awn-config-client

## awn-config-client awn-config-client — The configuration API for both Awn proper and Awn applets. `include` libawn/awn-config-client.h |

## Synopsis

                        AwnConfigClient;
    #define             AWN_CONFIG_CLIENT                   (obj)
                        AwnConfigClientNotifyEntry;
    void                (*AwnConfigClientNotifyFunc)        (AwnConfigClientNotifyEntry *entry,
                                                             gpointer user_data);
    #define             AWN_CONFIG_CLIENT_DEFAULT_GROUP
    enum                AwnConfigValueType;
    enum                AwnConfigListType;
    AwnConfigClient *   awn_config_client_new               ();
    AwnConfigClient *   awn_config_client_new_for_applet    (gchar *name,
                                                             gchar *uid);
    void                awn_config_client_clear             (AwnConfigClient *client,
                                                             GError **err);
    void                awn_config_client_ensure_group      (AwnConfigClient *client,
                                                             const gchar *group);
    void                awn_config_client_notify_add        (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             AwnConfigClientNotifyFunc callback,
                                                             gpointer user_data);
    gboolean            awn_config_client_entry_exists      (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key);
    gboolean            awn_config_client_get_bool          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);
    void                awn_config_client_set_bool          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gboolean value,
                                                             GError **err);
    gfloat              awn_config_client_get_float         (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);
    void                awn_config_client_set_float         (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gfloat value,
                                                             GError **err);
    gint                awn_config_client_get_int           (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);
    void                awn_config_client_set_int           (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gint value,
                                                             GError **err);
    gchar *             awn_config_client_get_string        (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);
    void                awn_config_client_set_string        (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gchar *value,
                                                             GError **err);
    GSList *            awn_config_client_get_list          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             AwnConfigListType list_type,
                                                             GError **err);
    void                awn_config_client_set_list          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             AwnConfigListType list_type,
                                                             GSList *value,
                                                             GError **err);

## Description

A configuration wrapper API that supports both a GConf backend, as well as a GKeyFile-based backend. Used for both Awn proper and its applets.

## Details

### AwnConfigClient

    typedef struct _AwnConfigClient AwnConfigClient;

An opaque structure that facilitates having multiple configuration backends available to Awn.

### AWN_CONFIG_CLIENT()

    #define AWN_CONFIG_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), AWN_TYPE_CONFIG_CLIENT, AwnConfigClient))

Casts a variable/value to be an AwnConfigClient.

`obj` : | The variable/value to cast

### AwnConfigClientNotifyEntry

    typedef struct {
    	AwnConfigClient *client;
    	gchar *group;
    	gchar *key;
    	AwnConfigClientValue value;
    } AwnConfigClientNotifyEntry;

The structure used to transport data to the notification functions of a configuration entry.

AwnConfigClient *`client`; | The client associated with the entry.
gchar *`group`; | The group name of the entry.
gchar *`key`; | The key name of the entry.
AwnConfigClientValue `value`; | The new value of the entry.

### AwnConfigClientNotifyFunc ()

    void                (*AwnConfigClientNotifyFunc)        (AwnConfigClientNotifyEntry *entry,
                                                             gpointer user_data);

The callback template for configuration change notification functions.

`entry` : | The metadata about the new entry value.
`user_data` : |

### AWN_CONFIG_CLIENT_DEFAULT_GROUP

    #define AWN_CONFIG_CLIENT_DEFAULT_GROUP "DEFAULT"

In the GKeyFile backend, the group name with which "top-level" configuration entries are associated.

### enum AwnConfigValueType

    typedef enum {
    	AWN_CONFIG_VALUE_TYPE_NULL = -1,
    	AWN_CONFIG_VALUE_TYPE_BOOL,
    	AWN_CONFIG_VALUE_TYPE_FLOAT,
    	AWN_CONFIG_VALUE_TYPE_INT,
    	AWN_CONFIG_VALUE_TYPE_STRING,
    	AWN_CONFIG_VALUE_TYPE_LIST_BOOL,
    	AWN_CONFIG_VALUE_TYPE_LIST_FLOAT,
    	AWN_CONFIG_VALUE_TYPE_LIST_INT,
    	AWN_CONFIG_VALUE_TYPE_LIST_STRING
    } AwnConfigValueType;

