# ACE_Configuration_Heap Class Reference

The concrete implementation of a allocator based configuration database. More...

`#include <Configuration.h>`

Inheritance diagram for ACE_Configuration_Heap:

[legend]
Collaboration diagram for ACE_Configuration_Heap:

[legend]
List of all members.

## Public Member Functions

| ACE_Configuration_Heap (void)
| Default ctor.
virtual | ~ACE_Configuration_Heap (void)
| Destructor.
int | open (const ACE_TCHAR *file_name, void *base_address=ACE_DEFAULT_BASE_ADDR, size_t default_map_size=ACE_DEFAULT_CONFIG_SECTION_SIZE)
| Opens a configuration based on a file name.
int | open (size_t default_map_size=ACE_DEFAULT_CONFIG_SECTION_SIZE)
| Opens a heap based configuration.
virtual int | open_section (const ACE_Configuration_Section_Key &base, const ACE_TCHAR *sub_section, int create, ACE_Configuration_Section_Key &result)
virtual int | remove_section (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *sub_section, int recursive)
| Removes a named section.
virtual int | enumerate_values (const ACE_Configuration_Section_Key &key, int index, ACE_TString &name, VALUETYPE &type)
virtual int | enumerate_sections (const ACE_Configuration_Section_Key &key, int index, ACE_TString &name)
virtual int | set_string_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, const ACE_TString &value)
| Sets a string-typed value.
virtual int | set_integer_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, u_int value)
| 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)
| Sets a binary-typed value.
virtual int | get_string_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, ACE_TString &value)
| Gets a string-typed value.
virtual int | get_integer_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, u_int &value)
| 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)
| Gets a binary-typed value.
virtual int | find_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name, VALUETYPE &type)
virtual int | remove_value (const ACE_Configuration_Section_Key &key, const ACE_TCHAR *name)
| Removes the the value <name> from <key>. returns non zero on error.

## Private Member Functions

int | open_simple_section (const ACE_Configuration_Section_Key &base, const ACE_TCHAR *sub_section, int create, ACE_Configuration_Section_Key &result)
| <sub_section> may not contain path separators
int | add_section (const ACE_Configuration_Section_Key &base, const ACE_TCHAR *sub_section, ACE_Configuration_Section_Key &result)
| Adds a new section.
int | create_index (void)
| Helper for the <open> method.
int | create_index_helper (void *buffer)
int | value_open_helper (size_t hash_table_size, void *buffer)
int | section_open_helper (size_t hash_table_size, void *buffer)
int | load_key (const ACE_Configuration_Section_Key &key, ACE_TString &name)
int | new_section (const ACE_TString &section, ACE_Configuration_Section_Key &result)
| ACE_Configuration_Heap (const ACE_Configuration_Heap &rhs)
ACE_Configuration_Heap & | operator= (const ACE_Configuration_Heap &rhs)

## Private Attributes

ACE_Allocator * | allocator_
SECTION_MAP * | index_
size_t | default_map_size_

## Detailed Description

The concrete implementation of a allocator based configuration database.

This class uses ACE's Allocators to manage a memory representation of a configuraiton database. A persistent heap may be used to store configurations persistently

Note:
  Before using this class you must call one of the open methods.

Todo:
  -Need to investigate what happens if memory mapped file gets mapped to a location different than it was created with.

## Constructor & Destructor Documentation

ACE_Configuration_Heap::ACE_Configuration_Heap | ( | void |  | ) |

| Default ctor.

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

| Destructor.

ACE_Configuration_Heap::ACE_Configuration_Heap | ( | const ACE_Configuration_Heap & | rhs | ) | `[private]`

## Member Function Documentation

int ACE_Configuration_Heap::add_section | ( | const ACE_Configuration_Section_Key & | base,
|  | const ACE_TCHAR * | sub_section,
|  | ACE_Configuration_Section_Key & | result
| ) | `[private]`

| Adds a new section.

int ACE_Configuration_Heap::create_index | ( | void |  | ) | `[private]`

| Helper for the <open> method.

int ACE_Configuration_Heap::create_index_helper | ( | void * | buffer | ) | `[private]`

| Helper for create_index() method: places hash table into an allocated space.

int ACE_Configuration_Heap::enumerate_sections | ( | const ACE_Configuration_Section_Key & | key,
|  | int | index,
|  | ACE_TString & | name
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::enumerate_values | ( | const ACE_Configuration_Section_Key & | key,
|  | int | index,
|  | ACE_TString & | name,
|  | VALUETYPE & | type
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::find_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | VALUETYPE & | type
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::get_binary_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | void *& | data,
|  | size_t & | length
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::get_integer_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | u_int & | value
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::get_string_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | ACE_TString & | value
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::load_key | ( | const ACE_Configuration_Section_Key & | key,
|  | ACE_TString & | name
| ) | `[private]`

int ACE_Configuration_Heap::new_section | ( | const ACE_TString & | section,
|  | ACE_Configuration_Section_Key & | result
| ) | `[private]`

int ACE_Configuration_Heap::open | ( | size_t | default_map_size = `ACE_DEFAULT_CONFIG_SECTION_SIZE` | ) |

| Opens a heap based configuration.

int ACE_Configuration_Heap::open | ( | const ACE_TCHAR * | file_name,
|  | void * | base_address = `ACE_DEFAULT_BASE_ADDR`,
|  | size_t | default_map_size = `ACE_DEFAULT_CONFIG_SECTION_SIZE`
| ) |

| Opens a configuration based on a file name.

int ACE_Configuration_Heap::open_section | ( | const ACE_Configuration_Section_Key & | base,
|  | const ACE_TCHAR * | sub_section,
|  | int | create,
|  | ACE_Configuration_Section_Key & | result
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::open_simple_section | ( | const ACE_Configuration_Section_Key & | base,
|  | const ACE_TCHAR * | sub_section,
|  | int | create,
|  | ACE_Configuration_Section_Key & | result
| ) | `[private]`

| <sub_section> may not contain path separators

ACE_Configuration_Heap& ACE_Configuration_Heap::operator= | ( | const ACE_Configuration_Heap & | rhs | ) | `[private]`

int ACE_Configuration_Heap::remove_section | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | sub_section,
|  | int | recursive
| ) | `[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.

Implements ACE_Configuration.

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

| Removes the the value <name> from <key>. returns non zero on error. Implements ACE_Configuration.

int ACE_Configuration_Heap::section_open_helper | ( | size_t | hash_table_size,
|  | void * | buffer
| ) | `[private]`

int ACE_Configuration_Heap::set_binary_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | const void * | data,
|  | size_t | length
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::set_integer_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | u_int | value
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::set_string_value | ( | const ACE_Configuration_Section_Key & | key,
|  | const ACE_TCHAR * | name,
|  | const ACE_TString & | value
| ) | `[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.

Implements ACE_Configuration.

int ACE_Configuration_Heap::value_open_helper | ( | size_t | hash_table_size,
|  | void * | buffer
| ) | `[private]`

## Member Data Documentation

ACE_Allocator* ACE_Configuration_Heap::allocator_ `[private]`

size_t ACE_Configuration_Heap::default_map_size_ `[private]`

SECTION_MAP* ACE_Configuration_Heap::index_ `[private]`

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

- Configuration.h
- Configuration.cpp