MateConf Core Interfaces

## MateConf Core Interfaces MateConf Core Interfaces — Basic functions to initialize MateConf and get/set values |

## Synopsis

    gboolean            mateconf_init                          (int argc,
                                                             char **argv,
                                                             GError **err);
    void                mateconf_preinit                       (gpointer app,
                                                             gpointer mod_info);
    void                mateconf_postinit                      (gpointer app,
                                                             gpointer mod_info);
    gboolean            mateconf_is_initialized                (void);
    void                (*MateConfNotifyFunc)                  (MateConfEngine *conf,
                                                             guint cnxn_id,
                                                             MateConfEntry *entry,
                                                             gpointer user_data);
    guint               mateconf_engine_notify_add             (MateConfEngine *conf,
                                                             const gchar *namespace_section,
                                                             MateConfNotifyFunc func,
                                                             gpointer user_data,
                                                             GError **err);
    void                mateconf_engine_notify_remove          (MateConfEngine *conf,
                                                             guint cnxn);
    MateConfValue *        mateconf_engine_get                    (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    MateConfValue *        mateconf_engine_get_without_default    (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    MateConfEntry *        mateconf_engine_get_entry              (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             gboolean use_schema_default,
                                                             GError **err);
    MateConfValue *        mateconf_engine_get_with_locale        (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             GError **err);
    MateConfValue *        mateconf_engine_get_default_from_schema
                                                            (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_engine_set                    (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const MateConfValue *value,
                                                             GError **err);
    gboolean            mateconf_engine_unset                  (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_engine_associate_schema       (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *schema_key,
                                                             GError **err);
    GSList *            mateconf_engine_all_entries            (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);
    GSList *            mateconf_engine_all_dirs               (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);
    void                mateconf_engine_suggest_sync           (MateConfEngine *conf,
                                                             GError **err);
    gboolean            mateconf_engine_dir_exists             (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);
    void                mateconf_engine_remove_dir             (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);
    gboolean            mateconf_engine_key_is_writable        (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_valid_key                     (const gchar *key,
                                                             gchar **why_invalid);
    gboolean            mateconf_key_is_below                  (const gchar *above,
                                                             const gchar *below);
    gchar *             mateconf_concat_dir_and_key            (const gchar *dir,
                                                             const gchar *key);
    gchar *             mateconf_unique_key                    (void);
    char *              mateconf_escape_key                    (const char *arbitrary_text,
                                                             int len);
    char *              mateconf_unescape_key                  (const char *escaped_key,
                                                             int len);
    gdouble             mateconf_engine_get_float              (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    gint                mateconf_engine_get_int                (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    gchar *             mateconf_engine_get_string             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_engine_get_bool               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    MateConfSchema *       mateconf_engine_get_schema             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);
    GSList *            mateconf_engine_get_list               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GError **err);
    gboolean            mateconf_engine_get_pair               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gpointer car_retloc,
                                                             gpointer cdr_retloc,
                                                             GError **err);
    gboolean            mateconf_engine_set_float              (MateConfEngine *conf,
                                                             const gchar *key,
                                                             gdouble val,
                                                             GError **err);
    gboolean            mateconf_engine_set_int                (MateConfEngine *conf,
                                                             const gchar *key,
                                                             gint val,
                                                             GError **err);
    gboolean            mateconf_engine_set_string             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *val,
                                                             GError **err);
    gboolean            mateconf_engine_set_bool               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             gboolean val,
                                                             GError **err);
    gboolean            mateconf_engine_set_schema             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const MateConfSchema *val,
                                                             GError **err);
    gboolean            mateconf_engine_set_list               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GSList *list,
                                                             GError **err);
    gboolean            mateconf_engine_set_pair               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gconstpointer address_of_car,
                                                             gconstpointer address_of_cdr,
                                                             GError **err);
                        MateConfEnumStringPair;
    gboolean            mateconf_string_to_enum                (MateConfEnumStringPair lookup_table[],
                                                             const gchar *str,
                                                             gint *enum_value_retloc);
    const gchar *       mateconf_enum_to_string                (MateConfEnumStringPair lookup_table[],
                                                             gint enum_value);
    void                mateconf_clear_cache                   (MateConfEngine *conf,
                                                             GError **err);
    void                mateconf_synchronous_sync              (MateConfEngine *conf,
                                                             GError **err);
    MateConfValue *        mateconf_engine_get_full               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             gboolean use_schema_default,
                                                             gboolean *is_default_p,
                                                             gboolean *is_writable_p,
                                                             GError **err);

