X11 Work Bench Toolkit  1.0
Configuration File Utilities

Configuration File Utilities, for application or user-defined config files. More...

Functions

void * CHOpenConfFile (const char *szAppName, int iFlags)
 open configuration file for read/write, optionally creating it, based on application name More...
 
void CHCloseConfFile (void *hFile)
 close configuration file opened by CHOpenConfFile(), but does NOT free memory resources More...
 
void CHDestroyConfFile (void *hFile)
 destroy configuration file opened by CHOpenConfFile(), freeing memory resources (but not the files) More...
 
int CHGetConfFileString (void *hFile, const char *szSection, const char *szIdentifier, char *szData, int cbData)
 obtain a string from a configuration file More...
 
int CHWriteConfFileString (void *hFile, const char *szSection, const char *szIdentifier, const char *szData)
 write a string to a configuration file More...
 
int CHGetConfFileInt (void *hFile, const char *szSection, const char *szIdentifier)
 obtain an integer value from a configuration file More...
 
int CHWriteConfFileInt (void *hFile, const char *szSection, const char *szIdentifier, int iData)
 write an integer value to a configuration file More...
 
#define CH_FLAGS_DEFAULT   0
 
#define CH_FLAGS_GLOBAL   0x1
 
#define CH_FLAGS_WRITE   0x2
 

Detailed Description

Configuration File Utilities, for application or user-defined config files.

Macro Definition Documentation

#define CH_FLAGS_DEFAULT   0

default flags for CHOpenConfFile()

Definition at line 109 of file conf_help.h.

#define CH_FLAGS_GLOBAL   0x1

set this for 'global only' for CHOpenConfFile()

Definition at line 110 of file conf_help.h.

#define CH_FLAGS_WRITE   0x2

set this to enable GLOBAL write (local write automatically enabled) for CHOpenConfFile()

Definition at line 111 of file conf_help.h.

Function Documentation

void CHCloseConfFile ( void *  hFile)

close configuration file opened by CHOpenConfFile(), but does NOT free memory resources

Parameters
hFileThe configuration file object returned by CHOpenConfFile()

Use this function to close the configuration file that was opened by CHOpenConfFile()
Memory resources will NOT be freed (values will remain cached as needed). Use this function to simply remove the open file reference but leave the data in memory for later use.

Header File: conf_help.h

Definition at line 831 of file conf_help.c.

void CHDestroyConfFile ( void *  hFile)

destroy configuration file opened by CHOpenConfFile(), freeing memory resources (but not the files)

Parameters
hFileThe configuration file object returned by CHOpenConfFile()

This function will close the configuration file and destroy the cached information created by CHOpenConfFile() but does not physically destroy the file on disk.

Header File: conf_help.h

Definition at line 863 of file conf_help.c.

int CHGetConfFileInt ( void *  hFile,
const char *  szSection,
const char *  szIdentifier 
)

obtain an integer value from a configuration file

Parameters
hFilethe configuration file object pointer returned by CHOpenConfFile
szSectiona pointer to an ASCII 0-byte terminated string containing the section name
szIdentifiera pointer to an ASCII 0-byte terminated string identifying the (unique) data entry
Returns
the integer value, or zero on error or if not found

Use this function to query an integer value for 'szIdentifier' in 'szSection'. The function will return a non-zero value on success, or a zero value on error, or if not found.
If you need to distinguish an actual zero value from an error or 'not found' condition, consider using the CHGetConfFileString() function instead.

Header File: conf_help.h

Definition at line 1621 of file conf_help.c.

int CHGetConfFileString ( void *  hFile,
const char *  szSection,
const char *  szIdentifier,
char *  szData,
int  cbData 
)

obtain a string from a configuration file

Parameters
hFilethe configuration file object pointer returned by CHOpenConfFile
szSectiona pointer to an ASCII 0-byte terminated string containing the section name
szIdentifiera pointer to an ASCII 0-byte terminated string identifying the (unique) data entry
szDataa buffer in which to return the string data
cbDatathe size of the buffer pointed to by szData
Returns
the total length of the string (excluding the zero byte), or -1 on error (or if value not found)

Use this function to obtain a configuration parameter 'szIdentifier' from section 'szSection', and save the data into 'szData', which is 'cbData' bytes in length. The function will return the total length of the resulting string. The function returns -1 on error, or if the data value is not located.

Header File: conf_help.h

Definition at line 1223 of file conf_help.c.

void* CHOpenConfFile ( const char *  szAppName,
int  iFlags 
)

open configuration file for read/write, optionally creating it, based on application name

Parameters
szAppNameThe name of the application for which a configuration file is to be opened (no extension)
iFlagsOne or more of the CH_FLAGS, specifically CH_FLAGS_DEFAULT, CH_FLAGS_GLOBAL, or CH_FLAGS_WRITE
Returns
pointer to a configuration file object that can be queried, or NULL on error

open conf file (if it exists), optionally for writing. Creates file as needed (write mode only)
write mode for global config may require root privileges
when done, you must close the returned configuration file object pointer with CHCloseConfFile
The function may block as needed. Use CHDestroyConfFile to close AND free memory resources.

Header File: conf_help.h

Definition at line 637 of file conf_help.c.

int CHWriteConfFileInt ( void *  hFile,
const char *  szSection,
const char *  szIdentifier,
int  iData 
)

write an integer value to a configuration file

Parameters
hFilethe configuration file object pointer returned by CHOpenConfFile
szSectiona pointer to an ASCII 0-byte terminated string containing the section name
szIdentifiera pointer to an ASCII 0-byte terminated string identifying the (unique) data entry
iDatathe integer data value
Returns
non-zero value on success, or zero on error

Writes an integer value to the configuration file for 'szIdentifier' in 'szSection'. The function returns a non-zero value if successful, or a value of 0 if an error occurred.

Header File: conf_help.h

Definition at line 1643 of file conf_help.c.

int CHWriteConfFileString ( void *  hFile,
const char *  szSection,
const char *  szIdentifier,
const char *  szData 
)

write a string to a configuration file

Parameters
hFilethe configuration file object pointer returned by CHOpenConfFile
szSectiona pointer to an ASCII 0-byte terminated string containing the section name
szIdentifiera pointer to an ASCII 0-byte terminated string identifying the (unique) data entry
szDataa buffer pointer to an ASCII 0-byte terminated string containing the data value
Returns
non-zero value on success, or zero on error

Writes a string value to the configuration file for 'szIdentifier' in 'szSection'. The function returns a non-zero value if successful, or a value of 0 if an error occurred.

Header File: conf_help.h

Definition at line 1357 of file conf_help.c.