DConfClient: dconf Reference Manual

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

## Functions

DConfClient * | dconf_client_new ()
GVariant * | dconf_client_read ()
GVariant * | dconf_client_read_full ()
gchar ** | dconf_client_list ()
gchar ** | dconf_client_list_locks ()
gboolean | dconf_client_is_writable ()
gboolean | dconf_client_write_fast ()
gboolean | dconf_client_write_sync ()
gboolean | dconf_client_change_fast ()
gboolean | dconf_client_change_sync ()
void | dconf_client_watch_fast ()
void | dconf_client_watch_sync ()
void | dconf_client_unwatch_fast ()
void | dconf_client_unwatch_sync ()
void | dconf_client_sync ()

## Signals

void | changed | Run Last
void | writability-changed | Run Last

## Types and Values

| DConfClient
enum | DConfReadFlags

## Object Hierarchy

        GObject
        ╰── DConfClient

## 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.

## Functions

### 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.

#### Parameters

client | a DConfClient |
key | the key to read the value of |

#### Returns

a GVariant, or `NULL`

### dconf_client_read_full ()

    GVariant *
    dconf_client_read_full (DConfClient *client,
                            const gchar *key,
                            DConfReadFlags flags,
                            const GQueue *read_through);

Reads the current value of `key` .

If `flags` contains `DCONF_READ_USER_VALUE` then only the user value will be read. Locks are ignored, which means that it is possible to use this API to read "invisible" user values which are hidden by system locks.

If `flags` contains `DCONF_READ_DEFAULT_VALUE` then only non-user values will be read. The result will be exactly equivalent to the value that would be read if the current value of the key were to be reset.

Flags may not contain both `DCONF_READ_USER_VALUE` and `DCONF_READ_DEFAULT_VALUE`.

If `read_through` is non-`NULL`, `DCONF_READ_DEFAULT_VALUE` is not given then `read_through` is checked for the key in question, subject to the restriction that the key in question is writable. This effectively answers the question of "what would happen if these changes were committed".

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

If `flags` is `DCONF_READ_FLAGS_NONE` and `read_through` is `NULL` then this call is exactly equivalent to `dconf_client_read()`.

#### Parameters

client | a DConfClient |
key | the key to read the default value of |
flags | DConfReadFlags |
read_through | a GQueue of DConfChangeset |

#### Returns

a GVariant, or `NULL`

Since: 0.26

### 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.

#### Parameters

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_list_locks ()

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

Lists all locks under `dir` in effect for `client` .

If no locks are in effect, an empty list is returned. If no keys are writable at all then a list containing `dir` is returned.

The returned list will be `NULL`-terminated.

#### Parameters

client | a DConfClient |
dir | the dir to limit results to |
length | the length of the returned list. |

#### Returns

an array of strings, never `NULL`.

Since: 0.26

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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).

#### Parameters

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.

#### Parameters

client | a DConfClient |

## Types and Values

### 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()`.

### enum DConfReadFlags

#### Members

DCONF_READ_FLAGS_NONE | no flags |
DCONF_READ_DEFAULT_VALUE | read the default value, ignoring any values in writable databases or any queued changes. This is effectively equivalent to asking what value would be read after a reset was written for the key in question. |
DCONF_READ_USER_VALUE | read the user value, ignoring any system databases, including ignoring locks. It is even possible to read "invisible" values in the user database in this way, which would have normally been ignored because of locks. |

Since: 0.26

## Signal Details

### The `“changed”` signal

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

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.

#### Parameters

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

Flags: Run Last

### The `“writability-changed”` signal

    void
    user_function (DConfClient *client,
                   gchar       *path,
                   gpointer     user_data)

Signal emitted when writability for a key (or all keys in a dir) changes. It will be immediately followed by “changed” signal for the path.

#### Parameters

client | the DConfClient reporting the change |
path | the dir or key that changed |
user_data | user data set when the signal handler was connected. |

Flags: Run Last