## Description

These functions initialize MateConf, and communicate with the mateconfd server via a MateConfEngine object. You can install a notification request on the server, get values, set values, list directories, and associate schema names with keys.

Most of this interface is replicated in the GObject wrapper (MateConfClient object); an alternative to the value-setting functions is the MateConfChangeSet interface.

## Details

### mateconf_init ()

    gboolean            mateconf_init                          (int argc,
                                                             char **argv,
                                                             GError **err);

### Warning

`mateconf_init` is deprecated and should not be used in newly-written code.

Initializes the MateConf library. Creates a connection to a CORBA ORB, and initializes OAF (the object activation framework) if it isn't already initialized.

`argc` : |
`argv` : |
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE otherwise.

### mateconf_preinit ()

    void                mateconf_preinit                       (gpointer app,
                                                             gpointer mod_info);

### Warning

`mateconf_preinit` is deprecated and should not be used in newly-written code.

`app` : |
`mod_info` : |

### mateconf_postinit ()

    void                mateconf_postinit                      (gpointer app,
                                                             gpointer mod_info);

### Warning

`mateconf_postinit` is deprecated and should not be used in newly-written code.

`app` : |
`mod_info` : |

### mateconf_is_initialized ()

    gboolean            mateconf_is_initialized                (void);

### Warning

`mateconf_is_initialized` is deprecated and should not be used in newly-written code.

Asks whether the library has been initialized.

Returns : | TRUE if the library has been initialized.

### MateConfNotifyFunc ()

    void                (*MateConfNotifyFunc)                  (MateConfEngine *conf,
                                                             guint cnxn_id,
                                                             MateConfEntry *entry,
                                                             gpointer user_data);

A callback function invoked when a key's value changes. The `cnxn_id` parameter will be the connection ID returned from `mateconf_engine_notify_add()`. `key` will be the full path of the changed key, `value` will be the new value if the key is set. If the key is unset, `value` will be the default value if one exists, or NULL otherwise. `is_default` indicates whether a value is a default setting or a user setting. If `value` is NULL, `is_default` will be TRUE. `user_data` is the data passed to `mateconf_engine_notify_add()`.

`conf` : | the MateConfEngine passed to `mateconf_engine_notify_add()`.
`cnxn_id` : | the ID returned from `mateconf_engine_notify_add()`.
`entry` : |
`user_data` : | the user data passed to `mateconf_engine_notify_add()`.

### mateconf_engine_notify_add ()

    guint               mateconf_engine_notify_add             (MateConfEngine *conf,
                                                             const gchar *namespace_section,
                                                             MateConfNotifyFunc func,
                                                             gpointer user_data,
                                                             GError **err);

Registers a notification request with the mateconfd server. The server will notify the client when any key at or below `namespace_section` is set or unset. Try to watch the smallest possible part of the namespace; otherwise you will slow down the server and your application with unnecessary notifications. Note that you should prefer `mateconf_client_notify_add()` if you're using the GObject wrapper library, because `mateconf_client_notify_add()` does not require a client-server conversation for every callback. `mateconf_engine_notify_add()` requests a different server notification for every callback. The function returns an ID you can use to remove the notification request; 0 is an invalid ID, and is returned if an error occurs.

`conf` : | a MateConfEngine to monitor for changes.
`namespace_section` : | the directory or key to watch; you will be notified of changes at or below this point.
`func` : | the callback to invoke when a notification is received from the server.
`user_data` : | the data to pass to the callback.
`err` : | the return location for an allocated GError, or NULL to ignore errors. Return value: an ID for the notification request, or 0 on error.
Returns : | value: an ID for the notification request, or 0 on error.

### mateconf_engine_notify_remove ()

    void                mateconf_engine_notify_remove          (MateConfEngine *conf,
                                                             guint cnxn);

Removes a notification request.

`conf` : | the MateConfEngine you were monitoring for changes.
`cnxn` : | The ID returned by `mateconf_engine_notify_add()`.

