Crystal Space: csConfigManager Class Reference (Crystal Space Public API Reference)

| ## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# csConfigManager Class Reference

A configuration manager makes a number of individual iConfigFile objects appear to be a single configuration object. More...

`#include <csutil/cfgmgr.h>`

Inheritance diagram for csConfigManager:

[legend]
List of all members.

## Public Member Functions
virtual iConfigFile * | AddDomain (char const *path, iVFS *, int priority)
| Add a configuration domain by loading it from a file.
virtual void | AddDomain (iConfigFile *, int priority)
| Add a configuration domain.
void | CleanUp ()
| FlushRemoved() and delete all domains.
virtual void | Clear ()
| Delete all options and rewind all iterators.
| csConfigManager (iConfigFile *DynamicDomain=0, bool Optimize=false)
| Create a new config manager object.
virtual void | DeleteKey (const char *Key)
| Delete a key and its value and comment.
virtual csPtr< iConfigIterator > | Enumerate (const char *Subsection=0)
| Enumerate selected keys.
virtual void | FlushRemoved ()
| flush all removed configuration files (only required in optimize mode)
virtual bool | GetBool (const char *Key, bool Def=false) const
| Get a boolean value from the configuration.
virtual const char * | GetComment (const char *Key) const
| Get the comment of the given key, or 0 if no comment exists.
virtual int | GetDomainPriority (iConfigFile *) const
| Return the priority of a configuration domain.
virtual int | GetDomainPriority (char const *path) const
| Return the priority of a configuration domain.
virtual iConfigFile * | GetDynamicDomain () const
| Return a pointer to the dynamic configuration domain.
virtual int | GetDynamicDomainPriority () const
| Return the priority of the dynamic configuration domain.
virtual const char * | GetEOFComment () const
| return the final comment at the end of the configuration file
virtual const char * | GetFileName () const
| Get configuration file name.
virtual float | GetFloat (const char *Key, float Def=0.0) const
| Get a float value from the configuration.
virtual int | GetInt (const char *Key, int Def=0) const
| Get an integer value from the configuration.
virtual const char * | GetStr (const char *Key, const char *Def="") const
| Get a string value from the configuration.
virtual iVFS * | GetVFS () const
| Get the VFS object on which this file is stored (if any).
virtual bool | KeyExists (const char *Key) const
| Test if a key exists.
virtual bool | Load (const char *iFileName, iVFS *=0, bool Merge=false, bool NewWins=true)
| Load a configuration file.
virtual iConfigFile * | LookupDomain (char const *path) const
| Find the iConfigFile object for a registered domain.
virtual void | RemoveDomain (char const *path)
| Remove a configuration domain.
virtual void | RemoveDomain (iConfigFile *)
| Remove a configuration domain.
virtual bool | Save (const char *iFileName, iVFS *=0)
| Save configuration into the given file (on VFS or on the physical filesystem).
virtual bool | Save ()
| Save configuration to the same place from which it was loaded.
virtual void | SetBool (const char *Key, bool Value)
| Set a boolean value.
virtual bool | SetComment (const char *Key, const char *Text)
| Set the comment for given key.
virtual void | SetDomainPriority (iConfigFile *, int priority)
| Set the priority of a registered configuration domain.
virtual void | SetDomainPriority (char const *path, int priority)
| Set the priority of a configuration domain.
virtual bool | SetDynamicDomain (iConfigFile *)
| Change the dynamic domain.
virtual void | SetDynamicDomainPriority (int priority)
| Set the priority of the dynamic configuration domain.
virtual void | SetEOFComment (const char *Text)
| set the final comment at the end of the configuration file
virtual void | SetFileName (const char *, iVFS *)
| Set config file name.
virtual void | SetFloat (const char *Key, float Value)
| Set a floating-point value.
virtual void | SetInt (const char *Key, int Value)
| Set an integer value.
virtual void | SetStr (const char *Key, const char *Val)
| Set an null-terminated string value.
virtual bool | SubsectionExists (const char *Subsection) const
| Test if at least one key exists with the given Subsection prefix.
virtual | ~csConfigManager ()
| Destroy configuration manager.
## Friends
class | csConfigManagerIterator

## Detailed Description

A configuration manager makes a number of individual iConfigFile objects appear to be a single configuration object.

See the description of the iConfigManager interface for full details.

Definition at line 40 of file cfgmgr.h.

## Constructor & Destructor Documentation

csConfigManager::csConfigManager | ( | iConfigFile * | DynamicDomain = `0`,
|  | bool | Optimize = `false` |
| ) |  |  |

Create a new config manager object.

If 'Optimize' is set to 'true', then the configuration manager will enable some optimizations, which you may or may not want:

- When an iConfigFile is added via AddDomain(name, vfs), the configuration manager first looks through all registered iConfigFile objects. If an object with the same name and VFS pointer are found, it is added a second time, so the file is not loaded twice.
- When an iConfigFile is removed, the configuration manager keeps a reference to it until Flush() is called. If you add the iConfigFile again in the meantime with AddDomain(name, vfs), this reference is used instead.

virtual csConfigManager::~csConfigManager | ( |  | ) | `[virtual]`

Destroy configuration manager.

## Member Function Documentation

virtual iConfigFile* csConfigManager::AddDomain | ( | char const * | path,
|  | iVFS * | ,
|  | int | priority |
| ) |  |  | `[virtual]`

Add a configuration domain by loading it from a file.

The new iConfigFile object which represents the loaded file is also returned. If you want to hold onto the iConfigFile even after it is removed from this object or after the configuration manager is destroyed, be sure to invoke IncRef() or assign it to a csRef<>. The incoming iVFS* may be null, in which case the path is assumed to point at a file in the pyhysical filesystem, rather than at a file in the virtual filesystem.

Implements iConfigManager.

virtual void csConfigManager::AddDomain | ( | iConfigFile * | ,
|  | int | priority |
| ) |  |  | `[virtual]`

Add a configuration domain.

The configuration manager invokes IncRef() upon the incoming iConfigFile.

Implements iConfigManager.

void csConfigManager::CleanUp | ( |  | ) |

FlushRemoved() and delete all domains.

virtual void csConfigManager::Clear | ( |  | ) | `[virtual]`

Delete all options and rewind all iterators.

Implements iConfigFile.

virtual void csConfigManager::DeleteKey | ( | const char * | Key | ) | `[virtual]`

Delete a key and its value and comment.

Implements iConfigFile.

virtual csPtr<iConfigIterator> csConfigManager::Enumerate | ( | const char * | Subsection = `0` | ) | `[virtual]`

Enumerate selected keys.

If a subsection is given, only those keys which are prefixed by the subsection string will be enumerated. The returned iterator does not yet point to a valid key. You must call Next() to set it to the first key.

Implements iConfigFile.

virtual void csConfigManager::FlushRemoved | ( |  | ) | `[virtual]`

flush all removed configuration files (only required in optimize mode)

Implements iConfigManager.

virtual bool csConfigManager::GetBool | ( | const char * | Key,
|  | bool | Def = `false` |
| ) |  |  | const`[virtual]`

Get a boolean value from the configuration.

Implements iConfigFile.

virtual const char* csConfigManager::GetComment | ( | const char * | Key | ) | const`[virtual]`

Get the comment of the given key, or 0 if no comment exists.

Implements iConfigFile.

virtual int csConfigManager::GetDomainPriority | ( | iConfigFile * |  | ) | const`[virtual]`

Return the priority of a configuration domain.

If the domain is not registered, PriorityMedium is returned.

Implements iConfigManager.

virtual int csConfigManager::GetDomainPriority | ( | char const * | path | ) | const`[virtual]`

Return the priority of a configuration domain.

If the domain is not registered, PriorityMedium is returned.

Implements iConfigManager.

virtual iConfigFile* csConfigManager::GetDynamicDomain | ( |  | ) | const`[virtual]`

Return a pointer to the dynamic configuration domain.

The returned pointer will remain valid as long as the domain is registered with the configuration manager.

Implements iConfigManager.

virtual int csConfigManager::GetDynamicDomainPriority | ( |  | ) | const`[virtual]`

Return the priority of the dynamic configuration domain.

Implements iConfigManager.

virtual const char* csConfigManager::GetEOFComment | ( |  | ) | const`[virtual]`

return the final comment at the end of the configuration file

Implements iConfigFile.

virtual const char* csConfigManager::GetFileName | ( |  | ) | const`[virtual]`

Get configuration file name.

Also consult GetVFS() to determine which (if any) VFS object was used for the file's storage.

Implements iConfigFile.

virtual float csConfigManager::GetFloat | ( | const char * | Key,
|  | float | Def = `0.0` |
| ) |  |  | const`[virtual]`

Get a float value from the configuration.

Implements iConfigFile.

virtual int csConfigManager::GetInt | ( | const char * | Key,
|  | int | Def = `0` |
| ) |  |  | const`[virtual]`

Get an integer value from the configuration.

Implements iConfigFile.

virtual const char* csConfigManager::GetStr | ( | const char * | Key,
|  | const char * | Def = `""` |
| ) |  |  | const`[virtual]`

Get a string value from the configuration.

Implements iConfigFile.

virtual iVFS* csConfigManager::GetVFS | ( |  | ) | const`[virtual]`

Get the VFS object on which this file is stored (if any).

Returns 0 if this file resides within the real (non-VFS) filesystem.

Implements iConfigFile.

virtual bool csConfigManager::KeyExists | ( | const char * | Key | ) | const`[virtual]`

Test if a key exists.

Implements iConfigFile.

