Configuration file operations
[MiniGUI-Processes specific functions]

Data Structures

Defines

Typedefs

Functions

Variables


Detailed Description

The configuration file used by MiniGUI have a similiar format as M$ Windows INI file, i.e. the file consists of sections, and the section consists of key-value pairs, like this:

 [system]
 # GAL engine
 gal_engine=fbcon

 # IAL engine
 ial_engine=console

 mdev=/dev/mouse
 mtype=PS2
 
 [fbcon]
 defaultmode=1024x768-16bpp
 
 [qvfb]
 defaultmode=640x480-16bpp
 display=0

Assume that the configuration file named my.cfg, if you want get the value of mdev in system section, you can call GetValueFromEtcFile in the following way:

 char buffer [51];

 GetValueFromEtcFile ("my.cfg", "system", "mdev", buffer, 51);

Example:

/*
 * The following code is used by MDE to get the applications information.
 *
 * It gets the information from a INI-like configuration file.
 */

#define APP_INFO_FILE "mginit.rc"

static BOOL get_app_info (void)
{
    int i;
    APPITEM* item;

    /* Get the number of the applications */
    if (GetIntValueFromEtcFile (APP_INFO_FILE, "mginit", "nr", &app_info.nr_apps) != ETC_OK)
        return FALSE;

    if (app_info.nr_apps <= 0)
        return FALSE;

    /* Get the index of the autostart application. */
    GetIntValueFromEtcFile (APP_INFO_FILE, "mginit", "autostart", &app_info.autostart);

    if (app_info.autostart >= app_info.nr_apps || app_info.autostart < 0)
        app_info.autostart = 0;

    /* Allocate application information structures. */
    if ((app_info.app_items = (APPITEM*)calloc (app_info.nr_apps, sizeof (APPITEM))) == NULL) {
        return FALSE;
    }

    /* Get the path, name, and icon of every application. */
    item = app_info.app_items;
    for (i = 0; i < app_info.nr_apps; i++, item++) {
        char section [10];

        sprintf (section, "app%d", i);
        if (GetValueFromEtcFile (APP_INFO_FILE, section, "path", item->path, PATH_MAX) != ETC_OK)
            goto error;

        if (GetValueFromEtcFile (APP_INFO_FILE, section, "name", item->name, NAME_MAX) != ETC_OK)
            goto error;

        if (GetValueFromEtcFile (APP_INFO_FILE, section, "layer", item->layer, LEN_LAYER_NAME) != ETC_OK)
            goto error;

        if (GetValueFromEtcFile (APP_INFO_FILE, section, "tip", item->tip, TIP_MAX) != ETC_OK)
            goto error;

        strsubchr (item->tip, '&', ' ');

        if (GetValueFromEtcFile (APP_INFO_FILE, section, "icon", item->bmp_path, PATH_MAX + NAME_MAX) != ETC_OK)
            goto error;

        if (LoadBitmap (HDC_SCREEN, &item->bmp, item->bmp_path) != ERR_BMP_OK)
            goto error;

        item->cdpath = TRUE;
    }
    return TRUE;

error:
    free_app_info ();
    return FALSE;
}

Define Documentation

#define ETC_FILEIOFAILED   -5

IO operation failed to etc file.

Definition at line 1784 of file minigui.h.

#define ETC_FILENOTFOUND   -1

No found etc file.

Definition at line 1764 of file minigui.h.

#define ETC_INTCONV   -6

Convert the value string to an integer failed.

Definition at line 1789 of file minigui.h.

#define ETC_INVALIDOBJ   -7

Invalid object to etc file.

Definition at line 1794 of file minigui.h.

#define ETC_KEYNOTFOUND   -3

No found key in etc file.

Definition at line 1774 of file minigui.h.

#define ETC_MAXLINE   1024

The max line number of etc file.

Definition at line 1758 of file minigui.h.

#define ETC_OK   0

Operate success to etc file.

Definition at line 1804 of file minigui.h.

#define ETC_READONLYOBJ   -8

Read only to etc file.

Definition at line 1799 of file minigui.h.

#define ETC_SECTIONNOTFOUND   -2