Indicates the value type of a particular configuration entry.

`AWN_CONFIG_VALUE_TYPE_NULL` | Indicates that the configuration value type is unknown.
`AWN_CONFIG_VALUE_TYPE_BOOL` | Indicates that the configuration value type is boolean.
`AWN_CONFIG_VALUE_TYPE_FLOAT` | Indicates that the configuration value type is float.
`AWN_CONFIG_VALUE_TYPE_INT` | Indicates that the configuration value type is integer.
`AWN_CONFIG_VALUE_TYPE_STRING` | Indicates that the configuration value type is string.
`AWN_CONFIG_VALUE_TYPE_LIST_BOOL` | Indicates that the configuration value type is list whose items are booleans.
`AWN_CONFIG_VALUE_TYPE_LIST_FLOAT` | Indicates that the configuration value type is list whose items are floats.
`AWN_CONFIG_VALUE_TYPE_LIST_INT` | Indicates that the configuration value type is list whose items are integers.
`AWN_CONFIG_VALUE_TYPE_LIST_STRING` | Indicates that the configuration value type is list whose items are strings.

### enum AwnConfigListType

    typedef enum {
    	AWN_CONFIG_CLIENT_LIST_TYPE_BOOL,
    	AWN_CONFIG_CLIENT_LIST_TYPE_FLOAT,
    	AWN_CONFIG_CLIENT_LIST_TYPE_INT,
    	AWN_CONFIG_CLIENT_LIST_TYPE_STRING
    } AwnConfigListType;

Indicates the value type of every item in a configuration entry of type "list".

`AWN_CONFIG_CLIENT_LIST_TYPE_BOOL` | Indicates that the list value type is boolean.
`AWN_CONFIG_CLIENT_LIST_TYPE_FLOAT` | Indicates that the list value type is float.
`AWN_CONFIG_CLIENT_LIST_TYPE_INT` | Indicates that the list value type is integer.
`AWN_CONFIG_CLIENT_LIST_TYPE_STRING` | Indicates that the list value type is string.

### awn_config_client_new ()

    AwnConfigClient *   awn_config_client_new               ();

Retrieves the configuration client for Awn proper. If none exists, one is created.

Returns : | a singleton instance of AwnConfigClient.

### awn_config_client_new_for_applet ()

    AwnConfigClient *   awn_config_client_new_for_applet    (gchar *name,
                                                             gchar *uid);

Creates a configuration client for the applet named in the parameter. If `uid` is not defined, it is implied that the applet is a singleton.

`name` : | The name of the applet.
`uid` : | The unique identifier for the applet (used for positioning on the dock). Optional value (i.e., may be `NULL`).
Returns : | an instance of AwnConfigClient for the specified applet.

### awn_config_client_clear ()

    void                awn_config_client_clear             (AwnConfigClient *client,
                                                             GError **err);

Removes all of the configuration entries from the client.

`client` : | The configuration client that is to be used.
`err` : | The pointer to the GError structure that contains an error message on failure.

### awn_config_client_ensure_group ()

    void                awn_config_client_ensure_group      (AwnConfigClient *client,
                                                             const gchar *group);

Ensures that the `group` named has been created in the configuration backend.

`client` : | The configuration client to be queried.
`group` : | The name of the group.

### awn_config_client_notify_add ()

    void                awn_config_client_notify_add        (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             AwnConfigClientNotifyFunc callback,
                                                             gpointer user_data);

Associates a callback function with a group and a key, which is called when that key's value has been modified in some way.

