1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
//-----------------------------------------------------------------------------
//
// 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