255 lines
11 KiB
C++
255 lines
11 KiB
C++
//-----------------------------------------------------------------------------
|
|
//
|
|
// Options.h
|
|
//
|
|
// Program options read from XML files or the command line.
|
|
//
|
|
// Copyright (c) 2010 Mal Lansell <openzwave@lansell.org>
|
|
//
|
|
// SOFTWARE NOTICE AND LICENSE
|
|
//
|
|
// This file is part of OpenZWave.
|
|
//
|
|
// OpenZWave is free software: you can redistribute it and/or modify
|
|
// it under the terms of the GNU Lesser General Public License as published
|
|
// by the Free Software Foundation, either version 3 of the License,
|
|
// or (at your option) any later version.
|
|
//
|
|
// OpenZWave is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
// GNU Lesser General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU Lesser General Public License
|
|
// along with OpenZWave. If not, see <http://www.gnu.org/licenses/>.
|
|
//
|
|
//-----------------------------------------------------------------------------
|
|
|
|
#ifndef _Options_H
|
|
#define _Options_H
|
|
|
|
#include <string>
|
|
#include <cstring>
|
|
#include <map>
|
|
|
|
#include "Defs.h"
|
|
|
|
namespace OpenZWave
|
|
{
|
|
/** \brief 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.
|
|
*/
|
|
class OPENZWAVE_EXPORT Options
|
|
{
|
|
public:
|
|
enum OptionType
|
|
{
|
|
OptionType_Invalid = 0,
|
|
OptionType_Bool,
|
|
OptionType_Int,
|
|
OptionType_String
|
|
};
|
|
|
|
/**
|
|
* Creates an object to manage the program options.
|
|
* \param _configPath a string containing the path to the OpenZWave library config
|
|
* folder, which contains XML descriptions of Z-Wave manufacturers and products.
|
|
* \param _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.
|
|
* \code
|
|
* <?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>
|
|
* \endcode
|
|
* \param _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.
|
|
* \return Pointer to the newly created Options object.
|
|
* \see Get, Destroy, AddOption, GetOptionAs, Lock
|
|
*/
|
|
static Options* Create( string const& _configPath, string const& _userPath, string const& _commandLine );
|
|
|
|
/**
|
|
* 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.
|
|
* \param _options Pointer to the Options object to be destroyed.
|
|
* \return true if the Options object was destroyed. If the manager
|
|
* object still exists, this call will return false.
|
|
* \see Create, Get
|
|
*/
|
|
static bool Destroy();
|
|
|
|
/**
|
|
* Gets a pointer to the Options singleton object.
|
|
* \return a pointer to the Options singleton object.
|
|
* \see Create, Destroy
|
|
*/
|
|
static Options* Get(){ return s_instance; }
|
|
|
|
/**
|
|
* 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 AddOption
|
|
*/
|
|
bool Lock();
|
|
|
|
/**
|
|
* 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.
|
|
* \param _name the name of the option. Option names are case insensitive and must be unique.
|
|
* \param _default the default value for this option.
|
|
* \see GetOptionAsBool
|
|
*/
|
|
bool AddOptionBool( string const& _name, bool 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.
|
|
* \param _name the name of the option. Option names are case insensitive and must be unique.
|
|
* \param _default the default value for this option.
|
|
* \see GetOptionAsInt
|
|
*/
|
|
bool AddOptionInt( string const& _name, int32 const _default );
|
|
|
|
/**
|
|
* 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.
|
|
* \param _name the name of the option. Option names are case insensitive and must be unique.
|
|
* \param _default the default value for this option.
|
|
* \param _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 GetOptionAsString
|
|
*/
|
|
bool AddOptionString( string const& _name, string const& _default, bool const _append );
|
|
|
|
/**
|
|
* Get the value of a boolean option.
|
|
* \param _name the name of the option. Option names are case insensitive.
|
|
* \param o_value a pointer to the item that will be filled with the option value.
|
|
* \return true if the option value was fetched successfully, false if the
|
|
* option does not exist, or does not contain a boolean value
|
|
* \see AddOptionBool, GetOptionType
|
|
*/
|
|
bool GetOptionAsBool( string const& _name, bool* o_value );
|
|
|
|
/**
|
|
* Get the value of an integer option.
|
|
* \param _name the name of the option. Option names are case insensitive.
|
|
* \param o_value a pointer to the item that will be filled with the option value.
|
|
* \return true if the option value was fetched successfully, false if the
|
|
* option does not exist, or does not contain an integer value
|
|
* \see AddOptionInt, GetOptionType
|
|
*/
|
|
bool GetOptionAsInt( string const& _name, int32* o_value );
|
|
|
|
/**
|
|
* Get the value of a string option.
|
|
* \param _name the name of the option. Option names are case insensitive.
|
|
* \param o_value a pointer to the item that will be filled with the option value.
|
|
* \return true if the option value was fetched successfully, false if the
|
|
* option does not exist, or does not contain a string value
|
|
* \see AddOptionString, GetOptionType
|
|
*/
|
|
bool GetOptionAsString( string const& _name, string* o_value );
|
|
|
|
/**
|
|
* Get the type of value stored in an option.
|
|
* \param _name the name of the option. Option names are case insensitive.
|
|
* \return An enum value representing the type of the option value. If the
|
|
* option does not exist, OptionType_Invalid is returned.
|
|
* \see GetOptionAsBool, GetOptionAsInt, GetOptionAsString
|
|
*/
|
|
OptionType GetOptionType( string const& _name );
|
|
|
|
/**
|
|
* Test whether the options have been locked.
|
|
* \return true if the options have been locked.
|
|
* \see Lock
|
|
*/
|
|
bool AreLocked()const{ return m_locked; }
|
|
|
|
|
|
private:
|
|
class Option
|
|
{
|
|
friend class Options;
|
|
|
|
public:
|
|
Option( string const& _name ): m_name( _name ), m_append( false ){}
|
|
bool SetValueFromString( string const& _value );
|
|
|
|
Options::OptionType m_type;
|
|
string m_name;
|
|
bool m_valueBool;
|
|
int32 m_valueInt;
|
|
string m_valueString;
|
|
bool m_append;
|
|
};
|
|
|
|
Options( string const& _configPath, string const& _userPath, string const& _commandLine ); // Constructor, to be called only via the static Create method.
|
|
~Options(); // Destructor, to be called only via the static Destroy method.
|
|
|
|
bool ParseOptionsString( string const& _options ); // Parse a string containing program options, such as a command line.
|
|
bool ParseOptionsXML( string const& _filename ); // Parse an XML file containing program options.
|
|
Option* AddOption( string const& _name ); // check lock and create (or open existing) option
|
|
Option* Find( string const& _name );
|
|
|
|
OPENZWAVE_EXPORT_WARNINGS_OFF
|
|
map<string,Option*> m_options; // Map of option names to values.
|
|
OPENZWAVE_EXPORT_WARNINGS_ON
|
|
string m_xml; // Path to XML options file.
|
|
string m_commandLine; // String containing command line options.
|
|
string m_SystemPath;
|
|
string m_LocalPath;
|
|
bool m_locked; // If true, the options are final and AddOption can no longer be called.
|
|
static Options* s_instance;
|
|
};
|
|
} // namespace OpenZWave
|
|
|
|
#endif // _Options_H
|