ACE/ace/Configuration.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Configuration.h
   6  *
   7  *  @author Chris Hafey <chafey@stentor.com>
   8  *
   9  *  The ACE configuration API provides a portable abstraction for
  10  *  program configuration similar to the Microsoft Windows registry.
  11  *  The API supports a tree based hierarchy of configuration sections.  Each
  12  *  section contains other sections or values.  Values may contain string,
  13  *  unsigned integer and binary data.
  14  *
  15  *  @note These classes are not thread safe, if multiple threads use these
  16  *  classes, you are responsible for serializing access.
  17  *
  18  *  For examples of using this class, see:
  19  *   -# The test code in ACE_wrappers/test
  20  *   -# wxConfigViewer, a Windows like Registry Editor for ACE_Configuration
  21  *   -# TAO's IFR, it makes extensive use of ACE_Configuration
  22  *
  23  *  @todo Templatize this class with an ACE_LOCK to provide thread safety
  24  */
  25 //=============================================================================
  26
  27 #ifndef ACE_CONFIGURATION_H
  28 #define ACE_CONFIGURATION_H
  29 #include /**/ "ace/pre.h"
  30
  31 #include "ace/SStringfwd.h"
  32 #include "ace/Hash_Map_With_Allocator_T.h"
  33 #include "ace/Malloc_T.h"
  34 #include "ace/MMAP_Memory_Pool.h"
  35 #include "ace/Local_Memory_Pool.h"
  36 #include "ace/Synch_Traits.h"
  37
  38
  39 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  40 # pragma once
  41 #endif /* ACE_LACKS_PRAGMA_ONCE */
  42
  43 // configurable parameters
  44
  45 #if !defined (ACE_CONFIG_SECTION_INDEX)
  46 #  define ACE_CONFIG_SECTION_INDEX "Config_Section_Index"
  47 #endif /* ! ACE_CONFIG_SECTION_INDEX */
  48
  49 #if !defined (ACE_DEFAULT_CONFIG_SECTION_SIZE)
  50 #define ACE_DEFAULT_CONFIG_SECTION_SIZE 16
  51 #endif /* ACE_DEFAULT_CONFIG_SECTION_SIZE */
  52
  53 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  54
  55 /**
  56  * @class ACE_Section_Key_Internal
  57  *
  58  * @internal
  59  *
  60  * @brief A base class for internal handles to section keys for
  61  * configuration implementations
  62  *
  63  * Implementations subclass this base class to represent a
  64  * section key.
  65  */
  66 class ACE_Export ACE_Section_Key_Internal
  67 {
  68 public:
  69   /// Virtual destructor, make sure descendants are virtual!
  70   virtual ~ACE_Section_Key_Internal (void);
  71
  72   /// Increment reference count
  73   virtual int add_ref (void);
  74
  75   /// Decrement reference count.  Will delete this if count gets to 0
  76   virtual int dec_ref (void);
  77 protected:
  78   ACE_Section_Key_Internal (void);
  79   ACE_Section_Key_Internal (const ACE_Section_Key_Internal& rhs);
  80   ACE_Section_Key_Internal& operator= (ACE_Section_Key_Internal& rhs);
  81
  82   u_int ref_count_;
  83 };
  84
  85 /**
  86  * @class ACE_Configuration_Section_Key
  87  *
  88  * @brief Reference counted wrapper for ACE_Section_Key_Internal.
  89  *
  90  * Reference counted wrapper class for the abstract internal
  91  * section key.  A user gets one of these to represent a section
  92  * in the configuration database.
  93  */
  94 class ACE_Export ACE_Configuration_Section_Key
  95 {
  96   friend class ACE_Configuration;
  97 public:
  98   /// Default constructor.
  99   ACE_Configuration_Section_Key (void);
 100
 101   /// Constructor that initializes to a pointer to a concrete internal key.
 102   /**
 103    * @param key The section key to reference. Calls add_ref() with @a key.
 104    */
 105   explicit ACE_Configuration_Section_Key (ACE_Section_Key_Internal *key);
 106
 107   /// Copy constructor, increments the reference count on the key.
 108   ACE_Configuration_Section_Key (const ACE_Configuration_Section_Key &rhs);
 109
 110   /// Destructor, decrements reference count on the referenced key.
 111   ~ACE_Configuration_Section_Key (void);
 112
 113   /// Assignment operator, increments reference count for this object
 114   /// and decrements it on @a rhs.
 115   ACE_Configuration_Section_Key &
 116     operator= (const ACE_Configuration_Section_Key &rhs);
 117 private:
 118   ACE_Section_Key_Internal *key_;
 119 };
 120
 121 /**
 122  * @class ACE_Configuration
 123  *
 124  * @internal
 125  *
 126  * @brief Base class for configuration databases
 127  *
 128  * This class provides an interface for configuration databases. A concrete
 129  * class is required that implements the interface.
 130  *
 131  * @sa ACE_Configuration_Heap
 132  * @sa ACE_Configuration_Win32Registry
 133  */
 134 class ACE_Export ACE_Configuration
 135 {
 136 public:
 137   /// Enumeration for the various types of values we can store.
 138   enum VALUETYPE
 139   {
 140     STRING,
 141     INTEGER,
 142     BINARY,
 143     INVALID
 144   };
 145
 146   /// Destructor
 147   virtual ~ACE_Configuration (void);
 148
 149   /// Obtain a reference to the root section of this configuration.
 150   /*
 151    * @return Reference to the configuration's root section. Note that
 152    *         it is a const reference.
 153    */
 154   virtual const ACE_Configuration_Section_Key& root_section (void) const;
 155
 156   /**
 157    * Opens a named section in an existing section.
 158    *
 159    * @param base        Existing section in which to open the named section.
 160    * @param sub_section Name of the section to open.
 161    * @param create      If false, the named section must exist, otherwise
 162    *                    the named section will be created if it does not exist.
 163    * @param result      Reference; receives the section key for the new
 164    *                    section.
 165    *
 166    * @retval   0 for success.
 167    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 168    */
 169   virtual int open_section (const ACE_Configuration_Section_Key &base,
 170                             const ACE_TCHAR *sub_section,
 171                             bool create,
 172                             ACE_Configuration_Section_Key& result) = 0;
 173
 174   /// Removes a named section.
 175   /**
 176    * @param key          Section key to remove the named section from.
 177    * @param sub_section  Name of the section to remove.
 178    * @param recursive    If true, any subkeys below @a sub_section are
 179    *                     removed as well.
 180    *
 181    * @retval   0 for success.
 182    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 183    */
 184   virtual int remove_section (const ACE_Configuration_Section_Key &key,
 185                               const ACE_TCHAR *sub_section,
 186                               bool recursive) = 0;
 187
 188   /**
 189    * Enumerates through the values in a section.
 190    *
 191    * @param key    Section key to iterate through.
 192    * @param index  Iteration position. Must be zero on the first call to
 193    *               iterate through @a key. Increment @a index by one on each
 194    *               successive call to this method.
 195    * @param name   Receives the value's name.
 196    * @param type   Receives the value's data type.
 197    *
 198    * @note  You may not delete or add values while enumerating.  If the
 199    *        section is modified during enumeration, results are undefined;
 200    *        you must restart the enumeration from index 0.
 201    *
 202    * @retval   0 for success, @a name and @a type are valid.
 203    * @retval   1 there are no more values in the section.
 204    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 205    */
 206   virtual int enumerate_values (const ACE_Configuration_Section_Key& key,
 207                                 int index,
 208                                 ACE_TString& name,
 209                                 VALUETYPE& type) = 0;
 210
 211   /**
 212    * Enumerates through the subsections in a section.
 213    *
 214    * @param key    Section key to iterate through.
 215    * @param index  Iteration position. Must be zero on the first call to
 216    *               iterate through @a key. Increment @a index by one on each
 217    *               successive call to this method.
 218    * @param name   Receives the subsection's name.
 219    *
 220    * @note  You may not modify the @a key section while enumerating.  If the
 221    *        section is modified during enumeration, results are undefined;
 222    *        you must restart the enumeration from index 0.
 223    *
 224    * @retval   0 for success, @a name has a valid name.
 225    * @retval   1 there are no more subsections in the section.
 226    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 227    */
 228   virtual int enumerate_sections (const ACE_Configuration_Section_Key& key,
 229                                   int index, ACE_TString& name) = 0;
 230
 231   /// Sets a string-typed value.
 232   /**
 233    * @param key     Configuration section to set the value in.
 234    * @param name    Name of the configuration value to set. If a value with
 235    *                the specified name exists, it is replaced.
 236    * @param value   The string to set the configuration value to.
 237    *
 238    * @retval   0 for success.
 239    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 240    */
 241   virtual int set_string_value (const ACE_Configuration_Section_Key& key,
 242                                 const ACE_TCHAR* name,
 243                                 const ACE_TString& value) = 0;
 244
 245   /// Sets a integer-typed value.
 246   /**
 247    * @param key     Configuration section to set the value in.
 248    * @param name    Name of the configuration value to set. If a value with
 249    *                the specified name exists, it is replaced.
 250    * @param value   The integer to set the configuration value to.
 251    *
 252    * @retval   0 for success.
 253    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 254    */
 255   virtual int set_integer_value (const ACE_Configuration_Section_Key& key,
 256                                  const ACE_TCHAR* name,
 257                                  u_int value) = 0;
 258
 259   /// Sets a binary-typed value.
 260   /**
 261    * @param key     Configuration section to set the value in.
 262    * @param name    Name of the configuration value to set. If a value with
 263    *                the specified name exists, it is replaced.
 264    * @param data    Pointer to the binary data for the value.
 265    * @param length  Number of bytes for the new value.
 266    *
 267    * @retval   0 for success.
 268    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 269    */
 270   virtual int set_binary_value (const ACE_Configuration_Section_Key& key,
 271                                 const ACE_TCHAR* name,
 272                                 const void* data,
 273                                 size_t length) = 0;
 274
 275   /// Gets a string-typed value.
 276   /**
 277    * @param key     Configuration section to get the value from.
 278    * @param name    Name of the configuration value to get.
 279    * @param value   Receives the configuration value if it exists and
 280    *                has type STRING.
 281    *
 282    * @retval   0 for success.
 283    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 284    */
 285   virtual int get_string_value (const ACE_Configuration_Section_Key& key,
 286                                 const ACE_TCHAR* name,
 287                                 ACE_TString& value) = 0;
 288
 289   /// Gets an integer-typed value.
 290   /**
 291    * @param key     Configuration section to get the value from.
 292    * @param name    Name of the configuration value to get.
 293    * @param value   Receives the configuration value if it exists and
 294    *                has type INTEGER.
 295    *
 296    * @retval   0 for success.
 297    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 298    */
 299   virtual int get_integer_value (const ACE_Configuration_Section_Key& key,
 300                                  const ACE_TCHAR* name,
 301                                  u_int& value) = 0;
 302
 303   /// Gets a binary-typed value.
 304   /**
 305    * @param key     Configuration section to get the value from.
 306    * @param name    Name of the configuration value to get.
 307    * @param data    Receives a pointer to memory holding the binary data
 308    *                for the value. This method allocates the memory pointed
 309    *                to using operator new[]. The caller is responsible for
 310    *                freeing the memory using operator delete[].
 311    * @param length  Receives the number of bytes in the value.
 312    *
 313    * @retval   0 for success; caller is responsible for freeing the
 314    *             returned memory.
 315    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 316    */
 317   virtual int get_binary_value (const ACE_Configuration_Section_Key& key,
 318                                 const ACE_TCHAR* name,
 319                                 void*& data,
 320                                 size_t& length) = 0;
 321
 322   /**
 323    * Retrieves the type of a named configuration value.
 324    *
 325    * @param key     Configuration section to look up the name in.
 326    * @param name    Name of the configuration value to get the type of.
 327    * @param type    Receives the data type of the named value, if it exists.
 328    *
 329    * @retval   0 for success.
 330    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 331    */
 332   virtual int find_value(const ACE_Configuration_Section_Key& key,
 333                          const ACE_TCHAR* name,
 334                          VALUETYPE& type) = 0;
 335
 336   /// Removes a named value.
 337   /**
 338    * @param key     Configuration section to remove the named value from.
 339    * @param name    Name of the configuration value to remove.
 340    *
 341    * @retval   0 for success.
 342    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
 343    */
 344   virtual int remove_value (const ACE_Configuration_Section_Key& key,
 345                             const ACE_TCHAR* name) = 0;
 346
 347   /**
 348    * Expands @a path_in to @a key_out from @a key.  If create is true,
 349    * the subsections are created.  Returns 0 on success, non zero on
 350    * error The path consists of sections separated by the backslash
 351    * '\' or forward slash '/'.
 352    * Returns 0 on success, -1 if <create) is 0 and the path refers
 353    * a nonexistant section
 354    */
 355   int expand_path (const ACE_Configuration_Section_Key& key,
 356                    const ACE_TString& path_in,
 357                    ACE_Configuration_Section_Key& key_out,
 358                    bool create = true);
 359
 360   /**
 361    * Determine if the contents of this object is the same as the
 362    * contents of the object on the right hand side.
 363    * Returns true if they are equal and false if they are not equal
 364    */
 365   bool operator==(const ACE_Configuration& rhs) const;
 366
 367   /**
 368    * Determine if the contents of this object are different from the
 369    * contents of the object on the right hand side.
 370    * Returns false if they are equal and true if they are not equal
 371    */
 372   bool operator!=(const ACE_Configuration& rhs) const;
 373
 374   /**
 375    *    *  Represents the "NULL" string to simplify the internal logic.
 376    *       */
 377   static ACE_TCHAR NULL_String_;
 378
 379 protected:
 380   /// Default ctor
 381   ACE_Configuration (void);
 382
 383   /// Resolves the internal key from a section key
 384   ACE_Section_Key_Internal* get_internal_key
 385     (const ACE_Configuration_Section_Key& key);
 386
 387   /**
 388    * Tests to see if @a name is valid.  @a name must be < 255 characters
 389    * and not contain the path separator '\', brackets [] or = (maybe
 390    * just restrict to alphanumeric?) returns non zero if name is not
 391    * valid.  The path separator is allowed, except for the first character,
 392    * if @a allow_path is true.
 393    */
 394   int validate_name (const ACE_TCHAR* name, int allow_path = 0);
 395
 396   /**
 397    * Test to see if @a name is valid.  The default value for a key can be
 398    * unnamed, which means either @a name is == 0 or @a name == '\0` is
 399    * valid.  Otherwise, it calls validate_name() to test @a name for the
 400    * same rules that apply to keys.
 401    */
 402   int validate_value_name (const ACE_TCHAR* name);
 403
 404   // Not used
 405   ACE_Configuration (const ACE_Configuration& rhs);
 406   ACE_Configuration& operator= (const ACE_Configuration& rhs);
 407
 408
 409   ACE_Configuration_Section_Key root_;
 410 };
 411
 412 #if defined (ACE_WIN32) && !defined (ACE_LACKS_WIN32_REGISTRY)
 413
 414 /**
 415  * @class ACE_Section_Key_Win32
 416  *
 417  * @brief The Win32 registry implementation of an internal section key.
 418  *
 419  * Holds the HKEY for a section (registry key).
 420  */
 421 class ACE_Export ACE_Section_Key_Win32 : public ACE_Section_Key_Internal
 422 {
 423 public:
 424   /// Constructor based on an HKEY
 425   ACE_Section_Key_Win32 (HKEY hKey);
 426
 427   HKEY hKey_;
 428
 429 protected:
 430   /// Destructor - invokes <RegCloseKey>
 431   virtual ~ACE_Section_Key_Win32 (void);
 432
 433   // Not used
 434   ACE_Section_Key_Win32 (const ACE_Section_Key_Win32& rhs);
 435   ACE_Section_Key_Win32& operator= (const ACE_Section_Key_Win32& rhs);
 436 };
 437
 438 /**
 439  * @class ACE_Configuration_Win32Registry
 440  *
 441  * @brief The win32 registry implementation of a configuration database
 442  *
 443  * The win32 implementation basically makes calls through to the
 444  * registry functions. The API is very similar so very little
 445  * work must be done
 446  */
 447 class ACE_Export ACE_Configuration_Win32Registry : public ACE_Configuration
 448 {
 449 public:
 450   /**
 451    * Constructor for registry configuration database.  hKey is the
 452    * base registry key to attach to.  This class takes ownership of
 453    * hKey, it will invoke <RegCloseKey> on it upon destruction.
 454    */
 455   explicit ACE_Configuration_Win32Registry (HKEY hKey,
 456                                             u_long security_access = KEY_ALL_ACCESS);
 457
 458   /// Destructor
 459   virtual ~ACE_Configuration_Win32Registry (void);
 460
 461   virtual int open_section (const ACE_Configuration_Section_Key& base,
 462                             const ACE_TCHAR* sub_section,
 463                             bool create,
 464                             ACE_Configuration_Section_Key& result);
 465
 466   virtual int remove_section (const ACE_Configuration_Section_Key& key,
 467                               const ACE_TCHAR* sub_section,
 468                               bool recursive);
 469
 470   virtual int enumerate_values (const ACE_Configuration_Section_Key& key,
 471                                 int index,
 472                                 ACE_TString& name,
 473                                 VALUETYPE& type);
 474
 475   virtual int enumerate_sections (const ACE_Configuration_Section_Key& key,
 476                                   int index,
 477                                   ACE_TString& name);
 478
 479   virtual int set_string_value (const ACE_Configuration_Section_Key& key,
 480                                 const ACE_TCHAR* name,
 481                                 const ACE_TString& value);
 482
 483   virtual int set_integer_value (const ACE_Configuration_Section_Key& key,
 484                                  const ACE_TCHAR* name,
 485                                  u_int value);
 486
 487   virtual int set_binary_value (const ACE_Configuration_Section_Key& key,
 488                                 const ACE_TCHAR* name,
 489                                 const void* data,
 490                                 size_t length);
 491
 492   virtual int get_string_value (const ACE_Configuration_Section_Key& key,
 493                                 const ACE_TCHAR* name,
 494                                 ACE_TString& value);
 495
 496   virtual int get_integer_value (const ACE_Configuration_Section_Key& key,
 497                                  const ACE_TCHAR* name,
 498                                  u_int& value);
 499
 500   virtual int get_binary_value (const ACE_Configuration_Section_Key& key,
 501                                 const ACE_TCHAR* name,
 502                                 void*& data,
 503                                 size_t& length);
 504
 505   virtual int find_value(const ACE_Configuration_Section_Key& key,
 506                          const ACE_TCHAR* name,
 507                          VALUETYPE& type);
 508
 509   /// Removes the the value @a name from @a key.  returns non zero on error
 510   virtual int remove_value (const ACE_Configuration_Section_Key& key,
 511                             const ACE_TCHAR* name);
 512
 513   /**
 514    * This method traverses <path> through <hKey>.  It is useful when
 515    * you want the HKEY for a specific registry key, especially when
 516    * initializing this implementation.  Caller is responsible for
 517    * closeing this key when it is no longer used.  If create is 1
 518    * (default) the keys are create if they don't already exist.
 519    * Returns 0 on error
 520    */
 521   static HKEY resolve_key (HKEY hKey,
 522                            const ACE_TCHAR* path,
 523                            bool create = true,
 524                            u_long security_access = KEY_ALL_ACCESS);
 525   virtual bool operator== (const ACE_Configuration_Win32Registry &rhs) const;
 526   virtual bool operator!= (const ACE_Configuration_Win32Registry &rhs) const;
 527
 528 protected:
 529
 530   /// Gets the HKEY for a configuration section
 531   int load_key (const ACE_Configuration_Section_Key& key, HKEY& hKey);
 532
 533   // Not used
 534   ACE_Configuration_Win32Registry (void);
 535   ACE_Configuration_Win32Registry (const ACE_Configuration_Win32Registry& rhs);
 536   ACE_Configuration_Win32Registry& operator= (const ACE_Configuration_Win32Registry& rhs);
 537
 538   const u_long security_access_;
 539 };
 540 #endif /* ACE_WIN32 && !ACE_LACKS_WIN32_REGISTRY */
 541
 542 // ACE_Allocator version
 543
 544 typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_MMAP_MEMORY_POOL,
 545                                            ACE_SYNCH_MUTEX> >
 546         PERSISTENT_ALLOCATOR;
 547 typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_LOCAL_MEMORY_POOL,
 548                                            ACE_SYNCH_MUTEX> >
 549         HEAP_ALLOCATOR;
 550
 551 /**
 552  * @class ACE_Configuration_ExtId
 553  *
 554  * @brief External ID for the section and value hash
 555  *
 556  * Contains a pointer to the section or value name.
 557  */
 558 class ACE_Export ACE_Configuration_ExtId
 559 {
 560 public:
 561   /// Defeault ctor
 562   ACE_Configuration_ExtId (void);
 563
 564   /// Named constructor
 565   explicit ACE_Configuration_ExtId (const ACE_TCHAR* name);
 566
 567   /// Copy ctor
 568   ACE_Configuration_ExtId (const ACE_Configuration_ExtId& rhs);
 569
 570   /// destructor
 571   ~ACE_Configuration_ExtId (void);
 572
 573   /// Assignment operator
 574   ACE_Configuration_ExtId& operator= (const ACE_Configuration_ExtId& rhs);
 575
 576   /// Equality comparison operator (must match name_).
 577   bool operator==  (const ACE_Configuration_ExtId &rhs) const;
 578
 579   /// Inequality comparison operator.
 580   bool operator!= (const ACE_Configuration_ExtId &rhs) const;
 581
 582   /// Frees the name of the value.  needed since we don't know the
 583   /// allocator name_ was created in
 584   void free (ACE_Allocator *alloc);
 585
 586   /// hash function is required in order for this class to be usable by
 587   /// ACE_Hash_Map_Manager.
 588   u_long hash  (void) const;
 589
 590   // = Data members.
 591
 592   const ACE_TCHAR * name_;
 593
 594   // Accessors
 595   const ACE_TCHAR *name (void);
 596 };
 597
 598 typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId, int>
 599         SUBSECTION_MAP;
 600 typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId,
 601                                 int,
 602                                 ACE_Hash<ACE_Configuration_ExtId>,
 603                                 ACE_Equal_To<ACE_Configuration_ExtId>,
 604                                 ACE_Null_Mutex>
 605         SUBSECTION_HASH;
 606
 607 /**
 608  * @class ACE_Configuration_Value_IntId
 609  *
 610  * @brief The section hash table internal value class
 611  *
 612  * This class is present as the internal portion of a section's
 613  * value hash table It may store string, integer or binary data.
 614  */
 615 class ACE_Export ACE_Configuration_Value_IntId
 616 {
 617 public:
 618   /// Default constructor
 619   ACE_Configuration_Value_IntId (void);
 620
 621   /// String constructor, takes ownership of string
 622   explicit ACE_Configuration_Value_IntId (ACE_TCHAR* string);
 623
 624   /// Integer constructor
 625   explicit ACE_Configuration_Value_IntId (u_int integer);
 626
 627   /// Binary constructor, takes ownership of data
 628   ACE_Configuration_Value_IntId (void* data, size_t length);
 629
 630   /// Copy ctor
 631   ACE_Configuration_Value_IntId (const ACE_Configuration_Value_IntId& rhs);
 632
 633   /// Destructor
 634   ~ACE_Configuration_Value_IntId (void);
 635
 636   /// Assignment operator
 637   ACE_Configuration_Value_IntId& operator= (
 638     const ACE_Configuration_Value_IntId& rhs);
 639
 640   void free (ACE_Allocator *alloc);
 641
 642   // = Data members.
 643
 644   /**
 645    * Points to the string value or binary data or IS the integer
 646    * Length is only used when type_ == BINARY
 647    */
 648   ACE_Configuration::VALUETYPE  type_;
 649   union {
 650     void *     ptr_;
 651     u_int      int_;
 652   }                             data_;
 653   size_t                        length_;
 654 };
 655
 656 typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId,
 657                                     ACE_Configuration_Value_IntId>
 658         VALUE_MAP;
 659 typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId,
 660                                 ACE_Configuration_Value_IntId,
 661                                 ACE_Hash<ACE_Configuration_ExtId>,
 662                                 ACE_Equal_To<ACE_Configuration_ExtId>,
 663                                 ACE_Null_Mutex>
 664         VALUE_HASH;
 665
 666 // Deprecated typedef.  Use the VALUE_HASH::ENTRY trait instead.
 667 typedef VALUE_HASH::ENTRY VALUE_ENTRY;
 668
 669 /**
 670  * @class ACE_Configuration_Section_IntId
 671  *
 672  * @brief The internal ID for a section hash table
 673  *
 674  * Contains a hash table containing value name/values
 675  */
 676 class ACE_Export ACE_Configuration_Section_IntId
 677 {
 678 public:
 679   /// Default ctor
 680   ACE_Configuration_Section_IntId (void);
 681
 682   /// Named ctor
 683   ACE_Configuration_Section_IntId (VALUE_MAP* value_hash_map,
 684                                    SUBSECTION_MAP* section_hash_map);
 685
 686   /// Copy ctor
 687   ACE_Configuration_Section_IntId (const ACE_Configuration_Section_IntId& rhs);
 688
 689   /// Destructor
 690   ~ACE_Configuration_Section_IntId (void);
 691
 692   /// Assignment operator
 693   ACE_Configuration_Section_IntId& operator= (
 694     const ACE_Configuration_Section_IntId& rhs);
 695
 696   /// Frees the hash table and all its values
 697   void free (ACE_Allocator *alloc);
 698
 699   // = Data Members.
 700   VALUE_MAP* value_hash_map_;
 701
 702   SUBSECTION_MAP* section_hash_map_;
 703 };
 704
 705 typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId,
 706                                     ACE_Configuration_Section_IntId>
 707         SECTION_MAP;
 708 typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId,
 709                                 ACE_Configuration_Section_IntId,
 710                                 ACE_Hash<ACE_Configuration_ExtId>,
 711                                 ACE_Equal_To<ACE_Configuration_ExtId>,
 712                                 ACE_Null_Mutex>
 713         SECTION_HASH;
 714
 715 // Deprecated typedef.  Use the SECTION_HASH::ENTRY trait instead.
 716 typedef SECTION_HASH::ENTRY SECTION_ENTRY;
 717
 718 /**
 719  * @class ACE_Configuration_Section_Key_Heap
 720  *
 721  * @brief Internal section key class for heap based configuration
 722  *    database.
 723  *
 724  *     Contains a value iterator and full path name of section.
 725  */
 726 class ACE_Export ACE_Configuration_Section_Key_Heap
 727   : public ACE_Section_Key_Internal
 728 {
 729 public:
 730   /// Constructor based on the full path of the section
 731   ACE_Configuration_Section_Key_Heap (const ACE_TCHAR* path);
 732
 733   /// The path itself
 734   ACE_TCHAR* path_;
 735
 736   /// The value iterator
 737   VALUE_HASH::ITERATOR* value_iter_;
 738
 739   /// The sub section iterator
 740   SUBSECTION_HASH::ITERATOR* section_iter_;
 741
 742   ACE_ALLOC_HOOK_DECLARE;
 743
 744 protected:
 745   /// Destructor - will delete the iterators
 746   virtual ~ACE_Configuration_Section_Key_Heap (void);
 747
 748   // Not used
 749   ACE_Configuration_Section_Key_Heap (const ACE_Configuration_Section_Key_Heap& rhs);
 750   ACE_Configuration_Section_Key_Heap& operator= (const ACE_Configuration_Section_Key_Heap& rhs);
 751 };
 752
 753 /**
 754  * @class ACE_Configuration_Heap
 755  *
 756  * @brief The concrete implementation of a allocator based
 757  * configuration database
 758  *
 759  * This class uses ACE's Allocators to manage a memory
 760  * representation of a configuration database. A persistent heap
 761  * may be used to store configurations persistently
 762  *
 763  * @note Before using this class you must call one of the open methods.
 764  *
 765  * @todo
 766  *  - Need to investigate what happens if memory mapped file gets mapped to
 767  *    a location different than it was created with.
 768  */
 769 class ACE_Export ACE_Configuration_Heap : public ACE_Configuration
 770 {
 771 public:
 772   /// Default ctor
 773   ACE_Configuration_Heap (void);
 774
 775   /// Destructor
 776   virtual ~ACE_Configuration_Heap (void);
 777
 778   /**
 779    * Opens a configuration that allocates its memory from a memory-mapped file.
 780    * This makes it possible to persist a configuration to permanent storage.
 781    * This is not the same as exporting the configuration to a file; the
 782    * memory-mapped file is not likely to be very readable by humans.
 783    *
 784    * @param file_name    Name of the file to map into memory.
 785    *
 786    * @param base_address Address to map the base of @a file_name to.
 787    *
 788    * @param default_map_size Starting size for the internal hash tables that
 789    *                     contain configuration information.
 790    *
 791    * @retval 0 for success.
 792    * @retval -1 for error, with errno set to indicate the cause. If open()
 793    *            is called multiple times, errno will be @c EBUSY.
 794    */
 795   int open (const ACE_TCHAR* file_name,
 796             void* base_address = ACE_DEFAULT_BASE_ADDR,
 797             size_t default_map_size = ACE_DEFAULT_CONFIG_SECTION_SIZE);
 798
 799   /**
 800    * Opens a configuration that allocates memory from the heap.
 801    *
 802    * @param default_map_size Starting size for the internal hash tables that
 803    *                     contain configuration information.
 804    *
 805    * @retval 0 for success.
 806    * @retval -1 for error, with errno set to indicate the cause. If open()
 807    *            is called multiple times, errno will be @c EBUSY.
 808    */
 809   int open (size_t default_map_size = ACE_DEFAULT_CONFIG_SECTION_SIZE);
 810
 811   virtual int open_section (const ACE_Configuration_Section_Key& base,
 812                             const ACE_TCHAR* sub_section,
 813                             bool create, ACE_Configuration_Section_Key& result);
 814
 815   virtual int remove_section (const ACE_Configuration_Section_Key& key,
 816                               const ACE_TCHAR* sub_section,
 817                               bool recursive);
 818
 819   virtual int enumerate_values (const ACE_Configuration_Section_Key& key,
 820                                 int index,
 821                                 ACE_TString& name,
 822                                 VALUETYPE& type);
 823
 824   virtual int enumerate_sections (const ACE_Configuration_Section_Key& key,
 825                                   int index,
 826                                   ACE_TString& name);
 827
 828   virtual int set_string_value (const ACE_Configuration_Section_Key& key,
 829                                 const ACE_TCHAR* name,
 830                                 const ACE_TString& value);
 831
 832   virtual int set_integer_value (const ACE_Configuration_Section_Key& key,
 833                                  const ACE_TCHAR* name,
 834                                  u_int value);
 835
 836   virtual int set_binary_value (const ACE_Configuration_Section_Key& key,
 837                                 const ACE_TCHAR* name,
 838                                 const void* data,
 839                                 size_t length);
 840
 841   virtual int get_string_value (const ACE_Configuration_Section_Key& key,
 842                                 const ACE_TCHAR* name,
 843                                 ACE_TString& value);
 844
 845   virtual int get_integer_value (const ACE_Configuration_Section_Key& key,
 846                                  const ACE_TCHAR* name,
 847                                  u_int& value);
 848
 849   virtual int get_binary_value (const ACE_Configuration_Section_Key& key,
 850                                 const ACE_TCHAR* name,
 851                                 void* &data,
 852                                 size_t &length);
 853
 854   virtual int find_value(const ACE_Configuration_Section_Key& key,
 855                          const ACE_TCHAR* name,
 856                          VALUETYPE& type);
 857
 858   /// Removes the the value @a name from @a key.  returns non zero on error
 859   virtual int remove_value (const ACE_Configuration_Section_Key& key,
 860                             const ACE_TCHAR* name);
 861
 862 private:
 863   /// @a sub_section may not contain path separators
 864   int open_simple_section (const ACE_Configuration_Section_Key &base,
 865                            const ACE_TCHAR *sub_section,
 866                            bool create, ACE_Configuration_Section_Key &result);
 867   /// Adds a new section
 868   int add_section (const ACE_Configuration_Section_Key &base,
 869                    const ACE_TCHAR *sub_section,
 870                    ACE_Configuration_Section_Key &result);
 871
 872   /// Helper for the <open> method.
 873   int create_index (void);
 874
 875   /// Helper for create_index() method: places hash table into an
 876   /// allocated space.
 877   int create_index_helper (void *buffer);
 878
 879   int value_open_helper (size_t hash_table_size, void *buffer);
 880
 881   int section_open_helper (size_t hash_table_size, void *buffer);
 882
 883   int load_key (const ACE_Configuration_Section_Key& key, ACE_TString& name);
 884
 885   int new_section (const ACE_TString& section,
 886                    ACE_Configuration_Section_Key& result);
 887
 888   ACE_Configuration_Heap (const ACE_Configuration_Heap& rhs);
 889   ACE_Configuration_Heap& operator= (const ACE_Configuration_Heap& rhs);
 890
 891   ACE_Allocator *allocator_;
 892   SECTION_MAP *index_;
 893   size_t default_map_size_;
 894 };
 895
 896 ACE_END_VERSIONED_NAMESPACE_DECL
 897
 898 #if defined (__ACE_INLINE__)
 899 #include "ace/Configuration.inl"
 900 #endif /* __ACE_INLINE__ */
 901
 902 #include /**/ "ace/post.h"
 903 #endif /* ACE_CONFIGURATION_H */