No found section in etc file.

Definition at line 1769 of file minigui.h.

#define ETC_TMPFILEFAILED   -4

Create tmpfile failed.

Definition at line 1779 of file minigui.h.

#define SetValueToEtc ( hEtc,
pSection,
pKey,
pValue   )     GetValueFromEtc(hEtc, pSection, pKey, pValue, -1)

Sets the value in the etc object.

This fuctions sets the value in the etc object, somewhat similiar to

See also:
SetValueToEtcFile.
SetValueToEtcFile, GetValueFromEtc

Definition at line 2100 of file minigui.h.


Typedef Documentation

typedef struct _ETC_S ETC_S

ETC_S The current config file information

typedef struct _ETCSECTION ETCSECTION

Etc The current config section information

Data type of pointer to a ETCSECTION

Definition at line 1821 of file minigui.h.


Function Documentation

GHANDLE GUIAPI FindSectionInEtc ( GHANDLE  hEtc,
const char *  pSection,
BOOL  bCreateNew 
)

Finds/Creates a section from an etc object.

This function look for a section named pSection from the etc object hEtc. If there is no such section in the etc object and bCreateNew is TRUE, the function will create an empty section.

Parameters:
hEtc Handle to the etc object.
pSection The name of the section.
bCreateNew Indicate whether to create a new section.
Returns:
The handle to the section, 0 if not found or creatation failed.
See also:
GetValueFromEtcSec, GetIntValueFromEtcSec, SetValueInEtcSec
int GUIAPI GetIntValueFromEtc ( GHANDLE  hEtc,
const char *  pSection,
const char *  pKey,
int *  pValue 
)

Gets the integer value from a configuration etc object.

See also:
GetValueFromEtc, GetIntValueFromEtcFile

Referenced by GetMgEtcIntValue().

int GUIAPI GetIntValueFromEtcFile ( const char *  pEtcFile,
const char *  pSection,
const char *  pKey,
int *  value 
)

Gets integer value from a configuration file.

This function gets the integer value of the key pKey in the section pSection of the configuration file pEtcFile, and returns the integer value through the buffer pointed to by value.

Parameters:
pEtcFile The path name of the configuration file.
pSection The section name in which the value located.
pKey The key name of the value.
value The integer value will be saved in this buffer.
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_FILENOTFOUND Can not find the specified configuration file.
ETC_SECTIONNOTFOUND Can not find the specified section in the configuration file.
ETC_KEYNOTFOUND Can not find the specified key in the section.
ETC_FILEIOFAILED File I/O operation error occurred.
ETC_INTCONV Can not convert the value string to an integer.
Note:
MiniGUI uses strtol to convert the string value to an integer, and pass the base as 0. Thus, the valid string value can be converted to integer should be in the following forms:
  • [+|-]0x[0-9|A-F]*
    Will be read in base 16.
  • [+|-]0[0-7]*
    Will be read in base 8.
  • [+|-][1-9][0-9]*
    Will be read in base 10.
See also:
GetValueFromEtcFile, SetValueToEtcFile, strtol(3)

Referenced by GetMgEtcIntValue().

int GUIAPI GetIntValueFromEtcSec ( GHANDLE  hSect,
const char *  pKey,
int *  pValue 
)

Gets an integer value from an etc section object.

This function gets an integer value from an etc section object, similar to GetIntValueFromEtc. It gets the value of the key pKey in the section hSect, and saves the value to the buffer pointed to by pValue.

Parameters:
hSect The handle to the section.
pKey The key name of the value.
pValue The value will be saved in this buffer.
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_INVALIDOBJ Invalid etc object.
ETC_KEYNOTFOUND Can not find the specified key in the section.
ETC_INTCONV Can not convert the value string to an integer.
See also:
GetValueFromEtcFile, GetValueFromEtc, FindSectionInEtc
static inline int GetMgEtcIntValue ( const char *  pSection,
const char *  pKey,
int *  value 
) [inline, static]

Gets integer value from MiniGUI configuration etc object.

This fuctions get integer value from MiniGUI configuration etc object some what similiar to GetIntValueFromEtcFile and GetIntValueFromEtc

