Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Configuration.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Configuration.h
00006  *
00007  *  $Id: Configuration.h,v 1.1.1.4.2.2 2003/06/12 12:42:24 chad Exp $
00008  *
00009  *  @author Chris Hafey <chafey@stentor.com>
00010  *
00011  *  The ACE configuration API provides a portable abstraction for
00012  *  program configuration similar to the Microsoft Windows registry.
00013  *  The API supports a tree based hierarchy of configuration sections.  Each
00014  *  section contains other sections or values.  Values may contain string,
00015  *  unsigned integer and binary data.
00016  *
00017  *  @note These classes are not thread safe, if multiple threads use these
00018  *  classes, you are responsible for serializing access.
00019  *
00020  *  For examples of using this class, see:
00021  *   -# The test code in ACE_wrappers/test
00022  *   -# wxConfigViewer, a Windows like Registry Editor for ACE_Configuration
00023  *   -# TAO's IFR, it makes extensive use of ACE_Configuration
00024  *
00025  *  @todo Templatize this class with an ACE_LOCK to provide thread safety
00026  *
00027  */
00028 //=============================================================================
00029 
00030 #ifndef ACE_CONFIGURATION_H
00031 #define ACE_CONFIGURATION_H
00032 #include "ace/pre.h"
00033 
00034 #include "ace/SString.h"
00035 #include "ace/Hash_Map_With_Allocator_T.h"
00036 #include "ace/Malloc.h"
00037 
00038 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00039 # pragma once
00040 #endif /* ACE_LACKS_PRAGMA_ONCE */
00041 
00042 // configurable parameters
00043 
00044 #if !defined (ACE_CONFIG_SECTION_INDEX)
00045 #  define ACE_CONFIG_SECTION_INDEX "Config_Section_Index"
00046 #endif /* ! ACE_CONFIG_SECTION_INDEX */
00047 
00048 #if !defined (ACE_DEFAULT_CONFIG_SECTION_SIZE)
00049 #define ACE_DEFAULT_CONFIG_SECTION_SIZE 16
00050 #endif /* ACE_DEFAULT_CONFIG_SECTION_SIZE */
00051 
00052 /**
00053  * @class ACE_Section_Key_Internal
00054  *
00055  * @internal
00056  *
00057  * @brief A base class for internal handles to section keys for
00058  * configuration implementations
00059  *
00060  * Implementations subclass this base class to represent a
00061  * section key.
00062  *
00063  */
00064 class ACE_Export ACE_Section_Key_Internal
00065 {
00066 public:
00067   /// Virtual destructor, make sure descendants are virtual!
00068   virtual ~ACE_Section_Key_Internal (void);
00069 
00070   /// Increment reference count
00071   virtual int add_ref (void);
00072 
00073   /// Decrement reference count.  Will delete this if count gets to 0
00074   virtual int dec_ref (void);
00075 protected:
00076   ACE_Section_Key_Internal (void);
00077   ACE_Section_Key_Internal (const ACE_Section_Key_Internal& rhs);
00078   ACE_Section_Key_Internal& operator= (ACE_Section_Key_Internal& rhs);
00079 
00080   u_int ref_count_;
00081 };
00082 
00083 /**
00084  * @class ACE_Configuration_Section_Key
00085  *
00086  * @brief Reference counted wrapper for ACE_Section_Key_Internal.
00087  *
00088  * Reference counted wrapper class for the abstract internal
00089  * section key.  A user gets one of these to represent a section
00090  * in the configuration database.
00091  */
00092 class ACE_Export ACE_Configuration_Section_Key
00093 {
00094   friend class ACE_Configuration;
00095 public:
00096   /// Default constructor.
00097   ACE_Configuration_Section_Key (void);
00098 
00099   /// Constructor that initializes to a pointer to a concrete internal key.
00100   /**
00101    * @param key The section key to reference. Calls add_ref() with @a key.
00102    */
00103   ACE_EXPLICIT ACE_Configuration_Section_Key (ACE_Section_Key_Internal *key);
00104 
00105   /// Copy constructor, increments the reference count on the key.
00106   ACE_Configuration_Section_Key (const ACE_Configuration_Section_Key &rhs);
00107 
00108   /// Destructor, decrements reference count on the referenced key.
00109   ~ACE_Configuration_Section_Key (void);
00110 
00111   /// Assignment operator, increments reference count for this object
00112   /// and decrements it on @a rhs.
00113   ACE_Configuration_Section_Key &
00114     operator= (const ACE_Configuration_Section_Key &rhs);
00115 private:
00116   ACE_Section_Key_Internal *key_;
00117 };
00118 
00119 /**
00120  * @class ACE_Configuration
00121  *
00122  * @internal
00123  *
00124  * @brief Base class for configuration databases
00125  *
00126  * This class provides an interface for configuration databases. A concrete
00127  * class is required that implements the interface.
00128  *
00129  * @sa ACE_Configuration_Heap
00130  * @sa ACE_Configuration_Win32Registry
00131  */
00132 class ACE_Export ACE_Configuration
00133 {
00134 public:
00135   /// Enumeration for the various types of values we can store.
00136   enum VALUETYPE
00137   {
00138     STRING,
00139     INTEGER,
00140     BINARY,
00141     INVALID
00142   };
00143 
00144   /// Destructor
00145   virtual ~ACE_Configuration (void);
00146 
00147   /// Obtain a reference to the root section of this configuration.
00148   /*
00149    * @return Reference to the configuration's root section. Note that
00150    *         it is a const reference.
00151    */
00152   virtual const ACE_Configuration_Section_Key& root_section (void) const;
00153 
00154   /**
00155    * Opens a named section in an existing section.
00156    *
00157    * @param base        Existing section in which to open the named section.
00158    * @param sub_section Name of the section to open.
00159    * @param create      If zero, the named section must exist. If non-zero,
00160    *                    the named section will be created if it does not exist.
00161    * @param result      Reference; receives the section key for the new
00162    *                    section.
00163    *
00164    * @retval   0 for success.
00165    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00166    */
00167   virtual int open_section (const ACE_Configuration_Section_Key &base,
00168                             const ACE_TCHAR *sub_section,
00169                             int create,
00170                             ACE_Configuration_Section_Key& result) = 0;
00171 
00172   /// Removes a named section.
00173   /**
00174    * @param key          Section key to remove the named section from.
00175    * @param sub_section  Name of the section to remove.
00176    * @param recursive    If non zero, any subkeys below @a sub_section are
00177    *                     removed as well.
00178    *
00179    * @retval   0 for success.
00180    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00181    */
00182   virtual int remove_section (const ACE_Configuration_Section_Key &key,
00183                               const ACE_TCHAR *sub_section,
00184                               int recursive) = 0;
00185 
00186   /**
00187    * Enumerates through the values in a section.
00188    *
00189    * @param key    Section key to iterate through.
00190    * @param index  Iteration position. Must be zero on the first call to
00191    *               iterate through @a key. Increment @a index by one on each
00192    *               successive call to this method.
00193    * @param name   Receives the value's name.
00194    * @param type   Receives the value's data type.
00195    *
00196    * @note  You may not delete or add values while enumerating.  If the
00197    *        section is modified during enumeration, results are undefined;
00198    *        you must restart the enumeration from index 0.
00199    *
00200    * @retval   0 for success, @a name and @a type are valid.
00201    * @retval   1 there are no more values in the section.
00202    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00203    */
00204   virtual int enumerate_values (const ACE_Configuration_Section_Key& key,
00205                                 int index,
00206                                 ACE_TString& name,
00207                                 VALUETYPE& type) = 0;
00208 
00209   /**
00210    * Enumerates through the subsections in a section.
00211    *
00212    * @param key    Section key to iterate through.
00213    * @param index  Iteration position. Must be zero on the first call to
00214    *               iterate through @a key. Increment @a index by one on each
00215    *               successive call to this method.
00216    * @param name   Receives the subsection's name.
00217    *
00218    * @note  You may not modify the @a key section while enumerating.  If the
00219    *        section is modified during enumeration, results are undefined;
00220    *        you must restart the enumeration from index 0.
00221    *
00222    * @retval   0 for success, @a name has a valid name.
00223    * @retval   1 there are no more subsections in the section.
00224    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00225    */
00226   virtual int enumerate_sections (const ACE_Configuration_Section_Key& key,
00227                                   int index, ACE_TString& name) = 0;
00228 
00229   /// Sets a string-typed value.
00230   /**
00231    * @param key     Configuration section to set the value in.
00232    * @param name    Name of the configuration value to set. If a value with
00233    *                the specified name exists, it is replaced.
00234    * @param value   The string to set the configuration value to.
00235    *
00236    * @retval   0 for success.
00237    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00238    */
00239   virtual int set_string_value (const ACE_Configuration_Section_Key& key,
00240                                 const ACE_TCHAR* name,
00241                                 const ACE_TString& value) = 0;
00242 
00243   /// Sets a integer-typed value.
00244   /**
00245    * @param key     Configuration section to set the value in.
00246    * @param name    Name of the configuration value to set. If a value with
00247    *                the specified name exists, it is replaced.
00248    * @param value   The integer to set the configuration value to.
00249    *
00250    * @retval   0 for success.
00251    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00252    */
00253   virtual int set_integer_value (const ACE_Configuration_Section_Key& key,
00254                                  const ACE_TCHAR* name,
00255                                  u_int value) = 0;
00256 
00257   /// Sets a binary-typed value.
00258   /**
00259    * @param key     Configuration section to set the value in.
00260    * @param name    Name of the configuration value to set. If a value with
00261    *                the specified name exists, it is replaced.
00262    * @param data    Pointer to the binary data for the value.
00263    * @param length  Number of bytes for the new value.
00264    *
00265    * @retval   0 for success.
00266    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00267    */
00268   virtual int set_binary_value (const ACE_Configuration_Section_Key& key,
00269                                 const ACE_TCHAR* name,
00270                                 const void* data,
00271                                 size_t length) = 0;
00272 
00273   /// Gets a string-typed value.
00274   /**
00275    * @param key     Configuration section to get the value from.
00276    * @param name    Name of the configuration value to get.
00277    * @param value   Receives the configuration value if it exists and
00278    *                has type STRING.
00279    *
00280    * @retval   0 for success.
00281    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00282    */
00283   virtual int get_string_value (const ACE_Configuration_Section_Key& key,
00284                                 const ACE_TCHAR* name,
00285                                 ACE_TString& value) = 0;
00286 
00287   /// Gets an integer-typed value.
00288   /**
00289    * @param key     Configuration section to get the value from.
00290    * @param name    Name of the configuration value to get.
00291    * @param value   Receives the configuration value if it exists and
00292    *                has type INTEGER.
00293    *
00294    * @retval   0 for success.
00295    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00296    */
00297   virtual int get_integer_value (const ACE_Configuration_Section_Key& key,
00298                                  const ACE_TCHAR* name,
00299                                  u_int& value) = 0;
00300 
00301   /// Gets a binary-typed value.
00302   /**
00303    * @param key     Configuration section to get the value from.
00304    * @param name    Name of the configuration value to get.
00305    * @param data    Receives a pointer to memory holding the binary data
00306    *                for the value. This method allocates the memory pointed
00307    *                to using operator new[]. The caller is responsible for
00308    *                freeing the memory using operator delete[].
00309    * @param length  Receives the number of bytes in the value.
00310    *
00311    * @retval   0 for success; caller is responsible for freeing the
00312    *             returned memory.
00313    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00314    */
00315   virtual int get_binary_value (const ACE_Configuration_Section_Key& key,
00316                                 const ACE_TCHAR* name,
00317                                 void*& data,
00318                                 size_t& length) = 0;
00319 
00320   /**
00321    * Retrieves the type of a named configuration value.
00322    *
00323    * @param key     Configuration section to look up the name in.
00324    * @param name    Name of the configuration value to get the type of.
00325    * @param type    Receives the data type of the named value, if it exists.
00326    *
00327    * @retval   0 for success.
00328    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00329    */
00330   virtual int find_value(const ACE_Configuration_Section_Key& key,
00331                          const ACE_TCHAR* name,
00332                          VALUETYPE& type) = 0;
00333 
00334   /// Removes a named value.
00335   /**
00336    * @param key     Configuration section to remove the named value from.
00337    * @param name    Name of the configuration value to remove.
00338    *
00339    * @retval   0 for success.
00340    * @retval  -1 for error; ACE_OS::last_error() retrieves error code.
00341    */
00342   virtual int remove_value (const ACE_Configuration_Section_Key& key,
00343                             const ACE_TCHAR* name) = 0;
00344 
00345   /**
00346    * Expands <path_in> to <key_out> from <key>.  If create is true,
00347    * the subsections are created.  Returns 0 on success, non zero on
00348    * error The path consists of sections separated by the backslash
00349    * '\' or forward slash '/'.
00350    * Returns 0 on success, -1 if <create) is 0 and the path refers
00351    * a nonexistant section
00352    */
00353   int expand_path (const ACE_Configuration_Section_Key& key,
00354                    const ACE_TString& path_in,
00355                    ACE_Configuration_Section_Key& key_out,
00356                    int create = 1);
00357 
00358   /**
00359    * @deprecated Exports the configuration database to filename.
00360    * If @a filename is already present, it is overwritten. This function is
00361    * deprecated and will be removed in a future version of ACE. Please use
00362    * either ACE_Registry_ImpExp or ACE_Ini_ImpExp instead.
00363    */
00364   int export_config (const ACE_TCHAR* filename);
00365 
00366   /**
00367    * @deprecated Imports the configuration database from filename.  Any
00368    * existing data is not removed. This function is deprecated and will be
00369    * removed in a future version of ACE. Please use ACE_Registry_ImpExp
00370    * or ACE_Ini_ImpExp instead.
00371    */
00372   int import_config (const ACE_TCHAR* filename);
00373 
00374   /**
00375    * Determine if the contents of this object is the same as the
00376    * contents of the object on the right hand side.
00377    * Returns 1 (True) if they are equal and 0 (False) if they are not equal
00378    */
00379   int operator==(const ACE_Configuration& rhs) const;
00380 
00381   /**
00382    * Determine if the contents of this object are different from the
00383    * contents of the object on the right hand side.
00384    * Returns 0 (False) if they are equal and 1 (True) if they are not equal
00385    */
00386   int operator!=(const ACE_Configuration& rhs) const {return !(*this == rhs);}
00387 
00388 protected:
00389   /// Default ctor
00390   ACE_Configuration (void);
00391 
00392   /// Resolves the internal key from a section key
00393   ACE_Section_Key_Internal* get_internal_key
00394     (const ACE_Configuration_Section_Key& key);
00395 
00396   /**
00397    * Tests to see if <name> is valid.  <name> must be < 255 characters
00398    * and not contain the path separator '\', brackets [] or = (maybe
00399    * just restrict to alphanumeric?) returns non zero if name is not
00400    * valid.  The path separator is allowed, except for the first character,
00401    * if <allow_path> is true.
00402    */
00403   int validate_name (const ACE_TCHAR* name, int allow_path = 0);
00404 
00405   // Not used
00406   ACE_Configuration (const ACE_Configuration& rhs);
00407   ACE_Configuration& operator= (const ACE_Configuration& rhs);
00408 
00409 
00410   ACE_Configuration_Section_Key root_;
00411 };
00412 
00413 #if defined (ACE_WIN32)
00414 
00415 /**
00416  * @class ACE_Section_Key_Win32
00417  *
00418  * @brief The Win32 registry implementation of an internal section key.
00419  *
00420  * Holds the HKEY for a section (registry key).
00421  */
00422 class ACE_Export ACE_Section_Key_Win32 : public ACE_Section_Key_Internal
00423 {
00424 public:
00425   /// Constructor based on an HKEY
00426   ACE_Section_Key_Win32 (HKEY hKey);
00427 
00428   HKEY hKey_;
00429 
00430 protected:
00431   /// Destructor - invokes <RegCloseKey>
00432   virtual ~ACE_Section_Key_Win32 (void);
00433 
00434   // Not used
00435   ACE_Section_Key_Win32 (const ACE_Section_Key_Win32& rhs);
00436   ACE_Section_Key_Win32& operator= (const ACE_Section_Key_Win32& rhs);
00437 };
00438 
00439 /**
00440  * @class ACE_Configuration_Win32Registry
00441  *
00442  * @brief The win32 registry implementation of a configuration database
00443  *
00444  * The win32 implementation basically makes calls through to the
00445  * registry functions. The API is very similar so very little
00446  * work must be done
00447  */
00448 class ACE_Export ACE_Configuration_Win32Registry : public ACE_Configuration
00449 {
00450 public:
00451 
00452   /**
00453    * Constructor for registry configuration database.  hKey is the
00454    * base registry key to attach to.  This class takes ownership of
00455    * hKey, it will invoke <RegCloseKey> on it upon destruction.
00456    */
00457   ACE_EXPLICIT ACE_Configuration_Win32Registry (HKEY hKey);
00458 
00459   /// Destructor
00460   virtual ~ACE_Configuration_Win32Registry (void);
00461 
00462   virtual int open_section (const ACE_Configuration_Section_Key& base,
00463                             const ACE_TCHAR* sub_section,
00464                             int create,
00465                             ACE_Configuration_Section_Key& result);
00466 
00467   virtual int remove_section (const ACE_Configuration_Section_Key& key,
00468                               const ACE_TCHAR* sub_section,
00469                               int recursive);
00470 
00471   virtual int enumerate_values (const ACE_Configuration_Section_Key& key,
00472                                 int index,
00473                                 ACE_TString& name,
00474                                 VALUETYPE& type);
00475 
00476   virtual int enumerate_sections (const ACE_Configuration_Section_Key& key,
00477                                   int index,
00478                                   ACE_TString& name);
00479 
00480   virtual int set_string_value (const ACE_Configuration_Section_Key& key,
00481                                 const ACE_TCHAR* name,
00482                                 const ACE_TString& value);
00483 
00484   virtual int set_integer_value (const ACE_Configuration_Section_Key& key,
00485                                  const ACE_TCHAR* name,
00486                                  u_int value);
00487 
00488   virtual int set_binary_value (const ACE_Configuration_Section_Key& key,
00489                                 const ACE_TCHAR* name,
00490                                 const void* data,
00491                                 size_t length);
00492 
00493   virtual int get_string_value (const ACE_Configuration_Section_Key& key,
00494                                 const ACE_TCHAR* name,
00495                                 ACE_TString& value);
00496 
00497   virtual int get_integer_value (const ACE_Configuration_Section_Key& key,
00498                                  const ACE_TCHAR* name,
00499                                  u_int& value);
00500 
00501   virtual int get_binary_value (const ACE_Configuration_Section_Key& key,
00502                                 const ACE_TCHAR* name,
00503                                 void*& data,
00504                                 size_t& length);
00505 
00506   virtual int find_value(const ACE_Configuration_Section_Key& key,
00507                          const ACE_TCHAR* name,
00508                          VALUETYPE& type);
00509 
00510   /// Removes the the value <name> from <key>.  returns non zero on error
00511   virtual int remove_value (const ACE_Configuration_Section_Key& key,
00512                             const ACE_TCHAR* name);
00513 
00514   /**
00515    * This method traverses <path> through <hKey>.  It is useful when
00516    * you want the HKEY for a specific registry key, especially when
00517    * initializing this implementation.  Caller is responsible for
00518    * closeing this key when it is no longer used.  If create is 1
00519    * (default) the keys are create if they don't already exist.
00520    * Returns 0 on error
00521    */
00522   static HKEY resolve_key (HKEY hKey,
00523                            const ACE_TCHAR* path,
00524                            int create = 1);
00525   virtual int operator== (const ACE_Configuration_Win32Registry &rhs) const;
00526   virtual int operator!= (const ACE_Configuration_Win32Registry &rhs) const;
00527 
00528 protected:
00529 
00530   /// Gets the HKEY for a configuration section
00531   int load_key (const ACE_Configuration_Section_Key& key, HKEY& hKey);
00532 
00533   // Not used
00534   ACE_Configuration_Win32Registry (void);
00535   ACE_Configuration_Win32Registry (const ACE_Configuration_Win32Registry& rhs);
00536   ACE_Configuration_Win32Registry& operator= (const ACE_Configuration_Win32Registry& rhs);
00537 };
00538 #endif /* ACE_WIN32 */
00539 
00540 // ACE_Allocator version
00541 
00542 typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_MMAP_MEMORY_POOL,
00543                                            ACE_SYNCH_MUTEX> >
00544         PERSISTENT_ALLOCATOR;
00545 typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_LOCAL_MEMORY_POOL,
00546                                            ACE_SYNCH_MUTEX> >
00547         HEAP_ALLOCATOR;
00548 
00549 /**
00550  * @class ACE_Configuration_ExtId
00551  *
00552  * @brief External ID for the section and value hash
00553  *
00554  * Contains a pointer to the section or value name.
00555  */
00556 class ACE_Export ACE_Configuration_ExtId
00557 {
00558 public:
00559   /// Defeault ctor
00560   ACE_Configuration_ExtId (void);
00561 
00562   /// Named constructor
00563   ACE_EXPLICIT ACE_Configuration_ExtId (const ACE_TCHAR* name);
00564 
00565   /// Copy ctor
00566   ACE_Configuration_ExtId (const ACE_Configuration_ExtId& rhs);
00567 
00568   /// destructor
00569   ~ACE_Configuration_ExtId (void);
00570 
00571   /// Assignment operator
00572   ACE_Configuration_ExtId& operator= (const ACE_Configuration_ExtId& rhs);
00573 
00574   /// Equality comparison operator (must match name_).
00575   int operator==  (const ACE_Configuration_ExtId &rhs) const;
00576 
00577   /// Inequality comparison operator.
00578   int operator!= (const ACE_Configuration_ExtId &rhs) const;
00579 
00580   /// Frees the name of the value.  needed since we don't know the
00581   /// allocator name_ was created in
00582   void free (ACE_Allocator *alloc);
00583 
00584   /// <hash> function is required in order for this class to be usable by
00585   /// ACE_Hash_Map_Manager.
00586   u_long hash  (void) const;
00587 
00588   // = Data members.
00589 
00590   const ACE_TCHAR * name_;
00591 
00592   // Accessors
00593   const ACE_TCHAR *name (void);
00594 };
00595 
00596 typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId, int>
00597         SUBSECTION_MAP;
00598 typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId,
00599                                 int,
00600                                 ACE_Hash<ACE_Configuration_ExtId>,
00601                                 ACE_Equal_To<ACE_Configuration_ExtId>,
00602                                 ACE_Null_Mutex>
00603         SUBSECTION_HASH;
00604 typedef ACE_Hash_Map_Entry<ACE_Configuration_ExtId, int>
00605         SUBSECTION_ENTRY;
00606 
00607 /**
00608  * @class ACE_Configuration_Value_IntId
00609  *
00610  * @brief The section hash table internal value class
00611  *
00612  * This class is present as the internal portion of a section's
00613  * value hash table It may store string, integer or binary data.
00614  */
00615 class ACE_Export ACE_Configuration_Value_IntId
00616 {
00617 public:
00618   /// Default constructor
00619   ACE_Configuration_Value_IntId (void);
00620 
00621   /// String constructor, takes ownership of string
00622   ACE_EXPLICIT ACE_Configuration_Value_IntId (ACE_TCHAR* string);
00623 
00624   /// Integer constructor
00625   ACE_EXPLICIT ACE_Configuration_Value_IntId (u_int integer);
00626 
00627   /// Binary constructor, takes ownership of data
00628   ACE_Configuration_Value_IntId (void* data, size_t length);
00629 
00630   /// Copy ctor
00631   ACE_Configuration_Value_IntId (const ACE_Configuration_Value_IntId& rhs);
00632 
00633   /// Destructor
00634   ~ACE_Configuration_Value_IntId (void);
00635 
00636   /// Assignment operator
00637   ACE_Configuration_Value_IntId& operator= (
00638     const ACE_Configuration_Value_IntId& rhs);
00639 
00640   void free (ACE_Allocator *alloc);
00641 
00642   // = Data members.
00643 
00644   /**
00645    * Points to the string value or binary data or IS the integer
00646    * Length is only used when type_ == BINARY
00647    */
00648   ACE_Configuration::VALUETYPE  type_;
00649   union {
00650     void *     ptr_;
00651     u_int      int_;
00652   }                             data_;
00653   size_t                        length_;
00654 };
00655 
00656 typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId,
00657                                     ACE_Configuration_Value_IntId>
00658         VALUE_MAP;
00659 typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId,
00660                                 ACE_Configuration_Value_IntId,
00661                                 ACE_Hash<ACE_Configuration_ExtId>,
00662                                 ACE_Equal_To<ACE_Configuration_ExtId>,
00663                                 ACE_Null_Mutex>
00664         VALUE_HASH;
00665 typedef ACE_Hash_Map_Entry<ACE_Configuration_ExtId,
00666                            ACE_Configuration_Value_IntId>
00667         VALUE_ENTRY;
00668 
00669 /**
00670  * @class ACE_Configuration_Section_IntId
00671  *
00672  * @brief The internal ID for a section hash table
00673  *
00674  * Contains a hash table containing value name/values
00675  */
00676 class ACE_Export ACE_Configuration_Section_IntId
00677 {
00678 public:
00679   /// Default ctor
00680   ACE_Configuration_Section_IntId (void);
00681 
00682   /// Named ctor
00683   ACE_EXPLICIT ACE_Configuration_Section_IntId (VALUE_MAP* value_hash_map,
00684                                                 SUBSECTION_MAP* section_hash_map);
00685 
00686   /// Copy ctor
00687   ACE_Configuration_Section_IntId (const ACE_Configuration_Section_IntId& rhs);
00688 
00689   /// Destructor
00690   ~ACE_Configuration_Section_IntId (void);
00691 
00692   /// Assignment operator
00693   ACE_Configuration_Section_IntId& operator= (
00694     const ACE_Configuration_Section_IntId& rhs);
00695 
00696   /// Frees the hash table and all its values
00697   void free (ACE_Allocator *alloc);
00698 
00699   // = Data Members.
00700   VALUE_MAP* value_hash_map_;
00701 
00702   SUBSECTION_MAP* section_hash_map_;
00703 };
00704 
00705 typedef ACE_Hash_Map_With_Allocator<ACE_Configuration_ExtId,
00706                                     ACE_Configuration_Section_IntId>
00707         SECTION_MAP;
00708 typedef ACE_Hash_Map_Manager_Ex<ACE_Configuration_ExtId,
00709                                 ACE_Configuration_Section_IntId,
00710                                 ACE_Hash<ACE_Configuration_ExtId>,
00711                                 ACE_Equal_To<ACE_Configuration_ExtId>,
00712                                 ACE_Null_Mutex>
00713         SECTION_HASH;
00714 typedef ACE_Hash_Map_Entry<ACE_Configuration_ExtId,
00715                            ACE_Configuration_Section_IntId>
00716         SECTION_ENTRY;
00717 
00718 /**
00719  * @class ACE_Configuration_Section_Key_Heap
00720  *
00721  * @brief Internal section key class for heap based configuration
00722  *    database.
00723  *
00724  *     Contains a value iterator and full path name of section.
00725  */
00726 class ACE_Export ACE_Configuration_Section_Key_Heap
00727   : public ACE_Section_Key_Internal
00728 {
00729 public:
00730   /// Constructor based on the full path of the section
00731   ACE_Configuration_Section_Key_Heap (const ACE_TCHAR* path);
00732 
00733   /// The path itself
00734   ACE_TCHAR* path_;
00735 
00736   /// The value iterator
00737   VALUE_HASH::ITERATOR* value_iter_;
00738 
00739   /// The sub section iterator
00740   SUBSECTION_HASH::ITERATOR* section_iter_;
00741 protected:
00742   /// Destructor - will delete the iterators
00743   virtual ~ACE_Configuration_Section_Key_Heap (void);
00744 
00745   // Not used
00746   ACE_Configuration_Section_Key_Heap (const ACE_Configuration_Section_Key_Heap& rhs);
00747   ACE_Configuration_Section_Key_Heap& operator= (const ACE_Configuration_Section_Key_Heap& rhs);
00748 };
00749 
00750 /**
00751  * @class ACE_Configuration_Heap
00752  *
00753  * @brief The concrete implementation of a allocator based
00754  * configuration database
00755  *
00756  * This class uses ACE's Allocators to manage a memory
00757  * representation of a configuraiton database. A persistent heap
00758  * may be used to store configurations persistently
00759  *
00760  * Note: Before using this class you must call one of the open methods.
00761  *
00762  * @todo
00763  *  - Need to investigate what happens if memory mapped file gets mapped to
00764  *    a location different than it was created with.
00765  */
00766 class ACE_Export ACE_Configuration_Heap : public ACE_Configuration
00767 {
00768 public:
00769 
00770   /// Default ctor
00771   ACE_Configuration_Heap (void);
00772 
00773   /// Destructor
00774   virtual ~ACE_Configuration_Heap (void);
00775 
00776   /// Opens a configuration based on a file name
00777   int open (const ACE_TCHAR* file_name,
00778             void* base_address = ACE_DEFAULT_BASE_ADDR,
00779             int default_map_size = ACE_DEFAULT_CONFIG_SECTION_SIZE);
00780 
00781   /// Opens a heap based configuration
00782   int open (int default_map_size = ACE_DEFAULT_CONFIG_SECTION_SIZE);
00783 
00784   virtual int open_section (const ACE_Configuration_Section_Key& base,
00785                             const ACE_TCHAR* sub_section,
00786                             int create, ACE_Configuration_Section_Key& result);
00787 
00788   virtual int remove_section (const ACE_Configuration_Section_Key& key,
00789                               const ACE_TCHAR* sub_section,
00790                               int recursive);
00791 
00792   virtual int enumerate_values (const ACE_Configuration_Section_Key& key,
00793                                 int index,
00794                                 ACE_TString& name,
00795                                 VALUETYPE& type);
00796 
00797   virtual int enumerate_sections (const ACE_Configuration_Section_Key& key,
00798                                   int index,
00799                                   ACE_TString& name);
00800 
00801   virtual int set_string_value (const ACE_Configuration_Section_Key& key,
00802                                 const ACE_TCHAR* name,
00803                                 const ACE_TString& value);
00804 
00805   virtual int set_integer_value (const ACE_Configuration_Section_Key& key,
00806                                  const ACE_TCHAR* name,
00807                                  u_int value);
00808 
00809   virtual int set_binary_value (const ACE_Configuration_Section_Key& key,
00810                                 const ACE_TCHAR* name,
00811                                 const void* data,
00812                                 size_t length);
00813 
00814   virtual int get_string_value (const ACE_Configuration_Section_Key& key,
00815                                 const ACE_TCHAR* name,
00816                                 ACE_TString& value);
00817 
00818   virtual int get_integer_value (const ACE_Configuration_Section_Key& key,
00819                                  const ACE_TCHAR* name,
00820                                  u_int& value);
00821 
00822   virtual int get_binary_value (const ACE_Configuration_Section_Key& key,
00823                                 const ACE_TCHAR* name,
00824                                 void* &data,
00825                                 size_t &length);
00826 
00827   virtual int find_value(const ACE_Configuration_Section_Key& key,
00828                          const ACE_TCHAR* name,
00829                          VALUETYPE& type);
00830 
00831   /// Removes the the value <name> from <key>.  returns non zero on error
00832   virtual int remove_value (const ACE_Configuration_Section_Key& key,
00833                             const ACE_TCHAR* name);
00834 
00835 private:
00836   /// <sub_section> may not contain path separators
00837   int open_simple_section (const ACE_Configuration_Section_Key &base,
00838                             const ACE_TCHAR *sub_section,
00839                             int create, ACE_Configuration_Section_Key &result);
00840   /// Adds a new section
00841   int add_section (const ACE_Configuration_Section_Key &base,
00842                    const ACE_TCHAR *sub_section,
00843                    ACE_Configuration_Section_Key &result);
00844 
00845   /// Helper for the <open> method.
00846   int create_index (void);
00847 
00848   /// Helper for create_index() method: places hash table into an
00849   /// allocated space.
00850   int create_index_helper (void *buffer);
00851 
00852   int value_open_helper (size_t hash_table_size, void *buffer);
00853 
00854   int section_open_helper (size_t hash_table_size, void *buffer);
00855 
00856   int load_key (const ACE_Configuration_Section_Key& key, ACE_TString& name);
00857 
00858   int new_section (const ACE_TString& section,
00859                    ACE_Configuration_Section_Key& result);
00860 
00861   ACE_Configuration_Heap (const ACE_Configuration_Heap& rhs);
00862   ACE_Configuration_Heap& operator= (const ACE_Configuration_Heap& rhs);
00863 
00864   ACE_Allocator *allocator_;
00865   SECTION_MAP *index_;
00866   int default_map_size_;
00867 };
00868 
00869 #include "ace/post.h"
00870 #endif /* ACE_CONFIGURATION_H */

Generated on Mon Jun 16 11:19:24 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002