| General Info | |
|
Interface: CfgManager Files: cfgmanager.h Last change: 01/06/2003 Author: Luiz Henrique Shigunov | Description |
| System Functions | |
|
0x00 - CloseGroup - Close a group 0x01 - EnumGroup - Enumerate groups 0x02 - EnumKey - Enumerate keys 0x03 - GetValue - Get a key value |
0x04 - OpenGroup - Open a group 0x05 - OpenGroupIndex - Open a group 0x06 - SetSystemFile - Set the file that must be used for the /system group |
This page describes the CfgManager interface which provides access to the system configuration, centralizing and standardizing this access.
System configurations are stored in keys and these keys are organized in groups. Each key has a value associated with it that can be read in different formats (string, hex number, etc).
To read a key's value, the group where the key is must be opened with the function OpenGroup, the value read with GetValue and after that the group must be closed with CloseGroup.
A group is looked up with a path which is formed this way: /file/interface or module/group. For instance: /system/SysModManager/modules or /system/SysModManager/modules/sysmodmanager.
int CfgManager_CloseGroup(CfgManager_Group *group);
This function closes group which must have been opened with OpenGroup or OpenGroupIndex.
Groups should not be left open any longer than necessary.
int CfgManager_EnumGroup(CfgManager_Group *group, unsigned int index, char *name, unsigned int *nameSize);
This function enumerates groups from group which must have been opened with OpenGroup or OpenGroupIndex.
index is the index of the group to be retrieved and must be zero for the first time this function is called and incremented for subsequent calls. Groups can be returned in any order.
name is the memory area that receives the name of the group, including the terminating null character. This function copies only the name of the group and not the full path.
When calling this function, nameSize must have the size of the memory area pointed to by name and when this function returns it will contain the number of characters stored in name, not including the terminating null character.
int CfgManager_EnumKey(CfgManager_Group *group, unsigned int index, char *name, unsigned int *nameSize);
This function enumerates keys from group which must have been opened with OpenGroup or OpenGroupIndex.
index is the index of the key to be retrieved and must be zero for the first time this function is called and incremented for subsequent calls. Keys can be returned in any order.
name is the memory area that receives the name of the key, including the terminating null character. This function copies only the name of the key and not the full path.
When calling this function, nameSize must have the size of the memory area pointed to by name and when this function returns it will contain the number of characters stored in name, not including the terminating null character.
int CfgManager_GetValue(CfgManager_Group *group, const char *key, int type, void *buf, unsigned int *bufSize);
This function retrieves the value associated with key from group which must have been opened with OpenGroup or OpenGroupIndex.
type contains the type of value to retrieve and can be:
buf is the memory area where to store the value.
When calling this function, bufSize must have the size of the memory area pointed to by buf and when this function returns it will contain the number of bytes stored in buf, including the terminating null character if type is CfgManager_STRING.
CfgManager_Group *CfgManager_OpenGroup(CfgManager_Group *base, const char *path);
This function opens the group path using base which must have been opened with OpenGroup or OpenGroupIndex. If base is NULL, the root will be used.
path is case sensive, names can only have letters (a-z, A-Z), numbers (0-9) or underscore (_) and is formed this way: /file/interface or module/group. For instance: /system/SysModManager/modules or only modules if base is used.
Every configuration file is stored in /system/config/ directory.
The ideia of using base is that a module can open for instance /system/SysModManager/modules and then open other groups using this base. This way, the process of opening groups is faster since less path must be parsed.
CfgManager_Group *CfgManager_OpenGroupIndex(CfgManager_Group *base, unsigned int index);
This function opens the group index using base which must have been opened with OpenGroup or OpenGroupIndex. If base is NULL, the root will be used.
index is the index of the group to be opened and should be zero for the first time this function is called and incremented in subsequent calls. Groups can be opened in any order.
This function simplifies and accelerates opening of groups. Without this function, EnumGroup and then OpenGroup would have to be used.
int CfgManager_SetSystemFile(void *file, unsigned int size);
This function sets the file that must be used for the /system group that contains system configurations. This group must be available since the beginning of the initialization process.
file is a pointer to the file's data and size is the number of bytes in this area.
The data pointed to by file must be copied to other memory area before they can be used.