## MateConfClient

MateConfClient — GObject-based convenience wrapper

## Synopsis

    enum                MateConfClientPreloadType;
    enum                MateConfClientErrorHandlingMode;
    void                (*MateConfClientNotifyFunc)            (MateConfClient *client,
                                                             guint cnxn_id,
                                                             MateConfEntry *entry,
                                                             gpointer user_data);
    void                (*MateConfClientErrorHandlerFunc)      (MateConfClient *client,
                                                             GError *error);
    #define             MATECONF_CLIENT                        (obj)
    MateConfClient *       mateconf_client_get_default            (void);
    MateConfClient *       mateconf_client_get_for_engine         (MateConfEngine *engine);
    void                mateconf_client_add_dir                (MateConfClient *client,
                                                             const gchar *dir,
                                                             MateConfClientPreloadType preload,
                                                             GError **err);
    void                mateconf_client_remove_dir             (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);
    guint               mateconf_client_notify_add             (MateConfClient *client,
                                                             const gchar *namespace_section,
                                                             MateConfClientNotifyFunc func,
                                                             gpointer user_data,
                                                             GFreeFunc destroy_notify,
                                                             GError **err);
    void                mateconf_client_notify_remove          (MateConfClient *client,
                                                             guint cnxn);
    void                mateconf_client_notify                 (MateConfClient *client,
                                                             const char *key);
    void                mateconf_client_set_error_handling     (MateConfClient *client,
                                                             MateConfClientErrorHandlingMode mode);
    void                mateconf_client_set_global_default_error_handler
                                                            (MateConfClientErrorHandlerFunc func);
    void                mateconf_client_clear_cache            (MateConfClient *client);
    void                mateconf_client_preload                (MateConfClient *client,
                                                             const gchar *dirname,
                                                             MateConfClientPreloadType type,
                                                             GError **err);
    void                mateconf_client_set                    (MateConfClient *client,
                                                             const gchar *key,
                                                             const MateConfValue *val,
                                                             GError **err);
    MateConfValue *        mateconf_client_get                    (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    MateConfValue *        mateconf_client_get_without_default    (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    MateConfEntry *        mateconf_client_get_entry              (MateConfClient *client,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             gboolean use_schema_default,
                                                             GError **err);
    MateConfValue *        mateconf_client_get_default_from_schema
                                                            (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_client_unset                  (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_client_recursive_unset        (MateConfClient *client,
                                                             const char *key,
                                                             MateConfUnsetFlags flags,
                                                             GError **err);
    GSList *            mateconf_client_all_entries            (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);
    GSList *            mateconf_client_all_dirs               (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);
    void                mateconf_client_suggest_sync           (MateConfClient *client,
                                                             GError **err);
    gboolean            mateconf_client_dir_exists             (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);
    gboolean            mateconf_client_key_is_writable        (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    gdouble             mateconf_client_get_float              (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    gint                mateconf_client_get_int                (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    gchar *             mateconf_client_get_string             (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            mateconf_client_get_bool               (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    MateConfSchema *       mateconf_client_get_schema             (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);
    GSList *            mateconf_client_get_list               (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GError **err);
    gboolean            mateconf_client_get_pair               (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gpointer car_retloc,
                                                             gpointer cdr_retloc,
                                                             GError **err);
    gboolean            mateconf_client_set_float              (MateConfClient *client,
                                                             const gchar *key,
                                                             gdouble val,
                                                             GError **err);
    gboolean            mateconf_client_set_int                (MateConfClient *client,
                                                             const gchar *key,
                                                             gint val,
                                                             GError **err);
    gboolean            mateconf_client_set_string             (MateConfClient *client,
                                                             const gchar *key,
                                                             const gchar *val,
                                                             GError **err);
    gboolean            mateconf_client_set_bool               (MateConfClient *client,
                                                             const gchar *key,
                                                             gboolean val,
                                                             GError **err);
    gboolean            mateconf_client_set_schema             (MateConfClient *client,
                                                             const gchar *key,
                                                             const MateConfSchema *val,
                                                             GError **err);
    gboolean            mateconf_client_set_list               (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GSList *list,
                                                             GError **err);
    gboolean            mateconf_client_set_pair               (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gconstpointer address_of_car,
                                                             gconstpointer address_of_cdr,
                                                             GError **err);
    void                mateconf_client_error                  (MateConfClient *client,
                                                             GError *error);
    void                mateconf_client_unreturned_error       (MateConfClient *client,
                                                             GError *error);
    void                mateconf_client_value_changed          (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValue *value);
    gboolean            mateconf_client_commit_change_set      (MateConfClient *client,
                                                             MateConfChangeSet *cs,
                                                             gboolean remove_committed,
                                                             GError **err);
    MateConfChangeSet *    mateconf_client_reverse_change_set     (MateConfClient *client,
                                                             MateConfChangeSet *cs,
                                                             GError **err);
    MateConfChangeSet *    mateconf_client_change_set_from_currentv
                                                            (MateConfClient *client,
                                                             const gchar **keys,
                                                             GError **err);
    MateConfChangeSet *    mateconf_client_change_set_from_current
                                                            (MateConfClient *client,
                                                             GError **err,
                                                             const gchar *first_key,
                                                             ...);

## Description

MateConfClient adds the following features to plain MateConf:

- A client-side cache for a specified list of directories you're interested in. You can "preload" entire directories into the cache, speeding things up even more.

- Some automatic error handling, if you request it.

- Signals when a value changes or an error occurs.

### Warning

If you use MateConfClient, you should not use the underlying MateConfEngine directly, or you'll break things. This is why there's no `mateconf_client_get_engine()` function; in fact, if you create the MateConfClient with `mateconf_client_get_default()`, there is no (legitimate) way to obtain a pointer to the underlying MateConfEngine. If you create a MateConfClient from an existing engine, you'll have to be disciplined enough to avoid using that engine directly. [1]

A MateConfClient has a list of directories that it "watches." These directories are optionally pre-loaded into the cache, and monitored in order to emit the value_changed signal. The MateConfClient can also be used to access directories not in the list, but those directories won't be preloaded and the "value_changed" signal won't be emitted for them.

There are two error-related signals in MateConfClient. The first is plain "error"; it's emitted anytime an error occurs. The second is "unreturned_error"; this signal is emitted if you pass NULL as the GError** to any MateConfClient function. The idea is that you can have a global error handler attached to the "unreturned_error" signal; if you want to use this handler, you don't need to use the normal MateConf error handling mechanism. However, if you ever need to handle errors for a specific function call, you can override the global handler by passing a non-NULL GError** to the function. If you want an error handler that's always invoked, use the "error" signal.

The "value_changed" signal is emitted whenever the server notifies your client program that a value has changed in the MateConf database. There's one problem with this signal: the signal handler has to use `strcmp()` to determine whether the changed value is the one it was interested in. If you are interested in lots of values, then every time a value changes you'll be making lots of calls to `strcmp()` and getting O(n) performance. `mateconf_client_notify_add()` is a superior interface in most cases for this reason. Note that calling `mateconf_client_set()` and its relatives will cause "value_changed" to be emitted, but "value_changed" is also emitted if another process changes the value.

Most of the MateConfClient interface mirrors the functions you'd use to manipulate a MateConfEngine (`mateconf_engine_get()` and `mateconf_client_get()`, for example). These should all work just like the MateConfEngine versions, except that they use the cache from MateConfClient and emit the MateConfClient signals.

As always with MateConf, applications based on MateConfClient should use a model-controller-view architecture. Typically, this means that areas of your application affected by a setting will monitor the relevant key and update themselves when necessary. The preferences dialog will simply change keys, allowing MateConf to notify the rest of the application that changes have occurred. Here the application proper is the "view," MateConf is the "model", and the preferences dialog is the "controller." In no case should you do this:

     mateconf_client_set(client, key, value);
     application_update_to_reflect_setting();

This breaks if a setting is changed outside your application—or even from a different part of your application. The correct way (in pseudo-code) is:

     /* At application startup */
     mateconf_client_notify_add(client, key, application_update_to_reflect_setting, data);
     /* From preferences dialog */
     mateconf_client_set(client, key, value);

See the example programs that come with MateConf for more details.

## Details

### enum MateConfClientPreloadType

    typedef enum { /*< prefix=MATECONF_CLIENT >*/
      MATECONF_CLIENT_PRELOAD_NONE,     /* don't preload anything */
      MATECONF_CLIENT_PRELOAD_ONELEVEL, /* load entries directly under the directory. */
      MATECONF_CLIENT_PRELOAD_RECURSIVE /* recurse the directory tree; possibly quite expensive! */
    } MateConfClientPreloadType;

The MateConfClientPreloadType is used to tell MateConfClient how to preload one of its directories. As a rule of thumb, if you plan to get the value of almost all the keys in a directory, preloading that directory will probably enhance performance. If you plan to use only half the keys, preloading is likely a bad idea. `MATECONF_CLIENT_PRELOAD_NONE` specifies that no preload occurs, `MATECONF_CLIENT_PRELOAD_ONELEVEL` loads the immediate children of the directory, `MATECONF_CLIENT_PRELOAD_RECURSIVE` loads all children of the directory and its subdirectories, recursively.

`MATECONF_CLIENT_PRELOAD_NONE` | preload nothing.
`MATECONF_CLIENT_PRELOAD_ONELEVEL` | preload immediate children of the directory.
`MATECONF_CLIENT_PRELOAD_RECURSIVE` | recursively preload everything in and below the directory.

### enum MateConfClientErrorHandlingMode

    typedef enum { /*< prefix=MATECONF_CLIENT >*/
      MATECONF_CLIENT_HANDLE_NONE,
      MATECONF_CLIENT_HANDLE_UNRETURNED,
      MATECONF_CLIENT_HANDLE_ALL
    } MateConfClientErrorHandlingMode;

MateConfClientErrorHandlingMode is used to control MateConfClient's default error handling. MateConfClient can pop up a dialog in the default signal handler for "error" or "unreturned_error." You can specify that no errors are handled, only unreturned errors are handled, or all errors are handled with this enumeration. You can prevent specific errors from being handled automatically by stopping the signal emission before the default signal handler is called (see the GLib documentation, `g_signal_stop_emission_by_name()` for example).

`MATECONF_CLIENT_HANDLE_NONE` | never run a default error handler.
`MATECONF_CLIENT_HANDLE_UNRETURNED` | run a default error handler for unreturned errors ("unreturned_error" signal).
`MATECONF_CLIENT_HANDLE_ALL` | run a default error handler for all errors ("error" signal).

### MateConfClientNotifyFunc ()

    void                (*MateConfClientNotifyFunc)            (MateConfClient *client,
                                                             guint cnxn_id,
                                                             MateConfEntry *entry,
                                                             gpointer user_data);

This is the signature of a user function added with `mateconf_client_notify_add()`. The notify function is invoked when the value of a key changes. The `entry` argument holds the new value, or NULL if the key was unset. The value in the `entry` argument should not be modified, and should be copied if you want to keep it around (the MateConfClient will destroy it sometime after your notify function is called).

`client` : | the MateConfClient notifying us.
`cnxn_id` : | connection ID from `mateconf_client_notify_add()`.
`entry` : | a MateConfEntry.
`user_data` : | user data from `mateconf_client_notify_add()`.

### MateConfClientErrorHandlerFunc ()

    void                (*MateConfClientErrorHandlerFunc)      (MateConfClient *client,
                                                             GError *error);

This is the signature of a user function which needs to be called for error handling.

`client` : | a MateConfClient.
`error` : | the return location for an allocated GError, or NULL to ignore errors.

### MATECONF_CLIENT()

    #define MATECONF_CLIENT(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MATECONF_TYPE_CLIENT, MateConfClient))

Casts a pointer to a MateConfClient*.

`obj` : | a MateConfClient.

### mateconf_client_get_default ()

    MateConfClient *       mateconf_client_get_default            (void);

Creates a new MateConfClient using the default MateConfEngine. Normally this is the engine you want. If someone else is already using the default MateConfClient, this function returns the same one they're using, but with the reference count incremented. So you have to unref either way.

It's important to call `g_type_init()` before using this GObject, to initialize the type system.

Returns : | a new MateConfClient. `g_object_unref()` when you're done. [transfer full]

### mateconf_client_get_for_engine ()

    MateConfClient *       mateconf_client_get_for_engine         (MateConfEngine *engine);

Creates a new MateConfClient with a specific MateConfEngine. Only specialized configuration-related programs should need to call this function. The returned MateConfClient should be unref'd when you're done with `g_object_unref()`. Remember to avoid using the MateConfEngine directly once you have a MateConfClient wrapper.

`engine` : | the MateConfEngine to use.
Returns : | a new MateConfClient. [transfer full]

### mateconf_client_add_dir ()

    void                mateconf_client_add_dir                (MateConfClient *client,
                                                             const gchar *dir,
                                                             MateConfClientPreloadType preload,
                                                             GError **err);

Add a directory to the list of directories the MateConfClient will watch. Any changes to keys below this directory will cause the "value_changed" signal to be emitted. When you add the directory, you can request that the MateConfClient preload its contents; see MateConfClientPreloadType for details.

Added directories may not overlap. That is, if you add "/foo", you may not add "/foo/bar". However you can add "/foo" and "/bar". You can also add "/foo" multiple times; if you add a directory multiple times, it will not be removed until you call `mateconf_client_remove_dir()` an equal number of times. The directory name must not have a trailing slash.

`client` : | a MateConfClient.
`dir` : | directory to add to the list.
`preload` : | degree of preload.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_client_remove_dir ()

    void                mateconf_client_remove_dir             (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);

Remove a directory from the list created with `mateconf_client_add_dir()`. If any notifications have been added below this directory with `mateconf_client_notify_add()`, those notifications will be disabled until you re-add the removed directory. Note that if a directory has been added multiple times, you must remove it the same number of times before the remove takes effect.

`client` : | a MateConfClient.
`dir` : | directory to remove.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_client_notify_add ()

    guint               mateconf_client_notify_add             (MateConfClient *client,
                                                             const gchar *namespace_section,
                                                             MateConfClientNotifyFunc func,
                                                             gpointer user_data,
                                                             GFreeFunc destroy_notify,
                                                             GError **err);

Request notification of changes to `namespace_section`. This includes the key `namespace_section` itself, and any keys below it (the behavior is identical to `mateconf_engine_notify_add()`, but while `mateconf_engine_notify_add()` places a notification request on the server for every notify function, MateConfClient requests server notification for directories added with `mateconf_client_add_dir()` and keeps the list of MateConfClientNotifyFunc on the client side).

For the notification to happen, `namespace_section` must be equal to or below one of the directories added with `mateconf_client_add_dir()`. You can still call `mateconf_client_notify_add()` for other directories, but no notification will be received until you add a directory above or equal to `namespace_section`. One implication of this is that `mateconf_client_remove_dir()` temporarily disables notifications that were below the removed directory.

The function returns a connection ID you can use to call `mateconf_client_notify_remove()`.

See the description of MateConfClientNotifyFunc for details on how the notification function is called.

`client` : | `namespace_section`
`namespace_section` : | where to listen for changes.
`func` : | . [scope notified][closure user_data][destroy destroy_notify]
Returns : | a connection ID for removing the notification.

### mateconf_client_notify_remove ()

    void                mateconf_client_notify_remove          (MateConfClient *client,
                                                             guint cnxn);

Remove a notification using the ID returned from `mateconf_client_notify_add()`. Invokes the destroy notify function on the notification's user data, if appropriate.

`client` : | a MateConfClient.
`cnxn` : | connection ID.

### mateconf_client_notify ()

    void                mateconf_client_notify                 (MateConfClient *client,
                                                             const char *key);

Emits the "value-changed" signal and notifies listeners as if `key` had been changed

`client` : | a MateConfClient.
`key` : | the key that has changed.

Since 2.4.

### mateconf_client_set_error_handling ()

    void                mateconf_client_set_error_handling     (MateConfClient *client,
                                                             MateConfClientErrorHandlingMode mode);

Controls the default error handling for MateConfClient. See MateConfClientErrorHandlingMode and MateConfClientParentWindowFunc for details on this.

`client` : | a MateConfClient.
`mode` : | error handling mode.

### mateconf_client_set_global_default_error_handler ()

    void                mateconf_client_set_global_default_error_handler
                                                            (MateConfClientErrorHandlerFunc func);

Set `func` as the default error handler for the MateConfClient. This handler would be called for all MateConfClient internal errors.

`func` : | pointer to the function to be called for error handling.

### mateconf_client_clear_cache ()

    void                mateconf_client_clear_cache            (MateConfClient *client);

Dumps everything out of the MateConfClient client-side cache. If you know you're done using the MateConfClient for a while, you can call this function to save some memory.

`client` : | a MateConfClient.

### mateconf_client_preload ()

    void                mateconf_client_preload                (MateConfClient *client,
                                                             const gchar *dirname,
                                                             MateConfClientPreloadType type,
                                                             GError **err);

Preloads a directory. Normally you do this when you call `mateconf_client_add_dir()`, but if you've called `mateconf_client_clear_cache()` there may be a reason to do it again.

`client` : | a MateConfClient.
`dirname` : | directory to preload.
`type` : | degree of preload.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_client_set ()

    void                mateconf_client_set                    (MateConfClient *client,
                                                             const gchar *key,
                                                             const MateConfValue *val,
                                                             GError **err);

Sets the value of a configuration key. Just like `mateconf_engine_set()`, but uses MateConfClient caching and error-handling features. The `val` argument will not be modified.

`client` : | a MateConfClient.
`key` : | key to set.
`val` : | new value.
`err` : | the return location for an allocated GError, or NULL to ignore errors.

### mateconf_client_get ()

    MateConfValue *        mateconf_client_get                    (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);

Gets the value of a configuration key. Just like `mateconf_engine_get()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`key` : | 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_client_get_without_default ()

    MateConfValue *        mateconf_client_get_without_default    (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);

Gets the value of a configuration key. Just like `mateconf_client_get()` but doesn't look for a default value if the key is unset.

`client` : | a MateConfClient.
`key` : | key to get.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | newly-allocated MateConfValue, or NULL if unset (even if a default exists).

### mateconf_client_get_entry ()

    MateConfEntry *        mateconf_client_get_entry              (MateConfClient *client,
                                                             const gchar *key,
                                                             const gchar *locale,
                                                             gboolean use_schema_default,
                                                             GError **err);

Obtains the full MateConfEntry for a value. Just like `mateconf_engine_get_entry()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`key` : | key to get.
`locale` : | preferred locale (as in the locale-related environment variables).
`use_schema_default` : | indicates whether to look for a default value when the key is unset.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | a MateConfEntry.

### mateconf_client_get_default_from_schema ()

    MateConfValue *        mateconf_client_get_default_from_schema
                                                            (MateConfClient *client,
                                                             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_client_get()`, `mateconf_engine_client_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. Just like `mateconf_engine_get_default_from_schema()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`key` : | key to get.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | newly-allocated MateConfValue, or NULL if the key has no default value in its schema.

### mateconf_client_unset ()

    gboolean            mateconf_client_unset                  (MateConfClient *client,
                                                             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. Just like `mateconf_engine_unset()`, but uses MateConfClient caching and error-handling features.

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

### mateconf_client_recursive_unset ()

    gboolean            mateconf_client_recursive_unset        (MateConfClient *client,
                                                             const char *key,
                                                             MateConfUnsetFlags flags,
                                                             GError **err);

Unsets all keys below `key`, including `key` itself. If any unset fails, continues on to unset as much as it can. The first failure is returned in `err`. Just like `mateconf_engine_recursive_unset()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`key` : | a key or directory name to be unset.
`flags` : | change how the unset is done.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE on error.

Since 2.4.

### mateconf_client_all_entries ()

    GSList *            mateconf_client_all_entries            (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);

Lists the key-value pairs in `dir`. Does not list subdirectories; for that use `mateconf_client_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. Just like `mateconf_engine_all_entries()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_all_dirs ()

    GSList *            mateconf_client_all_dirs               (MateConfClient *client,
                                                             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. Just like `mateconf_engine_all_dirs()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_suggest_sync ()

    void                mateconf_client_suggest_sync           (MateConfClient *client,
                                                             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. Just like `mateconf_engine_suggest_sync()`.

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

### mateconf_client_dir_exists ()

    gboolean            mateconf_client_dir_exists             (MateConfClient *client,
                                                             const gchar *dir,
                                                             GError **err);

Queries whether the directory `dir` exists in the MateConf database. Returns TRUE or FALSE. Just like `mateconf_engine_dir_exists()`, but uses MateConfClient caching and error-handling features.

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

### mateconf_client_key_is_writable ()

    gboolean            mateconf_client_key_is_writable        (MateConfClient *client,
                                                             const gchar *key,
                                                             GError **err);

Checks whether the key is writable.

`client` : | a MateConfClient.
`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_client_get_float ()

    gdouble             mateconf_client_get_float              (MateConfClient *client,
                                                             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. Just like `mateconf_engine_get_float()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_get_int ()

    gint                mateconf_client_get_int                (MateConfClient *client,
                                                             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. Just like `mateconf_engine_get_int()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_get_string ()

    gchar *             mateconf_client_get_string             (MateConfClient *client,
                                                             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. Just like `mateconf_engine_get_string()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_get_bool ()

    gboolean            mateconf_client_get_bool               (MateConfClient *client,
                                                             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. Just like `mateconf_engine_get_bool()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_get_schema ()

    MateConfSchema *       mateconf_client_get_schema             (MateConfClient *client,
                                                             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. Just like `mateconf_engine_get_schema()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_get_list ()

    GSList *            mateconf_client_get_list               (MateConfClient *client,
                                                             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_client_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_client_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()`.

Just like `mateconf_engine_get_list()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_get_pair ()

    gboolean            mateconf_client_get_pair               (MateConfClient *client,
                                                             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_client_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_client_get_pair()` returns TRUE on success.

An example of `mateconf_client_get_pair()` in action:

    gdouble car = 10.0;
    gchar* cdr  = NULL;
    GError* error = NULL;
    if (!mateconf_client_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);
      }

`client` : | a MateConfClient.
`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_client_set_float ()

    gboolean            mateconf_client_set_float              (MateConfClient *client,
                                                             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_client_set_float()` will fail. Just like `mateconf_engine_set()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_set_int ()

    gboolean            mateconf_client_set_int                (MateConfClient *client,
                                                             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_client_set_int()` will fail. Just like `mateconf_engine_set()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_set_string ()

    gboolean            mateconf_client_set_string             (MateConfClient *client,
                                                             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_client_set_string()` will fail. Just like `mateconf_engine_set()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_set_bool ()

    gboolean            mateconf_client_set_bool               (MateConfClient *client,
                                                             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_client_set_bool()` will fail. Just like `mateconf_engine_set()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_set_schema ()

    gboolean            mateconf_client_set_schema             (MateConfClient *client,
                                                             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_client_set_schema()` will fail. Just like `mateconf_engine_set()`, but uses MateConfClient caching and error-handling features.

`client` : | a MateConfClient.
`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_client_set_list ()

    gboolean            mateconf_client_set_list               (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValueType list_type,
                                                             GSList *list,
                                                             GError **err);

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

`client` : | a MateConfClient.
`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_client_set_pair ()

    gboolean            mateconf_client_set_pair               (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValueType car_type,
                                                             MateConfValueType cdr_type,
                                                             gconstpointer address_of_car,
                                                             gconstpointer address_of_cdr,
                                                             GError **err);

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

`client` : | a MateConfClient.
`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.

### mateconf_client_error ()

    void                mateconf_client_error                  (MateConfClient *client,
                                                             GError *error);

Emits the "error" signal. Rarely useful.

`client` : | a MateConfClient.
`error` : | error to pass to signal handlers.

### mateconf_client_unreturned_error ()

    void                mateconf_client_unreturned_error       (MateConfClient *client,
                                                             GError *error);

Emits the "unreturned_error" signal. Rarely useful.

`client` : | a MateConfClient.
`error` : | error to pass to signal handlers.

### mateconf_client_value_changed ()

    void                mateconf_client_value_changed          (MateConfClient *client,
                                                             const gchar *key,
                                                             MateConfValue *value);

Emits the "value_changed" signal. Rarely useful.

`client` : | a MateConfClient.
`key` : | key to pass to signal handlers.
`value` : | value of `key` to pass to signal handlers.

### mateconf_client_commit_change_set ()

    gboolean            mateconf_client_commit_change_set      (MateConfClient *client,
                                                             MateConfChangeSet *cs,
                                                             gboolean remove_committed,
                                                             GError **err);

Applies the changes in the change set to the MateConfClient passed as the first argument. If `remove_committed` is TRUE, then any successfully-committed changes are removed from the change set. If `remove_committed` is FALSE, the MateConfChangeSet is left unmodified.

If any set or unset operation results in an error, then processing terminates and the error is returned in `err` (unless `err` was NULL). If `remove_committed` was TRUE, then all the changes committed before the error occurred will have been removed from the set. If any error occurs, FALSE is returned.

`client` : | a MateConfClient.
`cs` : | a MateConfChangeSet.
`remove_committed` : | whether to remove successfully-committed changes from the set.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | TRUE on success, FALSE if an error occurs.

### mateconf_client_reverse_change_set ()

    MateConfChangeSet *    mateconf_client_reverse_change_set     (MateConfClient *client,
                                                             MateConfChangeSet *cs,
                                                             GError **err);

Creates a change set that would reverse `cs`. That is, for each change in `cs`, save the current state of that key in the returned change set.

`client` : | a MateConfClient.
`cs` : | change set to create the reverse of.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | a new change set that would restore the current state of each key in `cs`.

### mateconf_client_change_set_from_currentv ()

    MateConfChangeSet *    mateconf_client_change_set_from_currentv
                                                            (MateConfClient *client,
                                                             const gchar **keys,
                                                             GError **err);

Creates a change set that will change the keys in NULL-terminated array `keys` to their current state. Use this to save the current state of a collection of keys; then you can later revert to the current state by committing the returned change set.

`client` : | a MateConfClient.
`keys` : | NULL-terminated array of key names.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | new change set that changes all the `keys` to their current state.

### mateconf_client_change_set_from_current ()

    MateConfChangeSet *    mateconf_client_change_set_from_current
                                                            (MateConfClient *client,
                                                             GError **err,
                                                             const gchar *first_key,
                                                             ...);

Convenient varargs version of `mateconf_client_change_set_from_currentv()`.

`client` : | a MateConfClient.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
`first_key` : | first key to save the current state of.
`...` : | NULL-terminated list of additional keys.
Returns : | new change set that changes all the keys to their current state.

[1] This is all a white lie; some direct MateConfEngine operations are safe. But it's complicated to know which, and if an operation isn't safe the resulting bugs will mangle the cache and cause weird bugs at an indeterminate time in the future; you don't want to risk this situation.