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.

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