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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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

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.

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.