See also:
GetIntValueFromEtcFile
GetIntValueFromEtc

Definition at line 2244 of file minigui.h.

References GetIntValueFromEtc(), and GetIntValueFromEtcFile().

static inline int GetMgEtcValue ( const char *  pSection,
const char *  pKey,
char *  pValue,
int  iLen 
) [inline, static]

Gets value from MiniGUI configuration etc object.

This fuctions gets the value from MiniGUi configuration etc object, somewhat similiar to GetValueFromEtcFile and GetValueFromEtc

See also:
GetValueFromEtcFile
GetValueFromEtc.

Definition at line 2224 of file minigui.h.

References GetValueFromEtc(), and GetValueFromEtcFile().

int GUIAPI GetValueFromEtc ( GHANDLE  hEtc,
const char *  pSection,
const char *  pKey,
char *  pValue,
int  iLen 
)

Gets value from a configuration etc object.

This function gets value from an etc object, similar to GetValueFromEtcFile. This function gets the value of the key pKey in the section pSection of the etc object hEtc, and saves the value to the buffer pointed to by pValue.

Parameters:
hEtc Handle to the etc object.
pSection The section name in which the value located.
pKey The key name of the value.
pValue The value will be saved in this buffer.
iLen The length in bytes of the buffer. This function will set value if the iLen is less than 1.
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_INVALIDOBJ Invalid etc object.
ETC_SECTIONNOTFOUND Can not find the specified section in the configuration file.
ETC_KEYNOTFOUND Can not find the specified key in the section.
ETC_READONLYOBJ The etc object is read-only.
See also:
GetValueFromEtcFile, LoadEtcFile, UnloadEtcFile

Referenced by GetMgEtcValue().

int GUIAPI GetValueFromEtcFile ( const char *  pEtcFile,
const char *  pSection,
const char *  pKey,
char *  pValue,
int  iLen 
)

Gets value from a configuration file.

This function gets the value of the key pKey in the section pSection of the configuration file pEtcFile, and saves the value to the buffer pointed to by pValue.

Parameters:
pEtcFile The path name of the configuration file.
pSection The section name in which the value located.
pKey The key name of the value.
pValue The value will be saved in this buffer.
iLen The length in bytes of the buffer.
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_FILENOTFOUND Can not find the specified configuration file.
ETC_SECTIONNOTFOUND Can not find the specified section in the configuration file.
ETC_KEYNOTFOUND Can not find the specified key in the section.
ETC_FILEIOFAILED File I/O operation error occurred.
Note:
MiniGUI use strncpy to copy actual value to pValue. Thus, if the length of the actual value is larger than iLen, the result copied to pValue will NOT be null-terminated.
See also:
GetIntValueFromEtcFile, SetValueToEtcFile, strncpy(3)

Referenced by GetMgEtcValue().

int GUIAPI GetValueFromEtcSec ( GHANDLE  hSect,
const char *  pKey,
char *  pValue,
int  iLen 
)

Gets value from an etc section object.

This function gets value from an etc section object, similar to GetValueFromEtc. It gets the value of the key pKey in the section hSect, and saves the value to the buffer pointed to by pValue.

Parameters:
hSect The handle to the section.
pKey The key name of the value.
pValue The value will be saved in this buffer.
iLen The length in bytes of the buffer. This function will set value if the iLen is less than 1.
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_INVALIDOBJ Invalid etc object.
ETC_KEYNOTFOUND Can not find the specified key in the section.
ETC_READONLYOBJ The section object is read-only.
See also:
GetValueFromEtcFile, GetValueFromEtc, FindSectionInEtc
GHANDLE GUIAPI LoadEtcFile ( const char *  pEtcFile  ) 

Loads an etc file into memory.

This function loads the content of an etc file into the memory, later, you can visit the content using GetValueFromEtc function.

Parameters:
pEtcFile The path name of the configuration file. If pEtcFile is NULL, the function will create an empty ETC object.
Returns:
Handle of the etc object on success, NULL on error.
See also:
UnloadEtcFile, GetValueFromEtc
int GUIAPI RemoveSectionInEtc ( GHANDLE  hEtc,
const char *  pSection 
)

