DConfClient

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

## Synopsis

                        DConfClient;
    DConfClient *       dconf_client_new                    (void);
    GVariant *          dconf_client_read                   (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_fast             (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             GError **error);
    gboolean            dconf_client_write_sync             (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            dconf_client_change_fast            (DConfClient *client,
                                                             DConfChangeset *changeset,
                                                             GError **error);
    gboolean            dconf_client_change_sync            (DConfClient *client,
                                                             DConfChangeset *changeset,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                dconf_client_watch_fast             (DConfClient *client,
                                                             const gchar *path);
    void                dconf_client_watch_sync             (DConfClient *client,
                                                             const gchar *path);
    void                dconf_client_unwatch_fast           (DConfClient *client,
                                                             const gchar *path);
    void                dconf_client_unwatch_sync           (DConfClient *client,
                                                             const gchar *path);
    void                dconf_client_sync                   (DConfClient *client);

## Object Hierarchy

      GObject
       +----DConfClient

## Signals

      "changed"                                        : Run Last

## Description

This is the primary client interface to dconf.

It allows applications to directly read from and write to the dconf database. Applications can subscribe to change notifications.

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

Please note that the API of libdconf is not stable in any way. It has changed in incompatible ways in the past and there will be further changes in the future.

## Details

### DConfClient

    typedef struct _DConfClient DConfClient;

The main object for interacting with dconf. This is a GObject, so you should manage it with `g_object_ref()` and `g_object_unref()`.

### dconf_client_new ()

    DConfClient *       dconf_client_new                    (void);

Creates a new DConfClient.

Returns : | a new DConfClient

### dconf_client_read ()

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

Reads the current value of `key`.

If `key` exists, its value is returned. Otherwise, `NULL` is returned.

If there are outstanding "fast" changes in progress they may affect the result of this call.

`client` : | a DConfClient
`key` : | the key to read the value of
Returns : | a GVariant, or `NULL`

### dconf_client_list ()

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

Gets the list of all dirs and keys immediately under `dir`.

If `length` is non-`NULL` then it will be set to the length of the returned array. In any case, the array is `NULL`-terminated.

IF there are outstanding "fast" changes in progress then this call may return inaccurate results with respect to those outstanding changes.

`client` : | a DConfClient
`dir` : | the dir to list the contents of
`length` : | the length of the returned list
Returns : | an array of strings, never `NULL`.

### dconf_client_is_writable ()

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

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

This call does not verify that writing to the key will actually be successful. It only checks that the database is writable and that there are no locks affecting `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` : | the key to check for writability
Returns : | `TRUE` is `key` is writable

### dconf_client_write_fast ()

    gboolean            dconf_client_write_fast             (DConfClient *client,
                                                             const gchar *key,
                                                             GVariant *value,
                                                             GError **error);

Writes `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.

This call merely queues up the write and returns immediately, without blocking. The only errors that can be detected or reported at this point are attempts to write to read-only keys. If the application exits immediately after this function returns then the queued call may never be sent; see `dconf_client_sync()`.

A local copy of the written value is kept so that calls to `dconf_client_read()` that occur before the service actually makes the change will return the new value.

If the write is queued then a change signal will be directly emitted. If this function is being called from the main context of `client` then the signal is emitted before this function returns; otherwise it is scheduled on the main context.

`client` : | a DConfClient
`key` : | the key to write to
`value` : | a GVariant, the value to write
`error` : | a pointer to a `NULL` GError, or `NULL`
Returns : | `TRUE` if the write was queued

### dconf_client_write_sync ()

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

Write `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.

This call blocks until the write is complete. This call will therefore detect and report all cases of failure. If the modified key is currently being watched then a signal will be emitted from the main context of `client` (once the signal arrives from the service).

If `tag` is non-`NULL` then it is set to the unique tag associated with this write. This is the same tag that will appear in the following change signal.

`client` : | a DConfClient
`key` : | the key to write to
`value` : | a GVariant, the value to write
`tag` : | the tag from this write. [out][allow-none]
`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_change_fast ()

    gboolean            dconf_client_change_fast            (DConfClient *client,
                                                             DConfChangeset *changeset,
                                                             GError **error);

Performs the change operation described by `changeset`.

Once `changeset` is passed to this call it can no longer be modified.

This call merely queues up the write and returns immediately, without blocking. The only errors that can be detected or reported at this point are attempts to write to read-only keys. If the application exits immediately after this function returns then the queued call may never be sent; see `dconf_client_sync()`.

A local copy of the written value is kept so that calls to `dconf_client_read()` that occur before the service actually makes the change will return the new value.

If the write is queued then a change signal will be directly emitted. If this function is being called from the main context of `client` then the signal is emitted before this function returns; otherwise it is scheduled on the main context.

`client` : | a DConfClient
`changeset` : | the changeset describing the requested change
`error` : | a pointer to a `NULL` GError, or `NULL`
Returns : | `TRUE` if the requested changed was queued

### dconf_client_change_sync ()

    gboolean            dconf_client_change_sync            (DConfClient *client,
                                                             DConfChangeset *changeset,
                                                             gchar **tag,
                                                             GCancellable *cancellable,
                                                             GError **error);

Performs the change operation described by `changeset`.

Once `changeset` is passed to this call it can no longer be modified.

This call blocks until the change is complete. This call will therefore detect and report all cases of failure. If any of the modified keys are currently being watched then a signal will be emitted from the main context of `client` (once the signal arrives from the service).

If `tag` is non-`NULL` then it is set to the unique tag associated with this change. This is the same tag that will appear in the following change signal. If `changeset` makes no changes then `tag` may be non-unique (eg: the empty string may be used for empty changesets).

`client` : | a DConfClient
`changeset` : | the changeset describing the requested change
`tag` : | the tag from this write. [out][allow-none]
`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_fast ()

    void                dconf_client_watch_fast             (DConfClient *client,
                                                             const gchar *path);

Requests change notifications for `path`.

If `path` is a key then the single key is monitored. If `path` is a dir then all keys under the dir are monitored.

This function queues the watch request with D-Bus and returns immediately. There is a very slim chance that the dconf database could change before the watch is actually established. If that is the case then a synthetic change signal will be emitted.

Errors are silently ignored.

`client` : | a DConfClient
`path` : | a path to watch

### dconf_client_watch_sync ()

    void                dconf_client_watch_sync             (DConfClient *client,
                                                             const gchar *path);

Requests change notifications for `path`.

If `path` is a key then the single key is monitored. If `path` is a dir then all keys under the dir are monitored.

This function submits each of the various watch requests that are required to monitor a key and waits until each of them returns. By the time this function returns, the watch has been established.

Errors are silently ignored.

`client` : | a DConfClient
`path` : | a path to watch

### dconf_client_unwatch_fast ()

    void                dconf_client_unwatch_fast           (DConfClient *client,
                                                             const gchar *path);

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

This call returns immediately.

It is still possible that change signals are received after this call had returned (watching guarantees notification of changes, but unwatching does not guarantee no notifications).

`client` : | a DConfClient
`path` : | a path previously watched

### dconf_client_unwatch_sync ()

    void                dconf_client_unwatch_sync           (DConfClient *client,
                                                             const gchar *path);

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

This function submits each of the various unwatch requests and waits until each of them returns. It is still possible that change signals are received after this call has returned (watching guarantees notification of changes, but unwatching does not guarantee no notifications).

`client` : | a DConfClient
`path` : | a path previously watched

### dconf_client_sync ()

    void                dconf_client_sync                   (DConfClient *client);

Blocks until all outstanding "fast" change or write operations have been submitted to the service.

Applications should generally call this before exiting on any DConfClient that they wrote to.

`client` : | a DConfClient

## Signal Details

### The `"changed"` signal

    void                user_function                      (DConfClient *client,
                                                            gchar       *prefix,
                                                            GStrv        changes,
                                                            gchar       *tag,
                                                            gpointer     user_data)      : Run Last

This signal is emitted when the DConfClient has a possible change to report. The signal is an indication that a change may have occurred; it's possible that the keys will still have the same value as before.

To ensure that you receive notification about changes to paths that you are interested in you must call `dconf_client_watch_fast()` or `dconf_client_watch_sync()`. You may still receive notifications for paths that you did not explicitly watch.

`prefix` will be an absolute dconf path; see `dconf_is_path()`. `changes` is a `NULL`-terminated array of dconf rel paths; see `dconf_is_rel_path()`.

`tag` is an opaque tag string, or `NULL`. The only thing you should do with `tag` is to compare it to tag values returned by `dconf_client_write_sync()` or `dconf_client_change_sync()`.

The number of changes being reported is equal to the length of `changes`. Appending each item in `changes` to `prefix` will give the absolute path of each changed item.

If a single key has changed then `prefix` will be equal to the key and `changes` will contain a single item: the empty string.

If a single dir has changed (indicating that any key under the dir may have changed) then `prefix` will be equal to the dir and `changes` will contain a single empty string.

If more than one change is being reported then `changes` will have more than one item.

`client` : | the DConfClient reporting the change
`prefix` : | the prefix under which the changes happened
`changes` : | the list of paths that were changed, relative to `prefix`
`tag` : | the tag for the change, if it originated from the service
`user_data` : | user data set when the signal handler was connected.