settings

settings

Synopsis




typedef     boolean;
enum        error_t;
enum        type_t;
enum        action_t;
void        (*SettingNotifyFunc)            (int setting,
                                             int id,
                                             const char *key,
                                             type_t type,
                                             action_t action,
                                             void *user_data);
int         setting_open                    (void);
void        setting_close                   (int setting);
error_t     setting_notify_add              (int setting,
                                             const char *key,
                                             SettingNotifyFunc func,
                                             void *user_data,
                                             int *id);
void        setting_notify_remove           (int setting,
                                             int id);
error_t     setting_set_int                 (int setting,
                                             const char *key,
                                             int value);
error_t     setting_set_boolean             (int setting,
                                             const char *key,
                                             boolean value);
error_t     setting_set_string              (int setting,
                                             const char *key,
                                             const char *value);
error_t     setting_get_int                 (int setting,
                                             const char *key,
                                             int *value);
error_t     setting_get_boolean             (int setting,
                                             const char *key,
                                             boolean *value);
error_t     setting_get_string              (int setting,
                                             const char *key,
                                             char **value);
boolean     setting_entry_exist             (int setting,
                                             const char *key);
error_t     setting_entry_get_type          (int setting,
                                             const char *key,
                                             type_t *type);

Description

Details

boolean

typedef int   boolean;


enum error_t

typedef enum
{
  SETTING_ERROR_SUCCESS = 0, /*success*/
  SETTING_ERROR_BAD_KEY = 1, /*The key name is invalid, maybe it includes some invalid characters*/
  SETTING_ERROR_PARSE_ERROR = 2, /*Syntax error while parsing*/ 
  SETTING_ERROR_NO_PERM = 3, /*No permission for the performance*/
  SETTING_ERROR_TYPE_MISMATCH = 4, /*type requested doesn't match type found*/ 
  SETTING_ERROR_ENTRY_EXIST = 5, /*the entry already exists*/
  SETTING_ERROR_ENTRY_NOT_EXIST = 6, /*the entry doesn't exist*/ 
  SETTING_ERROR_BACKEND_LOST = 7 /*connectioin to the setting backend is lost*/
} error_t;


enum type_t

typedef enum  
{
  SETTING_TYPE_INT = 0,
  SETTING_TYPE_BOOLEAN,
  SETTING_TYPE_STRING,
  SETTING_TYPE_INVALID
} type_t;


enum action_t

typedef enum 
{
  SETTING_ACTION_REMOVE = 0, /*the entry has just been removed*/
  SETTING_ACTION_ADD, /*a new entry has just been added*/
  SETTING_ACTION_CHANGE /*the value of the entry has just been changed*/
} action_t;


SettingNotifyFunc ()

void        (*SettingNotifyFunc)            (int setting,
                                             int id,
                                             const char *key,
                                             type_t type,
                                             action_t action,
                                             void *user_data);

The prototype of callback function for handling notifications.

setting : the handle to the setting backend
id : returned from setting_notify_add.
key : the key of an entry.
type : the type of the value stored in the entry
action : an action_t, telling what had happend to the entry.
user_data : user provided data from setting_notify_add.

setting_open ()

int         setting_open                    (void);

Get the handle to access the setting system, the returned value should be used in subsequent setting function calls.

Returns : a handle to the setting backend

setting_close ()

void        setting_close                   (int setting);

Terminates the connection with the setting backend.

setting : the setting handle returned from setting_open()

setting_notify_add ()

error_t     setting_notify_add              (int setting,
                                             const char *key,
                                             SettingNotifyFunc func,
                                             void *user_data,
                                             int *id);

Register a callback for the value change of certain entriess. When changes happen to the entry(ies) represented (contained) by key, func will be invoked. Each call to setting_notify_add will return an integer which represents the connection ID for that notification. This connection ID can be used later by setting_notify_remove.

setting : the Setting handle.
key : includes the key(s) in which your application is interested.
func : the function to be called to handle value changes of the keys in branch.
user_data : user provided data.
id : conncetion ID for later removing of the notify.
Returns : error.

setting_notify_remove ()

void        setting_notify_remove           (int setting,
                                             int id);

Revoke the callback added by setting_notify_add.

setting : the Setting handle.
id : returned from setting_notify_add.

setting_set_int ()

error_t     setting_set_int                 (int setting,
                                             const char *key,
                                             int value);

Set the value of an entry whose type is SETTING_TYPE_INT.

setting : the Setting handle.
key : the key representing an entry.
value : the new value of this entry.
Returns : error number.

setting_set_boolean ()

error_t     setting_set_boolean             (int setting,
                                             const char *key,
                                             boolean value);

Set the value of an entry whose type is SETTING_TYPE_BOOLEAN.

setting : the Setting handle.
key : the key representing an entry.
value : the new value of this entry.
Returns : error number.

setting_set_string ()

error_t     setting_set_string              (int setting,
                                             const char *key,
                                             const char *value);

Set the value of an entry whose type is SETTING_TYPE_STRING.

setting : the Setting handle.
key : the key representing an entry.
value : the new value of this entry.
Returns : error number.

setting_get_int ()

error_t     setting_get_int                 (int setting,
                                             const char *key,
                                             int *value);

Get the value of an entry whose type is SETTING_TYPE_INT.

setting : the Setting handle.
key : the key representing an entry.
value : the return location for the value of this entry.
Returns : error number.

setting_get_boolean ()

error_t     setting_get_boolean             (int setting,
                                             const char *key,
                                             boolean *value);

Get the value of an entry whose type is SETTING_TYPE_BOOLEAN.

setting : the Setting handle.
key : the key representing an entry.
value : the return location for the value of this entry.
Returns : error number.

setting_get_string ()

error_t     setting_get_string              (int setting,
                                             const char *key,
                                             char **value);

Get the value of an entry whose type is SETTING_TYPE_STRING. The returned string should be freed when no longer needed.

setting : the Setting handle.
key : the key representing an entry.
value : the return location for the value of this entry, on error, NULL is returned.
Returns : error number.

setting_entry_exist ()

boolean     setting_entry_exist             (int setting,
                                             const char *key);

Check whether an entry exists.

setting : the Setting handle.
key : the key representing an entry.
Returns : TRUE if entry exists

setting_entry_get_type ()

error_t     setting_entry_get_type          (int setting,
                                             const char *key,
                                             type_t *type);

Get the type of an entry

setting : the Setting handle.
key : the key representing an entry.
type : the return location for the type of this entry
Returns : error number