iConfigManager Struct Reference
[Utilities]
The configuration manager is used to make a number of iConfigFile object appear like a single object.
More...
#include <iutil/cfgmgr.h>
Inheritance diagram for iConfigManager:
Public Types | |
| enum | |
| enum | |
| Default priority values (you may use other values if you want). More... | |
Public Member Functions | |
| virtual iConfigFile * | AddDomain (char const *path, iVFS *, int priority)=0 |
| Add a configuration domain by loading it from a file. | |
| virtual void | AddDomain (iConfigFile *, int priority)=0 |
| Add a configuration domain. | |
| virtual void | FlushRemoved ()=0 |
| Flush all removed configuration files (only required in optimize mode). | |
| virtual int | GetDomainPriority (iConfigFile *) const =0 |
| Return the priority of a configuration domain. | |
| virtual int | GetDomainPriority (char const *path) const =0 |
| Return the priority of a configuration domain. | |
| virtual iConfigFile * | GetDynamicDomain () const =0 |
| Return a pointer to the dynamic configuration domain. | |
| virtual int | GetDynamicDomainPriority () const =0 |
| Return the priority of the dynamic configuration domain. | |
| virtual iConfigFile * | LookupDomain (char const *path) const =0 |
| Find the iConfigFile object for a registered domain. | |
| virtual void | RemoveDomain (char const *path)=0 |
| Remove a configuration domain. | |
| virtual void | RemoveDomain (iConfigFile *)=0 |
| Remove a configuration domain. | |
| virtual void | SetDomainPriority (iConfigFile *, int priority)=0 |
| Set the priority of a registered configuration domain. | |
| virtual void | SetDomainPriority (char const *path, int priority)=0 |
| Set the priority of a configuration domain. | |
| virtual bool | SetDynamicDomain (iConfigFile *)=0 |
| Change the dynamic domain. | |
| virtual void | SetDynamicDomainPriority (int priority)=0 |
| Set the priority of the dynamic configuration domain. | |
Detailed Description
The configuration manager is used to make a number of iConfigFile object appear like a single object.To do this, each iConfigFile object (also called a 'domain') is assigned a priority value. Options from config files with higher priority override or shadow options from configuration objects with lower priority. The lower priority options are still present, so if you access the lower priority iConfigFile directly you will still find their real values. If two iConfigFile objects use the same priority value, then one will shadow the other (but it is not possible to predict which will be the victor).
One iConfigFile object is the so-called 'dynamic' domain. When you alter a setting in the configuration manager, the change is applied to the dynamic iConfigFile object. As a side-effect, the changed key is also removed from all objects with higher priority. The dynamic domain has always priority 0 (medium).
Differences in behaviour compared to a normal configuration object are:
- Deleting a key will not always remove the key from the configuration completely. It will only remove the key from the dynamic iConfigFile object and all higher-priority objects; and will thus reveal a value in a lower priority domain, if present. This also applies to the Clear() method.
- The Load() and Save() methods will load or save the configuration of the dynamic domain. The other domains are not affected by Load(); and Save() will not write any keys from other domains. (In the unlikely event that you need to load or save one of the other domains, simply access the iConfigFile object for that domain directly and invoke its Load() and Save() methods rather than the methods of iConfigManager.)
- Iterators: If you change an option after an iterator has passed the option, it may appear again, this time with the new value. If you change the option while the iterator looks at it, you may even read it twice after this change, once with the old and once with the new value. In general it is a bad idea to change something while an iterator exists.
Main creators of instances implementing this interface:
Main ways to get pointers to this interface:
Definition at line 77 of file cfgmgr.h.
Member Enumeration Documentation
| anonymous enum |
Member Function Documentation
| virtual iConfigFile* iConfigManager::AddDomain | ( | char const * | path, | |
| iVFS * | , | |||
| int | priority | |||
| ) | [pure 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 physical filesystem, rather than at a file in the virtual filesystem.
Implemented in csConfigManager.
| virtual void iConfigManager::AddDomain | ( | iConfigFile * | , | |
| int | priority | |||
| ) | [pure virtual] |
Add a configuration domain.
The configuration manager invokes IncRef() upon the incoming iConfigFile.
Implemented in csConfigManager.
| virtual void iConfigManager::FlushRemoved | ( | ) | [pure virtual] |
Flush all removed configuration files (only required in optimize mode).
Implemented in csConfigManager.
| virtual int iConfigManager::GetDomainPriority | ( | iConfigFile * | ) | const [pure virtual] |
Return the priority of a configuration domain.
If the domain is not registered, PriorityMedium is returned.
Implemented in csConfigManager.
| virtual int iConfigManager::GetDomainPriority | ( | char const * | path | ) | const [pure virtual] |
Return the priority of a configuration domain.
If the domain is not registered, PriorityMedium is returned.
Implemented in csConfigManager.
| virtual iConfigFile* iConfigManager::GetDynamicDomain | ( | ) | const [pure 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.
Implemented in csConfigManager.
| virtual int iConfigManager::GetDynamicDomainPriority | ( | ) | const [pure virtual] |
| virtual iConfigFile* iConfigManager::LookupDomain | ( | char const * | path | ) | const [pure virtual] |
Find the iConfigFile object for a registered domain.
Returns null if the domain is not registered.
Implemented in csConfigManager.
| virtual void iConfigManager::RemoveDomain | ( | char const * | path | ) | [pure virtual] |
| virtual void iConfigManager::RemoveDomain | ( | iConfigFile * | ) | [pure 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. Note that if optimize is on then this removal will not take place until FlushRemoved() is called.
Implemented in csConfigManager.
| virtual void iConfigManager::SetDomainPriority | ( | iConfigFile * | , | |
| int | priority | |||
| ) | [pure virtual] |
Set the priority of a registered configuration domain.
If the domain is not registered, the request is ignored.
Implemented in csConfigManager.
| virtual void iConfigManager::SetDomainPriority | ( | char const * | path, | |
| int | priority | |||
| ) | [pure virtual] |
| virtual bool iConfigManager::SetDynamicDomain | ( | iConfigFile * | ) | [pure 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.
Implemented in csConfigManager.
| virtual void iConfigManager::SetDynamicDomainPriority | ( | int | priority | ) | [pure virtual] |
The documentation for this struct was generated from the following file:
- iutil/cfgmgr.h
Generated for Crystal Space by doxygen 1.4.7