MiniGUI API Reference (MiniGUI-Processes)  v3.2.0
A mature and proven cross-platform GUI system for embedded and smart IoT devices
Data Structures | Macros | Typedefs | Functions | Variables
Configuration file operations

Data Structures

struct  _ETCSECTION
 
struct  _ETC_S
 

Macros

#define ETC_MAXLINE   1024
 The max line number of etc file. More...
 
#define ETC_FILENOTFOUND   -1
 No found etc file. More...
 
#define ETC_SECTIONNOTFOUND   -2
 No found section in etc file. More...
 
#define ETC_KEYNOTFOUND   -3
 No found key in etc file. More...
 
#define ETC_TMPFILEFAILED   -4
 Create tmpfile failed. More...
 
#define ETC_FILEIOFAILED   -5
 IO operation failed to etc file. More...
 
#define ETC_INTCONV   -6
 Convert the value string to an integer failed. More...
 
#define ETC_INVALIDOBJ   -7
 Invalid object to etc file. More...
 
#define ETC_READONLYOBJ   -8
 Read only to etc file. More...
 
#define ETC_OK   0
 Operate success to etc file. More...
 
#define SetValueToEtc(hEtc, pSection, pKey, pValue)   GetValueFromEtc(hEtc, pSection, pKey, pValue, -1)
 Sets the value in the etc object. More...
 

Typedefs

typedef struct _ETCSECTION ETCSECTION
 
typedef ETCSECTIONPETCSECTION
 
typedef struct _ETC_S ETC_S
 

Functions

MG_EXPORT int GUIAPI GetValueFromEtcFile (const char *pEtcFile, const char *pSection, const char *pKey, char *pValue, int iLen)
 Gets value from a configuration file. More...
 
MG_EXPORT int GUIAPI GetIntValueFromEtcFile (const char *pEtcFile, const char *pSection, const char *pKey, int *value)
 Gets integer value from a configuration file. More...
 
MG_EXPORT int GUIAPI SetValueToEtcFile (const char *pEtcFile, const char *pSection, const char *pKey, char *pValue)
 Sets a value in a configuration file. More...
 
MG_EXPORT int GUIAPI RemoveSectionInEtcFile (const char *pEtcFile, const char *pSection)
 Removes a section in an etc file. More...
 
MG_EXPORT int GUIAPI SaveSectionToEtcFile (const char *pEtcFile, PETCSECTION psect)
 Saves a section to an etc file. More...
 
MG_EXPORT GHANDLE GUIAPI LoadEtcFile (const char *pEtcFile)
 Loads an etc file into memory. More...
 
MG_EXPORT int GUIAPI SaveEtcToFile (GHANDLE hEtc, const char *file_name)
 Saves an ETC object into a file. More...
 
MG_EXPORT int GUIAPI UnloadEtcFile (GHANDLE hEtc)
 Unloads an etc file. More...
 
MG_EXPORT int GUIAPI GetValueFromEtc (GHANDLE hEtc, const char *pSection, const char *pKey, char *pValue, int iLen)
 Gets value from a configuration etc object. More...
 
MG_EXPORT int GUIAPI GetIntValueFromEtc (GHANDLE hEtc, const char *pSection, const char *pKey, int *pValue)
 Gets the integer value from a configuration etc object. More...
 
MG_EXPORT GHANDLE GUIAPI FindSectionInEtc (GHANDLE hEtc, const char *pSection, BOOL bCreateNew)
 Finds/Creates a section from an etc object. More...
 
MG_EXPORT int GUIAPI GetValueFromEtcSec (GHANDLE hSect, const char *pKey, char *pValue, int iLen)
 Gets value from an etc section object. More...
 
MG_EXPORT int GUIAPI GetIntValueFromEtcSec (GHANDLE hSect, const char *pKey, int *pValue)
 Gets an integer value from an etc section object. More...
 
MG_EXPORT int GUIAPI SetValueToEtcSec (GHANDLE hSect, const char *pKey, char *pValue)
 Sets the value in the etc section object. More...
 
MG_EXPORT int GUIAPI RemoveSectionInEtc (GHANDLE hEtc, const char *pSection)
 Removes a section in etc object. More...
 
static int GetMgEtcValue (const char *pSection, const char *pKey, char *pValue, int iLen)
 Gets value from MiniGUI configuration etc object. More...
 
static int GetMgEtcIntValue (const char *pSection, const char *pKey, int *value)
 Gets integer value from MiniGUI configuration etc object. More...
 

Variables

MG_EXPORT char ETCFILEPATH []
 The path name of MiniGUI configuration file. More...
 

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;
}

Macro Definition Documentation

#define ETC_FILEIOFAILED   -5

IO operation failed to etc file.

Definition at line 1805 of file minigui.h.

#define ETC_FILENOTFOUND   -1

No found etc file.

Definition at line 1785 of file minigui.h.

#define ETC_INTCONV   -6

Convert the value string to an integer failed.

Definition at line 1810 of file minigui.h.

#define ETC_INVALIDOBJ   -7

Invalid object to etc file.

Definition at line 1815 of file minigui.h.

#define ETC_KEYNOTFOUND   -3

No found key in etc file.

Definition at line 1795 of file minigui.h.

#define ETC_MAXLINE   1024

The max line number of etc file.

Definition at line 1779 of file minigui.h.

#define ETC_OK   0

Operate success to etc file.

Definition at line 1825 of file minigui.h.

#define ETC_READONLYOBJ   -8

Read only to etc file.

Definition at line 1820 of file minigui.h.

#define ETC_SECTIONNOTFOUND   -2

No found section in etc file.

Definition at line 1790 of file minigui.h.

#define ETC_TMPFILEFAILED   -4

Create tmpfile failed.

Definition at line 1800 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 2121 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 1842 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
hEtcHandle to the etc object.
pSectionThe name of the section.
bCreateNewIndicate 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
pEtcFileThe path name of the configuration file.
pSectionThe section name in which the value located.
pKeyThe key name of the value.
valueThe integer value will be saved in this buffer.
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKGets value successfullly.
ETC_FILENOTFOUNDCan not find the specified configuration file.
ETC_SECTIONNOTFOUNDCan not find the specified section in the configuration file.
ETC_KEYNOTFOUNDCan not find the specified key in the section.
ETC_FILEIOFAILEDFile I/O operation error occurred.
ETC_INTCONVCan 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
hSectThe handle to the section.
pKeyThe key name of the value.
pValueThe value will be saved in this buffer.
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKGets value successfullly.
ETC_INVALIDOBJInvalid etc object.
ETC_KEYNOTFOUNDCan not find the specified key in the section.
ETC_INTCONVCan 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 
)
inlinestatic

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 2265 of file minigui.h.

References GetIntValueFromEtc(), and GetIntValueFromEtcFile().

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

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 2245 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
hEtcHandle to the etc object.
pSectionThe section name in which the value located.
pKeyThe key name of the value.
pValueThe value will be saved in this buffer.
iLenThe 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_OKGets value successfullly.
ETC_INVALIDOBJInvalid etc object.
ETC_SECTIONNOTFOUNDCan not find the specified section in the configuration file.
ETC_KEYNOTFOUNDCan not find the specified key in the section.
ETC_READONLYOBJThe 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
pEtcFileThe path name of the configuration file.
pSectionThe section name in which the value located.
pKeyThe key name of the value.
pValueThe value will be saved in this buffer.
iLenThe length in bytes of the buffer.
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKGets value successfullly.
ETC_FILENOTFOUNDCan not find the specified configuration file.
ETC_SECTIONNOTFOUNDCan not find the specified section in the configuration file.
ETC_KEYNOTFOUNDCan not find the specified key in the section.
ETC_FILEIOFAILEDFile 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
hSectThe handle to the section.
pKeyThe key name of the value.
pValueThe value will be saved in this buffer.
iLenThe 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_OKGets value successfullly.
ETC_INVALIDOBJInvalid etc object.
ETC_KEYNOTFOUNDCan not find the specified key in the section.
ETC_READONLYOBJThe 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
pEtcFileThe 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
hEtcThe handle to the etc object.
pSectionThe name of the pSection;
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKGets value successfullly.
ETC_INVALIDOBJInvalid etc object.
ETC_READONLYOBJThe etc object is read-only.
ETC_SECTIONNOTFOUNDCan 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
pEtcFileThe name of the etc file.
pSectionThe name of the pSection;
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKGets value successfullly.
ETC_FILEIOFAILEDFile I/O operation error occurred.
ETC_SECTIONNOTFOUNDCan 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
hEtcHandle to the etc object.
file_nameThe name of the target file.
Returns
ETC_OK on success, 0 < on error.
Return values
ETC_OKSets the etc object successfullly.
ETC_INVALIDOBJInvalid etc object.
ETC_FILEIOFAILEDFile 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
pEtcFileThe name of the etc file.
psectThe name of the psect;
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKGets value successfullly.
ETC_FILEIOFAILEDFile I/O operation error occurred.
ETC_SECTIONNOTFOUNDCan 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
pEtcFileThe path name of the configuration file.
pSectionThe section name in which the value located.
pKeyThe key name of the value.
pValueThe null-terminated value string.
Returns
ETC_OK on success, < 0 on error.
Return values
ETC_OKSets value successfullly.
ETC_FILEIOFAILEDFile I/O operation error occurred.
ETC_TMPFILEFAILEDCan 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
hEtcHandle 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.