OpenZWave Library  1.4.2944
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
OpenZWave::Options Class Reference

Manages library options read from XML files or the command line. More...

#include <Options.h>

Public Types

enum  OptionType { OptionType_Invalid = 0, OptionType_Bool, OptionType_Int, OptionType_String }
 

Public Member Functions

bool Lock ()
 
bool AddOptionBool (string const &_name, bool const _default)
 
bool AddOptionInt (string const &_name, int32 const _default)
 
bool AddOptionString (string const &_name, string const &_default, bool const _append)
 
bool GetOptionAsBool (string const &_name, bool *o_value)
 
bool GetOptionAsInt (string const &_name, int32 *o_value)
 
bool GetOptionAsString (string const &_name, string *o_value)
 
OptionType GetOptionType (string const &_name)
 
bool AreLocked () const
 

Static Public Member Functions

static OptionsCreate (string const &_configPath, string const &_userPath, string const &_commandLine)
 
static bool Destroy ()
 
static OptionsGet ()
 

Detailed Description

Manages library options read from XML files or the command line.

A class that manages program options read from XML files or the command line. The OpenZWave Manager class requires a complete and locked Options object when created. The Options are therefore one of the first things that any OpenZWave application must deal with. Options are first read from an XML file called options.xml located in the User data folder (the path to which is supplied to the Options::Create method). This is the same folder that will be used by the Manager to save the state of each controller in the Z-Wave network, to avoid querying them for their entire state every time the application starts up. The second source of program options is a string, which will normally be the command line used to launch the application. In this way, common options can be specified in the XML, but over-ridden if necessary by the command line. The Options process is as follows: 1) Create an Options object, providing paths to the OpenZWave config folder, the User data folder and any command line string containing program options. 2) Call Options::AddOptionBool, Options::AddOptionInt or Options::AddOptionString to add any application-specific configurable options. In this way, the Options class can be used for non-OpenZWave options as well. (OpenZWave options must be specified in step #1 above (either via xml file or a command line string). 3) Call Options::Lock. This will cause the option values to be read from the options.xml file and the command line string, and will lock the options so that no more calls aside from GetOptionAs may be made. 4) Create the OpenZWave Manager object.

Member Enumeration Documentation

Enumerator
OptionType_Invalid 
OptionType_Bool 
OptionType_Int 
OptionType_String 

Member Function Documentation

bool Options::AddOptionBool ( string const &  _name,
bool const  _default 
)

Add a boolean option to the program. Adds an option to the program whose value can then be read from a file or command line. All calls to AddOptionInt must be made before Lock.

Parameters
_namethe name of the option. Option names are case insensitive and must be unique.
_defaultthe default value for this option.
See also
GetOptionAsBool
bool Options::AddOptionInt ( string const &  _name,
int32 const  _default 
)

Add an integer option to the program. Adds an option to the program whose value can then be read from a file or command line. All calls to AddOptionInt must be made before Lock.

Parameters
_namethe name of the option. Option names are case insensitive and must be unique.
_defaultthe default value for this option.
See also
GetOptionAsInt
bool Options::AddOptionString ( string const &  _name,
string const &  _default,
bool const  _append 
)

Add a string option to the program. Adds an option to the program whose value can then be read from a file or command line. All calls to AddOptionString must be made before Lock.

Parameters
_namethe name of the option. Option names are case insensitive and must be unique.
_defaultthe default value for this option.
_appendSetting append to true will cause values read from the command line or XML file to be concatenated into a comma delimited list. If _append is false, newer values will overwrite older ones.
See also
GetOptionAsString
bool OpenZWave::Options::AreLocked ( ) const
inline

Test whether the options have been locked.

Returns
true if the options have been locked.
See also
Lock
Options * Options::Create ( string const &  _configPath,
string const &  _userPath,
string const &  _commandLine 
)
static

Creates an object to manage the program options.

Parameters
_configPatha string containing the path to the OpenZWave library config folder, which contains XML descriptions of Z-Wave manufacturers and products.
_userPatha string containing the path to the application's user data folder where the OpenZWave should store the Z-Wave network configuration and state. The _userPath is also the folder where OpenZWave will look for the file Options.xml which contains program option values. The file should be in the form outlined below, with one or more Option elements containing a name and value attribute. Multiple values with the same option name should be listed separately. Note that option names are case insensitive.
<?xml version="1.0" encoding="utf-8"?>
<Options>
<Option name="logging" value="true" />
<Option name="ignore" value="COMMAND_CLASS_BASIC" />
<Option name="ignore" value="COMMAND_CLASS_VERSION" />
</Options>
_commandLinea string containing the program's command line options. Command line options are parsed after the options.xml file, and so take precedence. Options are identified by a leading – (two minus signs). The following items in the string are treated as values for this option, until the next – is reached. For boolean options only, it is possible to omit the value, in which case the value is assumed to be "true". Note that option names are case insensitive, and that option values should be separated by a space.
Returns
Pointer to the newly created Options object.
See also
Get, Destroy, AddOption, GetOptionAs, Lock
bool Options::Destroy ( )
static

Deletes the Options and cleans up any associated objects. The application is responsible for destroying the Options object, but this must not be done until after the Manager object has been destroyed.

Parameters
_optionsPointer to the Options object to be destroyed.
Returns
true if the Options object was destroyed. If the manager object still exists, this call will return false.
See also
Create, Get
static Options* OpenZWave::Options::Get ( )
inlinestatic

Gets a pointer to the Options singleton object.

Returns
a pointer to the Options singleton object.
See also
Create, Destroy
bool Options::GetOptionAsBool ( string const &  _name,
bool *  o_value 
)

Get the value of a boolean option.

Parameters
_namethe name of the option. Option names are case insensitive.
o_valuea pointer to the item that will be filled with the option value.
Returns
true if the option value was fetched successfully, false if the option does not exist, or does not contain a boolean value
See also
AddOptionBool, GetOptionType
bool Options::GetOptionAsInt ( string const &  _name,
int32 o_value 
)

Get the value of an integer option.

Parameters
_namethe name of the option. Option names are case insensitive.
o_valuea pointer to the item that will be filled with the option value.
Returns
true if the option value was fetched successfully, false if the option does not exist, or does not contain an integer value
See also
AddOptionInt, GetOptionType
bool Options::GetOptionAsString ( string const &  _name,
string *  o_value 
)

Get the value of a string option.

Parameters
_namethe name of the option. Option names are case insensitive.
o_valuea pointer to the item that will be filled with the option value.
Returns
true if the option value was fetched successfully, false if the option does not exist, or does not contain a string value
See also
AddOptionString, GetOptionType
Options::OptionType Options::GetOptionType ( string const &  _name)

Get the type of value stored in an option.

Parameters
_namethe name of the option. Option names are case insensitive.
Returns
An enum value representing the type of the option value. If the option does not exist, OptionType_Invalid is returned.
See also
GetOptionAsBool, GetOptionAsInt, GetOptionAsString
bool Options::Lock ( )

Locks the options. Reads in option values from the XML options file and command line string and marks the options as locked. Once locked, no more calls to AddOption can be made. The options must be locked before the Manager::Create method is called.

See also
AddOption

The documentation for this class was generated from the following files: