# ACE_Configuration Class Reference

Base class for configuration databases. More...

`#include <Configuration.h>`

Inheritance diagram for ACE_Configuration:

[legend]
Collaboration diagram for ACE_Configuration:

[legend]
List of all members.

## Public Types

enum | VALUETYPE { STRING, INTEGER, BINARY, INVALID }
| Enumeration for the various types of values we can store. More...

## Public Member Functions

virtual | ~ACE_Configuration (void)
| Destructor.
virtual const ACE_Configuration_Section_Key & | root_section (void) const
| Obtain a reference to the root section of this configuration.
virtual int | open_section (const ACE_Configuration_Section_Key &base, const ACE_TCHAR *sub_section, int create, ACE_Configuration_Section_Key &result)=0
virtual int | remove_section (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *sub_section, int recursive)=0
| Removes a named section.
virtual int | enumerate_values (const ACE_Configuration_Section_Key &key, int index, ACE_TString &name, VALUETYPE &type)=0
virtual int | enumerate_sections (const ACE_Configuration_Section_Key &key, int index, ACE_TString &name)=0
virtual int | set_string_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, const ACE_TString &value)=0
| Sets a string-typed value.
virtual int | set_integer_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, u_int value)=0
| Sets a integer-typed value.
virtual int | set_binary_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, const void *data, size_t length)=0
| Sets a binary-typed value.
virtual int | get_string_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, ACE_TString &value)=0
| Gets a string-typed value.
virtual int | get_integer_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, u_int &value)=0
| Gets an integer-typed value.
virtual int | get_binary_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, void *&data, size_t &length)=0
| Gets a binary-typed value.
virtual int | find_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, VALUETYPE &type)=0
virtual int | remove_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name)=0
| Removes a named value.
int | expand_path (const ACE_Configuration_Section_Key &key, const ACE_TString &path_in, ACE_Configuration_Section_Key &key_out, int create=1)
int | export_config (const ACE_TCHAR *filename)
int | import_config (const ACE_TCHAR *filename)
bool | operator== (const ACE_Configuration &rhs) const
bool | operator!= (const ACE_Configuration &rhs) const

## Static Public Attributes

ACE_TCHAR | NULL_String_ = '\0'

## Protected Member Functions

| ACE_Configuration (void)
| Default ctor.
ACE_Section_Key_Internal * | get_internal_key (const ACE_Configuration_Section_Key &key)
| Resolves the internal key from a section key.
int | validate_name (const ACE_TCHAR *name, int allow_path=0)
int | validate_value_name (const ACE_TCHAR *name)
| ACE_Configuration (const ACE_Configuration &rhs)
ACE_Configuration & | operator= (const ACE_Configuration &rhs)

## Protected Attributes

ACE_Configuration_Section_Key | root_

## Detailed Description

Base class for configuration databases.

For internal use only.

This class provides an interface for configuration databases. A concrete class is required that implements the interface.

See also:
  ACE_Configuration_Heap

  ACE_Configuration_Win32Registry

## Member Enumeration Documentation

enum ACE_Configuration::VALUETYPE

Enumeration for the various types of values we can store.

Enumeration values:

  STRING |
  INTEGER |
  BINARY |
  INVALID |

## Constructor & Destructor Documentation

ACE_Configuration::~ACE_Configuration | ( | void |  | ) | `[virtual]`

| Destructor.

ACE_Configuration::ACE_Configuration | ( | void |  | ) | `[protected]`

| Default ctor.

ACE_Configuration::ACE_Configuration | ( | const ACE_Configuration & | rhs | ) | `[protected]`

## Member Function Documentation

virtual int ACE_Configuration::enumerate_sections | ( | const ACE_Configuration_Section_Key & | key,
|  | int | index,
|  | ACE_TString & | name
| ) | `[pure virtual]`

Enumerates through the subsections in a section.

Parameters:

  | key | Section key to iterate through.
  | index | Iteration position. Must be zero on the first call to iterate through key. Increment index by one on each successive call to this method.
  | name | Receives the subsection's name.

Note:
  You may not modify the key section while enumerating. If the section is modified during enumeration, results are undefined; you must restart the enumeration from index 0.

Return values:

  | 0 | for success, name has a valid name.
  | 1 | there are no more subsections in the section.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

virtual int ACE_Configuration::enumerate_values | ( | const ACE_Configuration_Section_Key & | key,
|  | int | index,
|  | ACE_TString & | name,
|  | VALUETYPE & | type
| ) | `[pure virtual]`

Enumerates through the values in a section.

Parameters:

  | key | Section key to iterate through.
  | index | Iteration position. Must be zero on the first call to iterate through key. Increment index by one on each successive call to this method.
  | name | Receives the value's name.
  | type | Receives the value's data type.

Note:
  You may not delete or add values while enumerating. If the section is modified during enumeration, results are undefined; you must restart the enumeration from index 0.

Return values:

  | 0 | for success, name and type are valid.
  | 1 | there are no more values in the section.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

int ACE_Configuration::expand_path | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TString & | path_in,
|  | ACE_Configuration_Section_Key & | key_out,
|  | int | create = `1`
| ) |

| Expands <path_in> to <key_out> from <key>. If create is true, the subsections are created. Returns 0 on success, non zero on error The path consists of sections separated by the backslash '\' or forward slash '/'. Returns 0 on success, -1 if <create) is 0 and the path refers a nonexistant section

int ACE_Configuration::export_config | ( | const ACE_TCHAR * | filename | ) |

Deprecated:
  Exports the configuration database to filename. If filename is already present, it is overwritten. This function is deprecated and will be removed in a future version of ACE. Please use either ACE_Registry_ImpExp or ACE_Ini_ImpExp instead.

virtual int ACE_Configuration::find_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | VALUETYPE & | type
| ) | `[pure virtual]`

Retrieves the type of a named configuration value.

Parameters:

  | key | Configuration section to look up the name in.
  | name | Name of the configuration value to get the type of.
  | type | Receives the data type of the named value, if it exists.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

virtual int ACE_Configuration::get_binary_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | void *& | data,
|  | size_t & | length
| ) | `[pure virtual]`

Gets a binary-typed value.

Parameters:

  | key | Configuration section to get the value from.
  | name | Name of the configuration value to get.
  | data | Receives a pointer to memory holding the binary data for the value. This method allocates the memory pointed to using operator new[]. The caller is responsible for freeing the memory using operator delete[].
  | length | Receives the number of bytes in the value.

Return values:

  | 0 | for success; caller is responsible for freeing the returned memory.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

virtual int ACE_Configuration::get_integer_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | u_int & | value
| ) | `[pure virtual]`

Gets an integer-typed value.

Parameters:

  | key | Configuration section to get the value from.
  | name | Name of the configuration value to get.
  | value | Receives the configuration value if it exists and has type INTEGER.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

ACE_Section_Key_Internal * ACE_Configuration::get_internal_key | ( | const ACE_Configuration_Section_Key & | key | ) | `[protected]`

| Resolves the internal key from a section key.

virtual int ACE_Configuration::get_string_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | ACE_TString & | value
| ) | `[pure virtual]`

Gets a string-typed value.

Parameters:

  | key | Configuration section to get the value from.
  | name | Name of the configuration value to get.
  | value | Receives the configuration value if it exists and has type STRING.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

int ACE_Configuration::import_config | ( | const ACE_TCHAR * | filename | ) |

Deprecated:
  Imports the configuration database from filename. Any existing data is not removed. This function is deprecated and will be removed in a future version of ACE. Please use ACE_Registry_ImpExp or ACE_Ini_ImpExp instead.

virtual int ACE_Configuration::open_section | ( | const ACE_Configuration_Section_Key & | base,
|  | const ACE_TCHAR * | sub_section,
|  | int | create,
|  | ACE_Configuration_Section_Key & | result
| ) | `[pure virtual]`

