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 Options * | Create (string const &_configPath, string const &_userPath, string const &_commandLine)
static bool | Destroy ()
static Options * | Get ()

## 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

## OptionType

enum OpenZWave::Options::OptionType

Enumerator
OptionType_Invalid |
OptionType_Bool |
OptionType_Int |
OptionType_String |

## Member Function Documentation

## AddOptionBool()

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

  _name | the name of the option. Option names are case insensitive and must be unique.
  _default | the default value for this option.

See also
  GetOptionAsBool

## AddOptionInt()

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

  _name | the name of the option. Option names are case insensitive and must be unique.
  _default | the default value for this option.

See also
  GetOptionAsInt

## AddOptionString()

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

  _name | the name of the option. Option names are case insensitive and must be unique.
  _default | the default value for this option.
  _append | Setting 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

## AreLocked()

bool OpenZWave::Options::AreLocked | ( |  | ) | const

inline

Test whether the options have been locked.

Returns
  true if the options have been locked.

See also
  Lock

## Create()

Options * Options::Create | ( | string const & | _configPath,
|  | string const & | _userPath,
|  | string const & | _commandLine
| ) |  |

static

Creates an object to manage the program options.

Parameters

  _configPath | a string containing the path to the OpenZWave library config folder, which contains XML descriptions of Z-Wave manufacturers and products.

  _userPath

  a 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>

  _commandLine

  a 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

## Destroy()

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

  _options | Pointer 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

## Get()

static Options* OpenZWave::Options::Get | ( |  | ) |

inline static

Gets a pointer to the Options singleton object.

Returns
  a pointer to the Options singleton object.

See also
  Create, Destroy

## GetOptionAsBool()

bool Options::GetOptionAsBool | ( | string const & | _name,
|  | bool * | o_value
| ) |  |

Get the value of a boolean option.

Parameters

  _name | the name of the option. Option names are case insensitive.
  o_value | a 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

## GetOptionAsInt()

bool Options::GetOptionAsInt | ( | string const & | _name,
|  | int32 * | o_value
| ) |  |

Get the value of an integer option.

Parameters

  _name | the name of the option. Option names are case insensitive.
  o_value | a 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

## GetOptionAsString()

bool Options::GetOptionAsString | ( | string const & | _name,
|  | string * | o_value
| ) |  |

Get the value of a string option.

Parameters

  _name | the name of the option. Option names are case insensitive.
  o_value | a 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

## GetOptionType()

Options::OptionType Options::GetOptionType | ( | string const & | _name | ) |

Get the type of value stored in an option.

Parameters

  _name | the 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

## Lock()

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:

- Options.h
- Options.cpp