DConfClient

## DConfClient DConfClient — Direct read and write access to DConf, based on GDBus |

## Synopsis

                        DConfClient;
    void                (*DConfWatchFunc)                   (DConfClient *client,
                                                             const gchar *path,
                                                             const gchar * const *items,
                                                             gint n_items,
                                                             const gchar *tag,
                                                             gpointer user_data);
    DConfClient *       dconf_client_new                    (const gchar *profile,
                                                             DConfWatchFunc watch_func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    GVariant *          dconf_client_read                   (DConfClient *client,
                                                             const gchar *key);
    GVariant *          dconf_client_read_default           (DConfClient *client,
                                                             const gchar *key);
    GVariant *          dconf_client_read_no_default        (DConfClient *client,
                                                             const gchar *key);
    gchar **            dconf_client_list                   (DConfClient *client,
                                                             const gchar *dir,
                                                             gint *length);
    gboolean            dconf_client_is_writable            (DConfClient *client,
                                                             const gchar *key);
    gboolean            dconf_client_write                  (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                dconf_client_write_async            (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            dconf_client_write_finish           (DConfClient *client,
                                                             GAsyncResult *result,
                                                             gchar **tag,
                                                             GError **error);
    gboolean            dconf_client_set_locked             (DConfClient *client,
                                                             const gchar *path,
                                                             gboolean locked,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                dconf_client_set_locked_async       (DConfClient *client,
                                                             const gchar *path,
                                                             gboolean locked,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            dconf_client_set_locked_finish      (DConfClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            dconf_client_write_many             (DConfClient *client,
                                                             const gchar *dir,
                                                             const gchar * const *rels,
                                                             GVariant **values,
                                                             gint n_values,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            dconf_client_watch                  (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                dconf_client_watch_async            (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            dconf_client_watch_finish           (DConfClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            dconf_client_unwatch                (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                dconf_client_unwatch_async          (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            dconf_client_unwatch_finish         (DConfClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----DConfClient

## Description

This is a simple class that allows an application to directly read from and write to the dconf database. There is also a very simple mechanism for requesting and receiving notification of changes but not robust mechanism for dispatching change notifications to multiple listeners.

Most applications probably don't want to access dconf directly and would be better off using something like GSettings.

## Details

### DConfClient

    typedef struct _DConfClient DConfClient;

An opaque structure type. May only be used with the following functions.

### DConfWatchFunc ()

    void                (*DConfWatchFunc)                   (DConfClient *client,
                                                             const gchar *path,
                                                             const gchar * const *items,
                                                             gint n_items,
                                                             const gchar *tag,
                                                             gpointer user_data);

This is the type of the callback given to `dconf_client_new()`.

This function is called in response to changes occuring to the dconf database that `client` is associated with.

`path` can either be a key or a dir. If `path` is a key then `items` will be empty and the notification should be taken to mean that one key -- the key named by `path` -- may have changed.

If `path` is a dir and `items` is empty then it is an indication that any key under `path` may have changed.

Otherwise (if `items` is non-empty) then the set of affected keys is the same as if the watch function had been called multiple times for each item in the array appended to `path`. This includes the possibility of the resulting path being a dir.

`client` : | the DConfClient emitting the notification
`path` : | the path at which the change occured
`items` : | the items that were changed, given as relative paths
`n_items` : | the length of `items`
`tag` : | the tag associated with the change
`user_data` : | the user data given to `dconf_client_new()`

### dconf_client_new ()

    DConfClient *       dconf_client_new                    (const gchar *profile,
                                                             DConfWatchFunc watch_func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Creates a new DConfClient for the given context.

If `profile` is non-`NULL` then it specifies the name of the profile to use. If `profile` is `NULL` then the DCONF_PROFILE environment variable is consulted. If that is unset then the default profile of "user" is used. If a profile named "user" is not installed then the dconf client is setup to access ~/.config/dconf/user.

`profile` : | the dconf profile to use, or `NULL`
`watch_func` : | the function to call when changes occur
`user_data` : | the user_data to pass to `watch_func`
`notify` : | the function to free `user_data` when no longer needed Returns: a new DConfClient

### dconf_client_read ()

    GVariant *          dconf_client_read                   (DConfClient *client,
                                                             const gchar *key);

Reads the value named by `key` from dconf. If no such value exists, `NULL` is returned.

`client` : | a DConfClient
`key` : | a valid dconf key Returns: the value corresponding to `key`, or `NULL` if there is none

### dconf_client_read_default ()

    GVariant *          dconf_client_read_default           (DConfClient *client,
                                                             const gchar *key);

Reads the value named by `key` from any existing default/mandatory databases but ignoring any value set by the user. The result is as if the named key had just been reset.

`client` : | a DConfClient
`key` : | a valid dconf key Returns: the default value corresponding to `key`, or `NULL` if there is none

### dconf_client_read_no_default ()

    GVariant *          dconf_client_read_no_default        (DConfClient *client,
                                                             const gchar *key);

Reads the value named by `key` as set by the user, ignoring any default/mandatory databases. Normal applications will never want to do this, but it may be useful for administrative or configuration tweaking utilities to have access to this information.

Note that in the case of mandatory keys, the result of `dconf_client_read_no_default()` with a fallback to `dconf_client_read_default()` is not necessarily the same as the result of a `dconf_client_read()`. This is because the user may have set a value before the key became marked as mandatory, in which case this call will see the user's (otherwise inaccessible) key.

`client` : | a DConfClient
`key` : | a valid dconf key Returns: the user value corresponding to `key`, or `NULL` if there is none

### dconf_client_list ()

    gchar **            dconf_client_list                   (DConfClient *client,
                                                             const gchar *dir,
                                                             gint *length);

Lists the keys and dirs located directly below `dir`.

You should free the return result with `g_strfreev()` when it is no longer needed.

`client` : | a DConfClient
`dir` : | a dconf dir
`length` : | the paths located directly below `dir`. [array length=length]

### dconf_client_is_writable ()

    gboolean            dconf_client_is_writable            (DConfClient *client,
                                                             const gchar *key);

Checks if `key` is writable (ie: the key has no mandatory setting).

This call does not verify that writing to the key will actually be successful. It only checks for the existence of mandatory keys/locks that might affect writing to `key`. Other issues (such as a full disk or an inability to connect to the bus and start the service) may cause the write to fail.

`client` : | a DConfClient
`key` : | a dconf key Returns: `TRUE` is `key` is writable

### dconf_client_write ()

    gboolean            dconf_client_write                  (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);

Write a value to the given `key`, or reset `key` to its default value.

If `value` is `NULL` then `key` is reset to its default value (which may be completely unset), otherwise `value` becomes the new value.

If `tag` is non-`NULL` then it is set to the unique tag associated with this write. This is the same tag that appears in change notifications.

`client` : | a DConfClient
`key` : | a dconf key
`value` : | a GVariant, or `NULL`. [allow-none]
`tag` : | the tag from this write. [out][allow-none]
`cancellable` : | a GCancellable, or `NULL`
`error` : | a pointer to a GError, or `NULL` Returns: `TRUE` if the write is successful

### dconf_client_write_async ()

    void                dconf_client_write_async            (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Write a value to the given `key`, or reset `key` to its default value.

This is the asynchronous version of `dconf_client_write()`. You should call `dconf_client_write_finish()` from `callback` to collect the result.

`client` : | a DConfClient
`key` : | a dconf key
`value` : | a GVariant, or `NULL`. [allow-none]
`cancellable` : | a GCancellable, or `NULL`
`callback` : | the function to call when complete
`user_data` : | the user data for `callback`

### dconf_client_write_finish ()

    gboolean            dconf_client_write_finish           (DConfClient *client,
                                                             GAsyncResult *result,
                                                             gchar **tag,
                                                             GError **error);

Collects the result from a prior call to `dconf_client_write_async()`.

`client` : | a DConfClient
`result` : | the GAsyncResult passed to the GAsyncReadyCallback
`tag` : | the tag from this write. [out][allow-none]
`error` : | a pointer to a GError, or `NULL`

### dconf_client_set_locked ()

    gboolean            dconf_client_set_locked             (DConfClient *client,
                                                             const gchar *path,
                                                             gboolean locked,
                                                             GCancellable *cancellable,
                                                             GError **error);

Marks a dconf path as being locked.

Locks do not affect writes to this DConfClient. You can still write to a key that is marked as being locked without problems.

Locks are only effective when they are set on a database that is being used as the source of default/mandatory values. In that case, the lock will prevent writes from occuring to the database that has this database as its defaults.

`client` : | a DConfClient
`path` : | a dconf path
`locked` : | `TRUE` to lock, `FALSE` to unlock
`cancellable` : | a GCancellable, or `NULL`
`error` : | a pointer to a GError, or `NULL` Returns: `TRUE` if setting the lock was successful

### dconf_client_set_locked_async ()

    void                dconf_client_set_locked_async       (DConfClient *client,
                                                             const gchar *path,
                                                             gboolean locked,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Marks a dconf path as being locked.

This is the asynchronous version of `dconf_client_set_locked()`. You should call `dconf_client_set_locked_finish()` from `callback` to collect the result.

`client` : | a DConfClient
`path` : | a dconf path
`locked` : | `TRUE` to lock, `FALSE` to unlock
`cancellable` : | a GCancellable, or `NULL`
`callback` : | the function to call when complete
`user_data` : | the user data for `callback`

### dconf_client_set_locked_finish ()

    gboolean            dconf_client_set_locked_finish      (DConfClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Collects the result from a prior call to `dconf_client_set_locked_async()`.

`client` : | a DConfClient
`result` : | the GAsyncResult passed to the GAsyncReadyCallback
`error` : | a pointer to a GError, or `NULL`

### dconf_client_write_many ()

    gboolean            dconf_client_write_many             (DConfClient *client,
                                                             const gchar *dir,
                                                             const gchar * const *rels,
                                                             GVariant **values,
                                                             gint n_values,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);

Write multiple values at once.

For each pair of items from `rels` and `values`, the value is written to the result of concatenating `dir` with the relative path. As with `dconf_client_write()`, if a given value is `NULL` then the effect is that the specified key is reset.

If `tag` is non-`NULL` then it is set to the unique tag associated with this write. This is the same tag that appears in change notifications.

`client` : | a DConfClient
`dir` : | the dconf directory under which to make the writes
`rels` : | a `NULL`-terminated array of relative keys
`values` : | an array of possibly-`NULL` GVariant pointers
`n_values` : | the length of `values`, which must be equal to the length of `rels`
`tag` : | the tag from this write. [out][allow-none]
`cancellable` : | a GCancellable, or `NULL`
`error` : | a pointer to a GError, or `NULL` Returns: `TRUE` if the write is successful

### dconf_client_watch ()

    gboolean            dconf_client_watch                  (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);

Requests monitoring of a portion of the dconf database.

If `path` is a key (ie: doesn't end with a slash) then a single key is monitored for changes. If `path` is a dir (ie: sending with a slash) then all keys that have `path` as a prefix are monitored.

This function blocks until the watch has definitely been established with the bus daemon. If you would like a non-blocking version of this call, see `dconf_client_watch_async()`.

`client` : | a DConfClient
`path` : | a dconf path
`cancellable` : | a GCancellable, or `NULL`
`error` : | a pointer to a `NULL` GError, or `NULL` Returns: `TRUE` on success, else `FALSE` with `error` set

### dconf_client_watch_async ()

    void                dconf_client_watch_async            (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Requests monitoring of a portion of the dconf database.

This is the asynchronous version of `dconf_client_watch()`. You should call `dconf_client_watch_finish()` from `callback` to collect the result.

`client` : | a DConfClient
`path` : | a dconf path
`cancellable` : | a GCancellable, or `NULL`
`callback` : | a GAsyncReadyCallback to call when finished
`user_data` : | a pointer to pass as the last argument to `callback`

### dconf_client_watch_finish ()

    gboolean            dconf_client_watch_finish           (DConfClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Collects the result from a prior call to `dconf_client_watch_async()`.

`client` : | a DConfClient
`result` : | the GAsyncResult passed to the GAsyncReadyCallback
`error` : | a pointer to a GError, or `NULL`

### dconf_client_unwatch ()

    gboolean            dconf_client_unwatch                (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);

Cancels the effect of a previous call to `dconf_client_watch()`.

If the same path has been watched multiple times then only one of the watches is cancelled and the net effect is that the path is still watched.

This function blocks until the watch has definitely been removed from the bus daemon. It is possible that notifications in transit will arrive after this call returns. For an asynchronous version of this call, see `dconf_client_unwatch_async()`.

`client` : | a DConfClient
`path` : | a dconf path
`cancellable` : | a GCancellable, or `NULL`
`error` : | a pointer to a `NULL` GError, or `NULL` Returns: `TRUE` on success, else `FALSE` with `error` set

### dconf_client_unwatch_async ()

    void                dconf_client_unwatch_async          (DConfClient *client,
                                                             const gchar *path,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Cancels the effect of a previous call to `dconf_client_watch()`.

This is the asynchronous version of `dconf_client_unwatch()`. You should call `dconf_client_unwatch_finish()` from `callback` to collect the result. No additional notifications will be delivered for this watch after `callback` is called.

`client` : | a DConfClient
`path` : | a dconf path
`cancellable` : | a GCancellable, or `NULL`
`callback` : | a GAsyncReadyCallback to call when finished
`user_data` : | a pointer to pass as the last argument to `callback`

### dconf_client_unwatch_finish ()

    gboolean            dconf_client_unwatch_finish         (DConfClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Collects the result from a prior call to `dconf_client_unwatch_async()`.

`client` : | a DConfClient
`result` : | the GAsyncResult passed to the GAsyncReadyCallback
`error` : | a pointer to a GError, or `NULL`