`client` : | The configuration client that is to be used.
`group` : | The name of the group.
`key` : | The name of the key.
`callback` : | The function that is called when the key value has been modified.
`user_data` : | Extra data that is passed to the callback.

### awn_config_client_entry_exists ()

    gboolean            awn_config_client_entry_exists      (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key);

Determines whether the group and key exists in the configuration backend.

`client` : | The configuration client that is to be queried.
`group` : | The name of the group.
`key` : | The name of the key.
Returns : | `TRUE` on success, `FALSE` otherwise.

### awn_config_client_get_bool ()

    gboolean            awn_config_client_get_bool          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);

Retrieves the value (as a boolean) of the specified group and key.

`client` : | The configuration client that is to be queried.
`group` : | The name of the group.
`key` : | The name of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.
Returns : | a boolean value.

### awn_config_client_set_bool ()

    void                awn_config_client_set_bool          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gboolean value,
                                                             GError **err);

Changes the value (as a boolean) of the specified group and key.

`client` : | The configuration client that is to be used.
`group` : | The name of the group.
`key` : | The name of the key.
`value` : | The new value of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.

### awn_config_client_get_float ()

    gfloat              awn_config_client_get_float         (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);

Retrieves the value (as a float) of the specified group and key.

`client` : | The configuration client that is to be queried.
`group` : | The name of the group.
`key` : | The name of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.
Returns : | a float value.

### awn_config_client_set_float ()

    void                awn_config_client_set_float         (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gfloat value,
                                                             GError **err);

Changes the value (as a float) of the specified group and key. If you need double precision, use a string.

`client` : | The configuration client that is to be used.
`group` : | The name of the group.
`key` : | The name of the key.
`value` : | The new value of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.

### awn_config_client_get_int ()

    gint                awn_config_client_get_int           (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);

Retrieves the value (as an integer) of the specified group and key.

`client` : | The configuration client that is to be queried.
`group` : | The name of the group.
`key` : | The name of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.
Returns : | an integer value.

### awn_config_client_set_int ()

    void                awn_config_client_set_int           (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gint value,
                                                             GError **err);

Changes the value (as an integer) of the specified group and key.

`client` : | The configuration client that is to be used.
`group` : | The name of the group.
`key` : | The name of the key.
`value` : | The new value of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.

### awn_config_client_get_string ()

    gchar *             awn_config_client_get_string        (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             GError **err);

Retrieves the value (as a string) of the specified group and key.

`client` : | The configuration client that is to be queried.
`group` : | The name of the group.
`key` : | The name of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.
Returns : | a newly allocated string value. The caller is responsible for freeing the memory.

### awn_config_client_set_string ()

    void                awn_config_client_set_string        (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             gchar *value,
                                                             GError **err);

Changes the value (as a string) of the specified group and key.

`client` : | The configuration client that is to be used.
`group` : | The name of the group.
`key` : | The name of the key.
`value` : | The new value of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.

### awn_config_client_get_list ()

    GSList *            awn_config_client_get_list          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             AwnConfigListType list_type,
                                                             GError **err);

Retrieves the value (as a GSList) of the specified group and key.

`client` : | The configuration client that is to be queried.
`group` : | The name of the group.
`key` : | The name of the key.
`list_type` : | The value type of every item in the list.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.
Returns : | a newly allocated list value. The caller is responsible for freeing the memory.

### awn_config_client_set_list ()

    void                awn_config_client_set_list          (AwnConfigClient *client,
                                                             const gchar *group,
                                                             const gchar *key,
                                                             AwnConfigListType list_type,
                                                             GSList *value,
                                                             GError **err);

Changes the value (as a list of values) of the specified group and key.

`client` : | The configuration client that is to be used.
`group` : | The name of the group.
`key` : | The name of the key.
`list_type` : | The value type of every item in the list.
`value` : | The new value of the key.
`err` : | A pointer to a GError structure, which contains an error message if the function fails.