Removes a section in etc object.

This function removes a section named pSection from the etc object hEtc.

Parameters:
hEtc The handle to the etc object.
pSection The name of the pSection;
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_INVALIDOBJ Invalid etc object.
ETC_READONLYOBJ The etc object is read-only.
ETC_SECTIONNOTFOUND Can not find the specified section in the etc object.
See also:
RemoveSectionInEtcFile
int GUIAPI RemoveSectionInEtcFile ( const char *  pEtcFile,
const char *  pSection 
)

Removes a section in an etc file.

This function removes a section named pSection from the etc file named pEtcFile.

Parameters:
pEtcFile The name of the etc file.
pSection The name of the pSection;
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_FILEIOFAILED File I/O operation error occurred.
ETC_SECTIONNOTFOUND Can not find the specified section in the etc object.
See also:
RemoveSectionInEtc
int GUIAPI SaveEtcToFile ( GHANDLE  hEtc,
const char *  file_name 
)

Saves an ETC object into a file.

This function saves the etc object into the file named file_name;

Parameters:
hEtc Handle to the etc object.
file_name The name of the target file.
Returns:
ETC_OK on success, 0 < on error.
Return values:
ETC_OK Sets the etc object successfullly.
ETC_INVALIDOBJ Invalid etc object.
ETC_FILEIOFAILED File I/O operation error occurred.
See also:
LoadEtcFile
int GUIAPI SaveSectionToEtcFile ( const char *  pEtcFile,
PETCSECTION  psect 
)

Saves a section to an etc file.

This function saves a section named psect to the etc file named pEtcFile.

Parameters:
pEtcFile The name of the etc file.
psect The name of the psect;
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Gets value successfullly.
ETC_FILEIOFAILED File I/O operation error occurred.
ETC_SECTIONNOTFOUND Can not find the specified section in the etc object.
int GUIAPI SetValueToEtcFile ( const char *  pEtcFile,
const char *  pSection,
const char *  pKey,
char *  pValue 
)

Sets a value in a configuration file.

This function sets the value of the key pKey in the section pSection of the configuration file pEtcFile to be the string pointed to by pValue.

Parameters:
pEtcFile The path name of the configuration file.
pSection The section name in which the value located.
pKey The key name of the value.
pValue The null-terminated value string.
Returns:
ETC_OK on success, < 0 on error.
Return values:
ETC_OK Sets value successfullly.
ETC_FILEIOFAILED File I/O operation error occurred.
ETC_TMPFILEFAILED Can not create temporary file.
Note:
If the specified configuration file does not exist, MiniGUI will try to create this file.
See also:
GetValueFromEtcFile, GetIntValueFromEtcFile
int GUIAPI SetValueToEtcSec ( GHANDLE  hSect,
const char *  pKey,
char *  pValue 
)

Sets the value in the etc section object.

This fuctions sets the value in the etc section object hSect, somewhat similiar to SetValueToEtc

See also:
SetValueToEtc.
GetValueFromEtc, FindSectionInEtc
GUIAPI UnloadEtcFile ( GHANDLE  hEtc  ) 

Unloads an etc file.

This function unloads the etc object generated by using

See also:
LoadEtcFile function.
Parameters:
hEtc Handle of the etc object.
Returns:
Returns 0 on success, -1 on error.
See also:
LoadEtcFile, GetValueFromEtc

Variable Documentation

char * ETCFILEPATH

The path name of MiniGUI configuration file.

By default, the configuration file of MiniGUI must be installed in /etc, /usr/local/etc or your home directory. When you install it in your home directory, the name should be ".MiniGUI.cfg".

MiniGUI will try to use MiniGUI.cfg in the current directory, ~/.MiniGUI.cfg, then /usr/local/etc/MiniGUI.cfg, and /etc/MiniGUI.cfg last.

If MiniGUI can not find any MiniGUI.cfg file, or find a bad formated configure file, the initialzation of MiniGUI will be canceled.

Generated on Thu Apr 7 15:58:39 2011 for MiniGUI V3.0.12 API Reference by  doxygen 1.6.3