### mateconf_engine_get ()

    MateConfValue *        mateconf_engine_get                    (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Returns the MateConfValue stored at `key`, or NULL if no value is set. You must call `mateconf_value_free()` to free the returned value. If you know the expected type of the value, you probably want to use the type-specific convenience wrappers (`mateconf_engine_get_int()`, etc.) because they will do the type-checking for you and return the appropriate type. Automatically returns the default value for a key, if the key is unset and a default exists.

`conf` : | a MateConfEngine to get the value from.
`key` : | the key to get.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | newly-allocated MateConfValue, or NULL if unset and no default exists.

### mateconf_engine_get_without_default ()

    MateConfValue *        mateconf_engine_get_without_default    (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Identical to `mateconf_engine_get()`, except that it will return NULL in place of the default value if the key is unset. Note that `mateconf_engine_get()` can also return NULL if no default exists or an error occurs.

`conf` : | a MateConfEngine to get the value from.
`key` : | the key to get.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | newly-allocated MateConfValue, or NULL if unset.

### mateconf_engine_get_entry ()

    MateConfEntry *        mateconf_engine_get_entry              (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             gboolean use_schema_default,
                                                             GError **err);

Obtain the full MateConfEntry for a value.

`conf` : | a MateConfEngine.
`key` : | the key to get.
`locale` : | preferred locale (as in the locale-related environment variables).
`use_schema_default` : | a gboolean value indicating whether the default value associated with schema should be used.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | a MateConfEntry.

### mateconf_engine_get_with_locale ()

    MateConfValue *        mateconf_engine_get_with_locale        (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             GError **err);

Requests the value appropriate for a particular locale. Right now, only values of type `MATECONF_VALUE_SCHEMA` are localized; the locale is meaningless for other value types. Also, `mateconf_engine_get()` automatically requests the value in the user's current locale. So this function is only useful if you want a schema for some locale other than the user's current locale. Except for the additional argument, this function is identical to `mateconf_engine_get()` in all respects.

`conf` : | a MateConfEngine to get the value from.
`key` : | the key to get.
`locale` : | preferred locale (as in the locale-related environment variables).
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | newly-allocated MateConfValue, or NULL if unset.

### mateconf_engine_get_default_from_schema ()

    MateConfValue *        mateconf_engine_get_default_from_schema
                                                            (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Returns the default value stored in the key's schema, if the key has a schema associated and the schema exists and the schema contains a default value. Note that `mateconf_engine_get()`, `mateconf_engine_get_string()`, and so on already return the default value if no other value is found, so normally you do not need this function. This function is just for convenience; you could also get the MateConfMetaInfo for the key, read the schema name from there, then look up the schema by name and extract the default value.

`conf` : | a MateConfEngine to get the value from.
`key` : | the key to get the default value for.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | newly-allocated MateConfValue, or NULL if unset.

### mateconf_engine_set ()

    gboolean            mateconf_engine_set                    (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const MateConfValue *value,
                                                             GError **err);

Sets the value of `key` to `value`. Does not modify the passed-in MateConfValue, you must free it yourself. You may prefer a type-specific convenience wrapper, such as `mateconf_engine_set_int()`.

An error of note is `MATECONF_OVERRIDDEN`, indicating that the system administrator has "forced" a value for this key. If no writable configuration sources exist, it is not an error, but MateConf will just forget all your values; this allows users to have a configuration-free setup without a constant barrage of error messages.

`conf` : | a MateConfEngine to set the value in.
`key` : | the key to set.
`value` : | the new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_unset ()

    gboolean            mateconf_engine_unset                  (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Unsets the value of `key`; if `key` is already unset, has no effect. An error of note is `MATECONF_OVERRIDDEN`, indicating that the system administrator has "forced" a value for this key.

`conf` : | a MateConfEngine to affect.
`key` : | the key to unset.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_associate_schema ()

    gboolean            mateconf_engine_associate_schema       (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *schema_key,
                                                             GError **err);

Directs MateConf to find the schema for `key` at location `schema_key`. That is, the value stored at `schema_key` should have type MATECONF_VALUE_SCHEMA, and be descriptive of `key`. Normally you don't call this function from C code; you can ship a special file with your application and ask mateconftool to install schema associations into the database during "make install."

`conf` : | a MateConfEngine to affect.
`key` : | the key to associate the schema with.
`schema_key` : | the key where the schema will be stored.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_all_entries ()

    GSList *            mateconf_engine_all_entries            (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);

Lists the key-value pairs in `dir`. Does not list subdirectories; for that use `mateconf_engine_all_dirs()`. The returned list contains MateConfEntry objects. A MateConfEntry contains an absolute key and a value. The list is not recursive, it contains only the immediate children of `dir`. To free the returned list, `mateconf_entry_free()` each list element, then `g_slist_free()` the list itself.

`conf` : | a MateConfEngine.
`dir` : | Directory to list.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | List of MateConfEntry. [element-type MateConfEntry][transfer full MateConfEntry]

### mateconf_engine_all_dirs ()

    GSList *            mateconf_engine_all_dirs               (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);

Lists the subdirectories in `dir`. The returned list contains allocated strings. Each string is the absolute path of a subdirectory. You should `g_free()` each string in the list, then `g_slist_free()` the list itself.

`conf` : | a MateConfEngine.
`dir` : | Directory to get subdirectories from.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | List of allocated subdirectory names. [element-type utf8][transfer full utf8]

### mateconf_engine_suggest_sync ()

    void                mateconf_engine_suggest_sync           (MateConfEngine *conf,
                                                             GError **err);

Suggests to mateconfd that you've just finished a block of changes, and it would be an optimal time to sync to permanent storage. This is only a suggestion; and mateconfd will eventually sync even if you don't call `mateconf_engine_suggest_sync()`. This function is just a "hint" provided to mateconfd to maximize efficiency and minimize data loss.

`conf` : | the MateConfEngine to suggest syncing to.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_engine_dir_exists ()

    gboolean            mateconf_engine_dir_exists             (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);

Queries whether the directory `dir` exists in the MateConf database. Returns TRUE or FALSE.

`conf` : | a MateConfEngine.
`dir` : | Directory to check for.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE or FALSE.

### mateconf_engine_remove_dir ()

    void                mateconf_engine_remove_dir             (MateConfEngine *conf,
                                                             const gchar *dir,
                                                             GError **err);

This function first checks the validity of the mateconf key. In case of a local MateConfEngine it removes the directory from the source backend calling `mateconf_sources_remove_dir()`. Otherwise it obtains the configuration database using `mateconf_engine_get_database()` and removes the directory from the database calling `ConfigDatabase_remove_dir()`.

`conf` : | a MateConfEngine.
`dir` : | the name of the directory to be removed.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_engine_key_is_writable ()

    gboolean            mateconf_engine_key_is_writable        (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Checks whether the key is writable.

`conf` : | a MateConfEngine.
`key` : | the value to be changed.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE if the key is writable, FALSE if the key is read only.

### mateconf_valid_key ()

    gboolean            mateconf_valid_key                     (const gchar *key,
                                                             gchar **why_invalid);

Asks whether a key is syntactically correct, that is, it ensures that the key consists of slash-separated strings and contains only legal characters. Normally you shouldn't need to call this function; the MateConf functions all check this for you and return an error if the key is invalid. However, it may be useful to validate input to an entry field or the like. If you pass a non-NULL address as the `why_invalid` argument, an allocated string is returned explaining why the key is invalid, if it is. If the key is valid the `why_invalid` argument is unused.

`key` : | key to check.
`why_invalid` : | return location for an explanation of the problem, if any. `g_free()` the returned string.
Returns : | TRUE if the key is valid, or FALSE if not.

### mateconf_key_is_below ()

    gboolean            mateconf_key_is_below                  (const gchar *above,
                                                             const gchar *below);

Asks whether the key `below` would be found below the key `above`, were they both to exist in the database. For example, /foo is always found below / and above /foo/bar. This probably isn't useful but MateConf uses it internally so here it is if you need it.

`above` : | the key on the "left hand side" of the predicate.
`below` : | the key on the "right hand side."
Returns : | TRUE or FALSE.

### mateconf_concat_dir_and_key ()

    gchar *             mateconf_concat_dir_and_key            (const gchar *dir,
                                                             const gchar *key);

Concatenates the dir and key passed removing the unnecessary '/' characters and returns the new string.

`dir` : | the directory.
`key` : | the key.
Returns : | the newly concatenated string.

### mateconf_unique_key ()

    gchar *             mateconf_unique_key                    (void);

Generates a new and unique key using serial number, process id, current time and a random number generated.

Returns : | a newly created key, a gchar value.

### mateconf_escape_key ()

    char *              mateconf_escape_key                    (const char *arbitrary_text,
                                                             int len);

Escape `arbitrary_text` such that it's a valid key element (i.e. one part of the key path). The escaped key won't pass `mateconf_valid_key()` because it isn't a whole key (i.e. it doesn't have a preceding slash), but prepending a slash to the escaped text should always result in a valid key.

`arbitrary_text` : | some text in any encoding or format
`len` : | length of `arbitrary_text` in bytes, or -1 if `arbitrary_text` is nul-terminated
Returns : | a nul-terminated valid MateConf key

### mateconf_unescape_key ()

    char *              mateconf_unescape_key                  (const char *escaped_key,
                                                             int len);

Converts a string escaped with `mateconf_escape_key()` back into its original form.

`escaped_key` : | a key created with `mateconf_escape_key()`
`len` : | length of `escaped_key` in bytes, or -1 if `escaped_key` is nul-terminated
Returns : | the original string that was escaped to create `escaped_key`

### mateconf_engine_get_float ()

    gdouble             mateconf_engine_get_float              (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Requests the floating point number (`MATECONF_VALUE_FLOAT`) stored at `key`. Automatically performs type-checking, so if a non-float is stored at `key`, an error is returned. On error, or if `key` is unset, 0.0 is returned.

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | the value of `key`, or 0.0 if no value is obtained.

### mateconf_engine_get_int ()

    gint                mateconf_engine_get_int                (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Requests the integer (`MATECONF_VALUE_INT`) stored at `key`. Automatically performs type-checking, so if a non-integer is stored at `key`, an error is returned. On error, or if `key` is unset, 0 is returned.

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | the value of `key`, or 0 if no value is obtained.

### mateconf_engine_get_string ()

    gchar *             mateconf_engine_get_string             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Requests the string (`MATECONF_VALUE_STRING`) stored at `key`. Automatically performs type-checking, so if a non-string is stored at `key`, an error is returned. On error, or if `key` is unset, NULL is returned.

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | allocated string (value of `key`), or NULL if no value is obtained.

### mateconf_engine_get_bool ()

    gboolean            mateconf_engine_get_bool               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Requests the boolean value (`MATECONF_VALUE_BOOL`) stored at `key`. Automatically performs type-checking, so if a non-bool is stored at `key`, an error is returned. On error, or if `key` is unset, FALSE is returned.

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | the value of `key`, or FALSE if no value is obtained.

### mateconf_engine_get_schema ()

    MateConfSchema *       mateconf_engine_get_schema             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             GError **err);

Requests the schema (`MATECONF_VALUE_SCHEMA`) stored at `key`. Automatically performs type-checking, so if a non-schema is stored at `key`, an error is returned. If no value is set or an error occurs, NULL is returned.

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | the value of `key` as an allocated MateConfSchema, or NULL if no value was obtained.

### mateconf_engine_get_list ()

    GSList *            mateconf_engine_get_list               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GError **err);

Requests the list (`MATECONF_VALUE_LIST`) stored at `key`. Automatically performs type-checking, so if a non-list is stored at `key`, or the list does not contain elements of type `list_type`, an error is returned. If no value is set or an error occurs, NULL is returned. Note that NULL is also the empty list, so if you need to distinguish the empty list from an unset value, you must use `mateconf_engine_get()` to obtain a raw MateConfValue.

Remember that MateConf lists can only store primitive types: `MATECONF_VALUE_FLOAT`, `MATECONF_VALUE_INT`, `MATECONF_VALUE_BOOL`, `MATECONF_VALUE_STRING`, `MATECONF_VALUE_SCHEMA`. Also remember that lists must be uniform, you may not mix types in the same list.

The type of the list elements depends on `list_type`. A MateConfValue with type `MATECONF_VALUE_LIST` normally stores a list of more MateConfValue objects. `mateconf_engine_get_list()` automatically converts to primitive C types. Thus, the list->data fields in the returned list contain:

`MATECONF_VALUE_INT` | The integer itself, converted with `GINT_TO_POINTER()`
`MATECONF_VALUE_BOOL` | The bool itself, converted with `GINT_TO_POINTER()`
`MATECONF_VALUE_FLOAT` | A pointer to gdouble, which should be freed with `g_free()`
`MATECONF_VALUE_STRING` | A pointer to gchar, which should be freed with `g_free()`
`MATECONF_VALUE_SCHEMA` | A pointer to MateConfSchema, which should be freed with `mateconf_schema_free()`

In the `MATECONF_VALUE_FLOAT` and `MATECONF_VALUE_STRING` cases, you must `g_free()` each list element. In the `MATECONF_VALUE_SCHEMA` case you must `mateconf_schema_free()` each element. In all cases you must free the list itself with `g_slist_free()`.

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`list_type` : | type of each list element.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | an allocated list, with elements as described above.

### mateconf_engine_get_pair ()

    gboolean            mateconf_engine_get_pair               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gpointer car_retloc,
                                                             gpointer cdr_retloc,
                                                             GError **err);

Requests the pair (`MATECONF_VALUE_PAIR`) stored at `key`. Automatically performs type-checking, so if a non-pair is stored at `key`, or the pair does not have the right `car_type` and `cdr_type`, an error is returned. Remember that the car of a pair is its first value, and the cdr is its second value, in the Lisp tradition.

Remember that MateConf pairs can only store primitive types: `MATECONF_VALUE_FLOAT`, `MATECONF_VALUE_INT`, `MATECONF_VALUE_BOOL`, `MATECONF_VALUE_STRING`, `MATECONF_VALUE_SCHEMA`.

`mateconf_engine_get_pair()` stores the two fields of the pair in the locations pointed to by `car_retloc` and `cdr_retloc`. The type of these pointers depends on the corresponding `car_type` and `cdr_type`:

`MATECONF_VALUE_INT` | pointer to gint
`MATECONF_VALUE_BOOL` | pointer to gboolean
`MATECONF_VALUE_FLOAT` | pointer to gdouble
`MATECONF_VALUE_STRING` | pointer to gchar*
`MATECONF_VALUE_SCHEMA` | pointer to MateConfSchema*

In the `MATECONF_VALUE_STRING` case, you must `g_free()` the string(s) stored in the return location(s). In the `MATECONF_VALUE_SCHEMA` case you must `mateconf_schema_free()` the returned schema. If there's an error or the value is unset, `car_retloc` and `cdr_retloc` are left unchanged.

`mateconf_engine_get_pair()` returns TRUE on success.

An example of `mateconf_engine_get_pair()` in action:

    gdouble car = 10.0;
    gchar* cdr  = NULL;
    GError* error = NULL;
    if (!mateconf_engine_get_pair(conf, "/foo",
                        MATECONF_VALUE_FLOAT,
                        MATECONF_VALUE_STRING,
                        &car, &cdr, &error))
      {
        /* Note: car/cdr should be untouched, because an error occurred */
        g_assert(error != NULL);
        fprintf(stderr, "Error: %s\n", error->message);
        g_error_free(error);
        error = NULL;
      }
    else
      {
        /* Note: car/cdr may be untouched even though there was no error,
           if no value was set for "/foo"
         */
        printf("Found pair (%g,%s)\n", car, cdr);
        if (cdr != NULL)
          g_free(cdr);
      }

`conf` : | a MateConfEngine.
`key` : | key you want the value of.
`car_type` : | desired type of the pair's first field (car).
`cdr_type` : | desired type of the pair's second field (cdr).
`car_retloc` : | address of a return location for the car.
`cdr_retloc` : | address of a return location for the cdr.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_float ()

    gboolean            mateconf_engine_set_float              (MateConfEngine *conf,
                                                             const gchar *key,
                                                             gdouble val,
                                                             GError **err);

Change the value of `key` to `val`. Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a float (MATECONF_VALUE_FLOAT), `mateconf_engine_set_float()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`val` : | new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_int ()

    gboolean            mateconf_engine_set_int                (MateConfEngine *conf,
                                                             const gchar *key,
                                                             gint val,
                                                             GError **err);

Change the value of `key` to `val`. Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store an integer (MATECONF_VALUE_INT), `mateconf_engine_set_int()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`val` : | new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_string ()

    gboolean            mateconf_engine_set_string             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *val,
                                                             GError **err);

Change the value of `key` to `val`. Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a string (MATECONF_VALUE_STRING), `mateconf_engine_set_string()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`val` : | new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_bool ()

    gboolean            mateconf_engine_set_bool               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             gboolean val,
                                                             GError **err);

Change the value of `key` to `val`. Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but but doesn't store a boolean (MATECONF_VALUE_BOOL), `mateconf_engine_set_bool()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`val` : | new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_schema ()

    gboolean            mateconf_engine_set_schema             (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const MateConfSchema *val,
                                                             GError **err);

Change the value of `key` to `val`. Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a schema value (MATECONF_VALUE_SCHEMA), `mateconf_engine_set_schema()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`val` : | new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_list ()

    gboolean            mateconf_engine_set_list               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GSList *list,
                                                             GError **err);

Change the value of `key` to `list` of type `list_type`. Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a list value (MATECONF_VALUE_LIST), `mateconf_engine_set_list()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`list_type` : | type of each list element.
`list` : | new value of `key`.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### mateconf_engine_set_pair ()

    gboolean            mateconf_engine_set_pair               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gconstpointer address_of_car,
                                                             gconstpointer address_of_cdr,
                                                             GError **err);

Change the value of `key` to a pair of first type `car_type` and second type `cdr_type` . Automatically creates the `key` if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a schema value (MATECONF_VALUE_SCHEMA), `mateconf_engine_set_schema()` will fail.

`conf` : | a MateConfEngine.
`key` : | key you want to set the value of.
`car_type` : | type of the pair's first field (car).
`cdr_type` : | type of the pair's second field (cdr).
`address_of_car` : | address of the car.
`address_of_cdr` : | address of the cdr.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

### MateConfEnumStringPair

    typedef struct {
      gint enum_value;
      const gchar* str;
    } MateConfEnumStringPair;

### mateconf_string_to_enum ()

    gboolean            mateconf_string_to_enum                (MateConfEnumStringPair lookup_table[],
                                                             const gchar *str,
                                                             gint *enum_value_retloc);

It's best to store enumeration values as strings rather than integers. This is robust against changes in the enumeration, and also human-readable. This function makes it more convenient to store enums as strings.

The first argument is a lookup table, typically declared statically as follows:

    static MateConfEnumStringPair foo_enum_lookup_table[] = {
      { FOO_BLAH, "Blah" },
      { FOO_BAR,  "Bar"  },
      { 0, NULL }
    };

Note that the last element of the table is `{ 0, NULL }`. Typically the strings you use should be semi-human-readable, for GTK+ and MATE stripping off the library prefix and converting to StudlyCaps is the recommended convention.

The function returns TRUE if a match for the string is found, and if a match is found the enum value is placed in `enum_value_retloc`.

`lookup_table` : | a lookup table mapping enum values to strings.
`str` : | the string to convert to an enum value.
`enum_value_retloc` : | the address of an enum variable.
Returns : | TRUE if a match was found.

### mateconf_enum_to_string ()

    const gchar *       mateconf_enum_to_string                (MateConfEnumStringPair lookup_table[],
                                                             gint enum_value);

See `mateconf_string_to_enum()` for background information on this function.

`lookup_table` : | a lookup table mapping enum values to strings.
`enum_value` : | the enumeration value to convert to a string.
Returns : | a pointer to the proper string in the lookup table, or NULL if no match was found.

### mateconf_clear_cache ()

    void                mateconf_clear_cache                   (MateConfEngine *conf,
                                                             GError **err);

In case of a local MateConfEngine, this function calls `mateconf_sources_clear_cache()` to clear the cache from the source. Otherwise it obtains the configuration database using `mateconf_engine_get_database()` and clears the configuration database cache using `ConfigDatabase_clear_cache()`.

`conf` : | a MateConfEngine.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_synchronous_sync ()

    void                mateconf_synchronous_sync              (MateConfEngine *conf,
                                                             GError **err);

In case of a local MateConfEngine, this function syncs up all the mateconf sources calling `mateconf_synchronous_sync()`. Otherwise it obtains the configuration database using `mateconf_engine_get_database()` and syncs up the database calling `ConfigDatabase_synchronous_sync()`.

`conf` : | a MateConfEngine.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_engine_get_full ()

    MateConfValue *        mateconf_engine_get_full               (MateConfEngine *conf,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             gboolean use_schema_default,
                                                             gboolean *is_default_p,
                                                             gboolean *is_writable_p,
                                                             GError **err);

Returns the MateConfValue of a key and the associated MateConfEntry fields depending on the parameters passed.

`conf` : | a MateConfEngine.
`key` : | the key whose value is to be obtained.
`locale` : | the preferred locale (as in the locale related environment variables) orNULL if no locale is to be passed.
`use_schema_default` : | a gboolean value, indicating whether schema information is to be used as the default value.
`is_default_p` : | a gpointer if the is_default field of the MateConfEntry is required, NULL otherwise.
`is_writable_p` : | a gpointer if the is_writable field of the MateConfEntry is required, NULL otherwise.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | the MateConfValue.