#include ``config.h''
ReturnCode
CONFIG_open(char * pFileName,
void ** phConfig);
void
CONFIG_close(void * hConfig);
ReturnCode
CONFIG_nextSection(void * hConfig,
char ** ppSectionName,
void ** phSection);
ReturnCode
CONFIG_nextParameter(void * hConfig,
char * pSectionName,
char ** ppTypeName,
char ** ppValue,
void ** phParameter);
ReturnCode
CONFIG_getNumber(void * hConfig,
char * pSectionName,
char * pTypeName,
OS_Uint32 * pValue);
ReturnCode
CONFIG_getString(void * hConfig,
char * pSectionName,
char * pTypeName,
char ** ppValue);
ReturnCode
CONFIG_setNumber(void * hConfig,
char * pSectionName,
char * pTypeName,
OS_Uint32 value,
CONFIG_Permanence permanence);
ReturnCode
CONFIG_setString(void * hConfig,
char * pSectionName,
char * pTypeName,
char * pValue,
CONFIG_Permanance permanance);
The Configuration Module (CFG) provides a set of functions for reading and writing configuration data. The data can be maintained in a file, or can be set on a temporary basis for use during an iteration of the program, or until the data is re-read from the file.
A CFG configuration file contains one or more Sections, each of which contain one or more Parameters. Parameters are pairs of Types and Values.
section a
parameterx.type parameterx.value
parametery.type parametery.value
.
.
.
section b
parameteri.type parameteri.value
parameteri.type parameteri.value
.
.
.
For examples of configuration file formats for various environments see Chapter 8, Implementations of the Platform.
ReturnCode
CONFIG_open(char * pFileName,
void ** phConfig);
void
CONFIG_close(void * hConfig);
CONFIG_open opens the configuration file specified by pFileName and places a file handle in the location pointed to by phConfig. CONFIG_close closes the previously opened configuration file with the handle hConfig.
CONFIG_open has the following possible return values:
ReturnCode
CONFIG_nextSection(void * hConfig,
char ** ppSectionName,
void ** phSection);
Returns:
Success
Fail
CONFIG_nextSection scans the configuration file pointed to by hConfig for the next Section and returns a pointer to the character string containing the section name in ppSectionName.
phSectionis a Handle indicating where to begin the search. If the location pointed to by this parameter contains NULL (i.e. *phSection == NULL) then the first section in the configuration file will be returned. Upon return from this function, *phSection is updated with a new value. If this value of phSection is passed to this function again (with the same section name), the next section in the configuration file will be returned.
ReturnCode
CONFIG_nextParameter(void * hConfig,
char * pSectionName,
char ** ppTypeName,
char ** ppValue,
void ** phParameter);
Returns:
Success
Fail
CONFIG_nextParameter scans the configuration file pointed to by hConfig, under the section pSectionName for the next occurrence of a Parameter. It then places a pointer to the string containing the Parameter's Type in ppTypeName and a pointer to the string containing the Parameter's Value in ppValue.
phParameter is a Handle indicating where to begin the search. If the location pointed to by this parameter contains NULL (i.e. *phParameter == NULL) then the first Parameter in the specified Section will be returned. Upon return from this function, *phParameter is updated with a new value. If this value of phParameter is passed to this function again (with the same section name), the next parameter in the specified Section will be returned.
#define CONFIG_MAX_PARAMETER_LEN 1024
ReturnCode
CONFIG_getNumber(void * hConfig,
char * pSectionName,
char * pTypeName,
OS_Uint32 * pValue);
ReturnCode
CONFIG_getString(void * hConfig,
char * pSectionName,
char * pTypeName,
char ** ppValue);
ReturnCode
CONFIG_setNumber(void * hConfig,
char * pSectionName,
char * pTypeName,
OS_Uint32 value,
CONFIG_Permanance permanance);
ReturnCode
CONFIG_setString(void * hConfig,
char * pSectionName,
char * pTypeName,
char * pValue,
CONFIG_Permanance permanance);
Returns:
Success
Fail
The facilities CONFIG_getNumber, CONFIG_getString, CONFIG_setNumber, and CONFIG_setString operate on Paramter Values.
CONFIG_getNumber and CONFIG_getString read a configuration file and return an unsigned 32 bit integer or a pointer to a string, respectively.
CONFIG_setNumber and CONFIG_setString take an unsigned 32 bit integer or a pointer to a string, respectively, as input and write their values to a configuration file.
In all cases the configuration file is pointed to by hConfig, a configuration handle previously returned by CONFIG_openFile. The Parameter is taken from the Section indicated by pSectionName. The Paramter Type to search for is given by pTypeName. (Section and Parameter names have white space stripped from them.)
CONFIG_getNumber returns its result in the location pointed to by pValue.
CONFIG_getString returns its result in the location pointed to by ppValue. The returned Value pointer points to static data. Do not modify the data pointed to by the returned Parameter.
CONFIG_setNumber assigns value to the specified Section/Type.
CONFIG_setString assigns pValue the specified Section/Type.
Note: Paramter Values may be no longer than 1024 bytes.
typedef enum
{
CONFIG_Permanent,
CONFIG_ThisExecution,
CONFIG_Transient
} CONFIG_Permanance;
This module does not yet write to the configuration file. The file should be created by hand, for now. For this reason, the PERMANANCE values have no meaning at this time.
For CONFIG_setNumber and CONFIG_setString, if permanance is set to CONFIG_Permanent, rewrite the configuration file with this new value assigned to the specified Section/Type. If CONFIG_ThisExecution, this value is "local" to the current run-time environment, and returns to the value saved in the file upon program termination or upon a call to CONFIG_close. If permanance is set to CONFIG_Transient, this value is "local to the current run-time environment, and returns to the value saved in the file upon re-reading of the configuration file (not yet implemented), or upon a call to CONFIG_close.