00001 ////////////////////////////////////////////////////////////////////////////// 00002 /*! \file SystemProperties.h 00003 * \brief Defines the SystemProperties class -- a container for system-wide configuration parameters. 00004 * \author $Author: rsharo $ 00005 * \version $Revision: 1.3 $ 00006 * \date $Date: 2004/04/07 13:47:12 $ 00007 *//////////////////////////////////////////////////////////////////////////// 00008 #ifndef SYSTEM_PROPERTIES_H 00009 #define SYSTEM_PROPERTIES_H 00010 00011 #include "ace/Configuration.h" 00012 #include "ace/Auto_Ptr.h" 00013 #include <vector> 00014 #include <string> 00015 00016 // 00017 // The SystemProperties class provides access to key/value data 00018 // pairs that can be read from files or set from the program. 00019 // 00020 // The class is an extension of the ACE_Configuration interface 00021 // to improve usability. 00022 // SystemProperties can be read and written to files in two different formats. 00023 // 00024 // 00025 // An example of the INI format is as follows: 00026 // 00027 // [SectionName\SubsectionName\SubSubsectionName] 00028 // StringField = stringValue 00029 // 00030 // # This is a comment. 00031 // HexIntegerField = 0xa1b2c3d4 00032 // DecimalIntegerField = 100 00033 // OctalIntegerField = 077 00034 // "6-byte binary field" = "a1, b2, c3, d4, e5, f6" 00035 // MyBoolean = true 00036 // anotherBoolean = No 00037 // "Yet Another Boolean" = 1 00038 // DoubleFieldName = 3.1415 00039 // 00040 // Whitespace may be used to format INI-style files as long as the field names 00041 // start on the first character of a line. Whitespace must be quoted be be 00042 // interpreted as part of a field's name or value. 00043 // 00044 // 00045 // An example of the Registry format is as follows: 00046 // 00047 // [SectionName\SubsectionName\SubSubsectionName] 00048 // "A_StringField"="stringValue" 00049 // "An_IntegerField"=dword:a1b2c3d4 00050 // 00051 // # This is a comment. 00052 // "A_BinaryField"=hex:a1b2c3d4e5f6 00053 // "A BooleanField"="true" 00054 // "A_DoubleField"="3.1415" 00055 // 00056 // Registry-style files may not have any extra whitespace on a line. 00057 // 00058 // Note that Registry format only supports the valuetypes of INTEGER, 00059 // STRING, and BINARY. All fields read from an INI format file are 00060 // interpreted to have a valuetype of STRING. This class can coerce all 00061 // supported datatypes to and from strings, however. 00062 // 00063 class SystemProperties : public ACE_Configuration_Heap 00064 { 00065 public: 00066 typedef ACE_Configuration_Section_Key SectionKey_t; 00067 typedef ACE_Configuration::VALUETYPE Valuetype_t; 00068 00069 // 00070 // The default constructor. It constructs an empty SystemProperties object. 00071 SystemProperties(); 00072 00073 // 00074 // SystemProperties destructor. 00075 virtual ~SystemProperties() {} 00076 00077 // 00078 // Retrieve a singleton instance of the SystemProperties class. 00079 // When called for the first time, this method will attempt to open 00080 // and read the specified configuration file. This file is presumed 00081 // to be in the form of an INI file unless the registryFormat 00082 // argument is set to true. If it is set to true, then the file 00083 // is presumed to be in (WIN32) registry format. See ACE_Ini_ImpExp 00084 // and ACE_Registry_ImpExp for details on the file format. 00085 static SystemProperties *Instance( 00086 const char *configFilename="System.config", 00087 bool registryFormat=false); 00088 00089 // 00090 // Reads a string from the specified key in the properties. 00091 // If the section and key are found and can be read as a string, 00092 // then the value argument is set and the return value is zero. 00093 // Otherwise, the return value is -1. 00094 int GetStringEntry (const char *sectionName, const char *name, 00095 std::string &value); 00096 // 00097 // Reads an intger from the specified key in the properties. 00098 // If the section and key are found and can be read as an integer, 00099 // then the value argument is set and the return value is zero. 00100 // Otherwise, the return value is -1. 00101 int GetIntegerEntry(const char *sectionName, const char *name, 00102 unsigned int &value); 00103 // 00104 // Reads a double from the specified key in the properties. 00105 // If the section and key are found and can be read as a double, 00106 // then the value argument is set and the return value is zero. 00107 // Otherwise, the return value is -1. 00108 int GetDoubleEntry (const char *sectionName, const char *name, 00109 double &value); 00110 // 00111 // Reads a block of binary data from the specified key in the 00112 // properties. 00113 // If the section and key are found and can be read as a binary, 00114 // then the value argument is allocated and filled, the length 00115 // is set, and the return value is zero. 00116 // On failure, the return value is -1. 00117 // NOTE: The caller is responsible for deleting the block of 00118 // data returned on success! 00119 int GetBinaryEntry (const char *sectionName, const char *name, 00120 void *&value, size_t &length); 00121 // 00122 // Reads a boolean from the specified key in the properties. 00123 // If the section and key are found and can be interpreted as 00124 // a boolean, then the value argument is set and the return 00125 // value is zero. Otherwise, the return value is -1. 00126 // 00127 // Zero-valued integers and the case-insensitive strings "NO" and "FALSE" 00128 // are interpreted to mean a boolean false. All other strings and 00129 // integers are interpreted to mean true. 00130 int GetBooleanEntry(const char *sectionName, const char *name, 00131 bool &value); 00132 00133 // 00134 // Reads a string from the specified key in the properties. 00135 // If the section and key are found and can be read as a string, 00136 // then the value argument is set and the return value is zero. 00137 // Otherwise, the return value is -1. 00138 int GetStringEntry (const SectionKey_t &parent, const char *name, 00139 std::string &value); 00140 // 00141 // Reads an intger from the specified key in the properties. 00142 // If the section and key are found and can be read as an integer, 00143 // then the value argument is set and the return value is zero. 00144 // Otherwise, the return value is -1. 00145 int GetIntegerEntry(const SectionKey_t &parent, const char *name, 00146 unsigned int &value); 00147 // 00148 // Reads a double from the specified key in the properties. 00149 // If the section and key are found and can be read as a double, 00150 // then the value argument is set and the return value is zero. 00151 // Otherwise, the return value is -1. 00152 int GetDoubleEntry (const SectionKey_t &parent, const char *name, 00153 double &value); 00154 // 00155 // Reads a block of binary data from the specified key in the 00156 // properties. 00157 // If the section and key are found and can be read as a binary, 00158 // then the value argument is allocated and filled, the length 00159 // is set, and the return value is zero. 00160 // On failure, the return value is -1. 00161 // NOTE: The caller is responsible for deleting the block of 00162 // data returned on success! 00163 int GetBinaryEntry (const SectionKey_t &parent, const char *name, 00164 void *&value, size_t &length); 00165 // 00166 // Reads a boolean from the specified key in the properties. 00167 // If the section and key are found and can be interpreted as 00168 // a boolean, then the value argument is set and the return 00169 // value is zero. Otherwise, the return value is -1. 00170 // 00171 // Zero-valued integers and the case-insensitive strings "NO" and "FALSE" 00172 // are interpreted to mean a boolean false. All other strings and 00173 // integers are interpreted to mean true. 00174 int GetBooleanEntry (const SectionKey_t &parent, const char *name, 00175 bool &value); 00176 00177 // 00178 // Sets a field in the properties to a string value. 00179 // The sectionName argument is the absolute path to the section where the 00180 // field will reside. If the specified section doesn't already exist 00181 // it will be created. 00182 // The name argument is the name of the field to be set. 00183 // The value argument is the value which will be assigned to the field. 00184 // Returns 0 on success or -1 on failure. 00185 int SetStringEntry (const char *sectionName, const char *name, 00186 const char *value); 00187 00188 // 00189 // Sets a field in the properties to an integer value. 00190 // The sectionName argument is the absolute path to the section where the 00191 // field will reside. If the specified section doesn't already exist 00192 // it will be created. 00193 // The name argument is the name of the field to be set. 00194 // The value argument is the value which will be assigned to the field. 00195 // Returns 0 on success or -1 on failure. 00196 int SetIntegerEntry(const char *sectionName, const char *name, 00197 unsigned int value); 00198 00199 // 00200 // Sets a field in the properties to an integer value. 00201 // The sectionName argument is the absolute path to the section where the 00202 // field will reside. If the specified section doesn't already exist 00203 // it will be created. 00204 // The name argument is the name of the field to be set. 00205 // The value argument is the value which will be assigned to the field. 00206 // Returns 0 on success or -1 on failure. 00207 int SetDoubleEntry (const char *sectionName, const char *name, 00208 double value); 00209 00210 // 00211 // Sets a field in the properties to a binary value. 00212 // The sectionName argument is the absolute path to the section where the 00213 // field will reside. If the specified section doesn't already exist 00214 // it will be created. 00215 // The name argument is the name of the field to be set. 00216 // The value argument is a pointer to the value which will be assigned to 00217 // the field. 00218 // The length argument is the number of bytes in the binary value to be 00219 // stored. 00220 // Returns 0 on success or -1 on failure. 00221 int SetBinaryEntry (const char *sectionName, const char *name, 00222 const void *value, size_t length); 00223 00224 // 00225 // Sets a field in the properties to a boolean value. 00226 // The sectionName argument is the absolute path to the section where the 00227 // field will reside. If the specified section doesn't already exist 00228 // it will be created. 00229 // The name argument is the name of the field to be set. 00230 // The value argument is the value which will be assigned to the field. 00231 // Returns 0 on success or -1 on failure. 00232 int SetBooleanEntry (const char *sectionName, const char *name, 00233 bool value); 00234 00235 // 00236 // Sets a field in the properties to a string value. 00237 // The parent argument is the section key of the section where the field 00238 // will reside. Note that the section must already exist when this method 00239 // is called. 00240 // The name argument is the name of the field to be set. 00241 // The value argument is the value which will be assigned to the field. 00242 // Returns 0 on success or -1 on failure. 00243 int SetStringEntry (const SectionKey_t &parent, const char *name, 00244 const char *value); 00245 00246 // 00247 // Sets a field in the properties to an integer value. 00248 // The parent argument is the section key of the section where the field 00249 // will reside. Note that the section must already exist when this method 00250 // is called. 00251 // The name argument is the name of the field to be set. 00252 // The value argument is the value which will be assigned to the field. 00253 // Returns 0 on success or -1 on failure. 00254 int SetIntegerEntry(const SectionKey_t &parent, const char *name, 00255 unsigned int value); 00256 00257 // 00258 // Sets a field in the properties to a double value. 00259 // The parent argument is the section key of the section where the field 00260 // will reside. Note that the section must already exist when this method 00261 // is called. 00262 // The name argument is the name of the field to be set. 00263 // The value argument is the value which will be assigned to the field. 00264 // Returns 0 on success or -1 on failure. 00265 int SetDoubleEntry (const SectionKey_t &parent, const char *name, 00266 double value); 00267 00268 // 00269 // Sets a field in the properties to a binary value. 00270 // The parent argument is the section key of the section where the field 00271 // will reside. Note that the section must already exist when this method 00272 // is called. 00273 // The name argument is the name of the field to be set. 00274 // The value argument is a pointer to the value which will be assigned to 00275 // the field. 00276 // The length argument is the number of bytes in the binary value to be 00277 // stored. 00278 // Returns 0 on success or -1 on failure. 00279 int SetBinaryEntry (const SectionKey_t &parent, const char *name, 00280 const void *value, size_t length); 00281 00282 // 00283 // Sets a field in the properties to a boolean value. 00284 // The parent argument is the section key of the section where the field 00285 // will reside. Note that the section must already exist when this method 00286 // is called. 00287 // The name argument is the name of the field to be set. 00288 // The value argument is the value which will be assigned to the field. 00289 // Returns 0 on success or -1 on failure. 00290 int SetBooleanEntry (const SectionKey_t &parent, const char *name, 00291 bool value); 00292 00293 // 00294 // Given a section name, this method retrieves a key pointing 00295 // to that section. 00296 // 00297 // Section keys can be used to efficiently refer to the same 00298 // section repeatedly. 00299 // The sectionName argument is the name of the section to be 00300 // retrieved. The key argument will be set to the section key 00301 // If createNew is true and the specified section doesn't already 00302 // exist, it will be created. 00303 // Returns 0 on success or -1 on failure. 00304 int GetSectionKey(const char *sectionName, SectionKey_t &key, 00305 bool createNew=false); 00306 00307 // 00308 // Given a section key and the name of a subsection, this method retrieves 00309 // a key pointing to that subsection. 00310 // 00311 // Section keys can be used to efficiently refer to the same 00312 // section repeatedly. 00313 // The parent argument is the key of the section to which the sectionName 00314 // is relative. 00315 // The sectionName argument is the relative path to the subsection to be 00316 // retrieved. The key argument will be set to the section key 00317 // If createNew is true and the specified section doesn't already 00318 // exist, it will be created. 00319 // Returns 0 on success or -1 on failure. 00320 int GetSectionKey(const SectionKey_t &parent, const char *sectionName, 00321 SectionKey_t &key, bool createNew=false); 00322 00323 // 00324 // This method iterates through the top-level sections of the properties. 00325 // The index argument should be zero on the first call to EnumerateSections() 00326 // On each successful call, the name of a top-level section will be returned 00327 // in the name argument. Each successive call should be with an index 00328 // one higher than the last until no sections remain. 00329 // The return value is 0 on success with more sections remaining, 00330 // 1 on success with no more sections remaining, and -1 on error. 00331 int EnumerateSections(int index, std::string &name); 00332 00333 // 00334 // This method iterates through a subsection of the properties. 00335 // The index argument should be zero on the first call to 00336 // EnumerateSections(). 00337 // On each successful call, the name of an immediate subsection of the 00338 // parent key will be returned in the name argument. Each successive 00339 // call should be with an index one higher than the last until no 00340 // subsections remain. 00341 // The return value is 0 on success with more sections remaining, 00342 // 1 on success with no more sections remaining, and -1 on error. 00343 int EnumerateSections(const SectionKey_t &parent, int index, 00344 std::string &name); 00345 00346 // 00347 // This method iterates through the top-level fields of the properties. 00348 // Top-level fields are those that have no section name -- they are in 00349 // the "root section" of the properties. 00350 // The index argument should be zero on the first call to 00351 // EnumerateEntries(). 00352 // On each successful call, the name and valuetype of a field 00353 // will be returned in the name and valuetype arguments respectively. 00354 // Note that entries reported as a string can be interpreted as 00355 // virtually any data type -- this class knows how to coerce strings. 00356 // Each successive call should be with an index one higher than the last 00357 // until no sections remain. 00358 // The return value is 0 on success with more fields remaining, 00359 // 1 on success with no more fields remaining, and -1 on error. 00360 int EnumerateEntries(int index, std::string &name, 00361 Valuetype_t &valuetype); 00362 00363 // 00364 // This method iterates through the fields in one section of the properties. 00365 // The index argument should be zero on the first call to 00366 // EnumerateEntries(). 00367 // On each successful call, the name and valuetype of a field 00368 // will be returned in the name and valuetype arguments respectively. 00369 // Note that entries reported as a string can be interpreted as 00370 // virtually any data type -- this class knows how to coerce strings. 00371 // Each successive call should be with an index one higher than the last 00372 // until no sections remain. 00373 // The return value is 0 on success with more fields remaining, 00374 // 1 on success with no more fields remaining, and -1 on error. 00375 int EnumerateEntries(const SectionKey_t &parent, int index, 00376 std::string &name, Valuetype_t &valuetype); 00377 00378 // 00379 // This method parses a Registry-style property file and imports 00380 // its contents into the the system properties. The file's contents 00381 // are merged with any properties already held. Pre-existing fields 00382 // with the same name and section as fields from the file will be 00383 // overwritten. 00384 // 00385 // The method returns 0 on success and -1 on failure. 00386 int ImportPropertiesRegistry(const char * filename); 00387 00388 // 00389 // This method writes the contents of the SystemProperties object 00390 // to a file in Registry format. If the file already exists, it will 00391 // be overwritten. 00392 // The method returns 0 on success and -1 on failure. 00393 int ExportPropertiesRegistry(const char * filename); 00394 00395 // 00396 // This method parses an INI-style property file and imports 00397 // its contents into the the system properties. The file's contents 00398 // are merged with any properties already held. Pre-existing fields 00399 // with the same name and section as fields from the file will be 00400 // overwritten. 00401 // 00402 // The method returns 0 on success and -1 on failure. 00403 int ImportPropertiesIni(const char * filename); 00404 00405 // 00406 // This method writes the contents of the SystemProperties object 00407 // to a file in INI format. If the file already exists, it will 00408 // be overwritten. 00409 // The method returns 0 on success and -1 on failure. 00410 int ExportPropertiesIni(const char * filename); 00411 00412 protected: 00413 00414 static SystemProperties * m_pInstance; 00415 }; 00416 00417 #endif // SYSTEM_PROPERTIES_H 00418
1.3.9.1