Opens a named section in an existing section.

Parameters:

  | base | Existing section in which to open the named section.
  | sub_section | Name of the section to open.
  | create | If zero, the named section must exist. If non-zero, the named section will be created if it does not exist.
  | result | Reference; receives the section key for the new section.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

bool ACE_Configuration::operator!= | ( | const ACE_Configuration & | rhs | ) | const

| Determine if the contents of this object are different from the contents of the object on the right hand side. Returns 0 (False) if they are equal and 1 (True) if they are not equal

ACE_Configuration& ACE_Configuration::operator= | ( | const ACE_Configuration & | rhs | ) | `[protected]`

bool ACE_Configuration::operator== | ( | const ACE_Configuration & | rhs | ) | const

| Determine if the contents of this object is the same as the contents of the object on the right hand side. Returns 1 (True) if they are equal and 0 (False) if they are not equal

virtual int ACE_Configuration::remove_section | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | sub_section,
|  | int | recursive
| ) | `[pure virtual]`

Removes a named section.

Parameters:

  | key | Section key to remove the named section from.
  | sub_section | Name of the section to remove.
  | recursive | If non zero, any subkeys below sub_section are removed as well.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

virtual int ACE_Configuration::remove_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name
| ) | `[pure virtual]`

Removes a named value.

Parameters:

  | key | Configuration section to remove the named value from.
  | name | Name of the configuration value to remove.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

const ACE_Configuration_Section_Key & ACE_Configuration::root_section | ( | void |  | ) | const`[virtual]`

| Obtain a reference to the root section of this configuration.

virtual int ACE_Configuration::set_binary_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | const void * | data,
|  | size_t | length
| ) | `[pure virtual]`

Sets a binary-typed value.

Parameters:

  | key | Configuration section to set the value in.
  | name | Name of the configuration value to set. If a value with the specified name exists, it is replaced.
  | data | Pointer to the binary data for the value.
  | length | Number of bytes for the new value.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

virtual int ACE_Configuration::set_integer_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | u_int | value
| ) | `[pure virtual]`

Sets a integer-typed value.

Parameters:

  | key | Configuration section to set the value in.
  | name | Name of the configuration value to set. If a value with the specified name exists, it is replaced.
  | value | The integer to set the configuration value to.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

virtual int ACE_Configuration::set_string_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | const ACE_TString & | value
| ) | `[pure virtual]`

Sets a string-typed value.

Parameters:

  | key | Configuration section to set the value in.
  | name | Name of the configuration value to set. If a value with the specified name exists, it is replaced.
  | value | The string to set the configuration value to.

Return values:

  | 0 | for success.
  | -1 | for error; ACE_OS::last_error() retrieves error code.

Implemented in ACE_Configuration_Win32Registry, and ACE_Configuration_Heap.

int ACE_Configuration::validate_name | ( | const ACE_TCHAR * | name,
|  | int | allow_path = `0`
| ) | `[protected]`

| Tests to see if <name> is valid. <name> must be < 255 characters and not contain the path separator '\', brackets [] or = (maybe just restrict to alphanumeric?) returns non zero if name is not valid. The path separator is allowed, except for the first character, if <allow_path> is true.

int ACE_Configuration::validate_value_name | ( | const ACE_TCHAR * | name | ) | `[protected]`

| Test to see if <name> is valid. The default value for a key can be unnamed, which means either <name> is == 0 or <name> == '` is valid. Otherwise, it calls validate_name() to test <name> for the same rules that apply to keys.

## Member Data Documentation

ACE_TCHAR ACE_Configuration::NULL_String_ = '\0'`[static]`

| * Represents the "NULL" string to simplify the internal logic.

ACE_Configuration_Section_Key ACE_Configuration::root_ `[protected]`

The documentation for this class was generated from the following files:

- Configuration.h
- Configuration.cpp