virtual bool csConfigManager::Load | ( | const char * | iFileName,
|  | iVFS * | = `0`,
|  | bool | Merge = `false`,
|  | bool | NewWins = `true` |
| ) |  |  | `[virtual]`

Load a configuration file.

If the file resides in a real filesystem, rather than a VFS filesystem, then pass 0 for the VFS argument. This will clear all options before loading the new options, even if the file cannot be opened.

You can set the Merge flag to merge the newly loaded configuration information into the existing information. If you do so, nothing will happen if the named file doesn't exist. The NewWins flag determines the behavior in case of configuration key conflicts. If true, then the new configuration value replaces the old for that key. If false, then the old value is kept, and the new value is ignored. The recorded file name will be set to the name of the newly loaded file if the Merge flag is false; otherwise it will retain the old name.

Implements iConfigFile.

virtual iConfigFile* csConfigManager::LookupDomain | ( | char const * | path | ) | const`[virtual]`

Find the iConfigFile object for a registered domain.

Returns null if the domain is not registered.

Implements iConfigManager.

virtual void csConfigManager::RemoveDomain | ( | char const * | path | ) | `[virtual]`

Remove a configuration domain.

Implements iConfigManager.

virtual void csConfigManager::RemoveDomain | ( | iConfigFile * |  | ) | `[virtual]`

Remove a configuration domain.

If registered, the configuration manager will relinquish its reference to the domain by invoking DecRef() on it to balance the IncRef() it performed when the domain was added. If the domain is not registered, the RemoveDomain() request is ignored. It is not legal to remove the dynamic domain.

Implements iConfigManager.

virtual bool csConfigManager::Save | ( | const char * | iFileName,
|  | iVFS * | = `0` |
| ) |  |  | `[virtual]`

Save configuration into the given file (on VFS or on the physical filesystem).

If the iVFS parameter is null, the file will be written to the physical filesystem, otherwise it is stored on given VFS filesystem. This method does not change the internally stored file name.

Implements iConfigFile.

virtual bool csConfigManager::Save | ( |  | ) | `[virtual]`

Save configuration to the same place from which it was loaded.

Returns true if the save operation succeeded, else false.

Implements iConfigFile.

virtual void csConfigManager::SetBool | ( | const char * | Key,
|  | bool | Value |
| ) |  |  | `[virtual]`

Set a boolean value.

Implements iConfigFile.

virtual bool csConfigManager::SetComment | ( | const char * | Key,
|  | const char * | Text |
| ) |  |  | `[virtual]`

Set the comment for given key.

In addition to an actual comment, you can use "" for Text to place an empty comment line before this key, or 0 to remove the comment entirely. The comment may contain newline characters. Returns false if the key does not exist.

Implements iConfigFile.

virtual void csConfigManager::SetDomainPriority | ( | iConfigFile * | ,
|  | int | priority |
| ) |  |  | `[virtual]`

Set the priority of a registered configuration domain.

If the domain is not registered, the request is ignored.

Implements iConfigManager.

virtual void csConfigManager::SetDomainPriority | ( | char const * | path,
|  | int | priority |
| ) |  |  | `[virtual]`

Set the priority of a configuration domain.

Implements iConfigManager.

virtual bool csConfigManager::SetDynamicDomain | ( | iConfigFile * |  | ) | `[virtual]`

Change the dynamic domain.

The domain must already have been registered with AddDomain() before calling this method. If the domain is not registered, then false is returned.

Implements iConfigManager.

virtual void csConfigManager::SetDynamicDomainPriority | ( | int | priority | ) | `[virtual]`

Set the priority of the dynamic configuration domain.

Implements iConfigManager.

virtual void csConfigManager::SetEOFComment | ( | const char * | Text | ) | `[virtual]`

set the final comment at the end of the configuration file

Implements iConfigFile.

virtual void csConfigManager::SetFileName | ( | const char * | ,
|  | iVFS * |  |
| ) |  |  | `[virtual]`

Set config file name.

You can use this if you want Save() to write to another file. The incoming iVFS can be null, in which case the filename represents a file in the physical fileysstem. This will set the dirty flag.

Implements iConfigFile.

virtual void csConfigManager::SetFloat | ( | const char * | Key,
|  | float | Value |
| ) |  |  | `[virtual]`

Set a floating-point value.

Implements iConfigFile.

virtual void csConfigManager::SetInt | ( | const char * | Key,
|  | int | Value |
| ) |  |  | `[virtual]`

Set an integer value.

Implements iConfigFile.

virtual void csConfigManager::SetStr | ( | const char * | Key,
|  | const char * | Val |
| ) |  |  | `[virtual]`

Set an null-terminated string value.

Implements iConfigFile.

virtual bool csConfigManager::SubsectionExists | ( | const char * | Subsection | ) | const`[virtual]`

Test if at least one key exists with the given Subsection prefix.

Implements iConfigFile.

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

- csutil/cfgmgr.h