DConfClient

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

Functions

Types and Values

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.

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

client

a DConfClient

 

dir

a dconf dir

 

length

the number of items that were returned Returns: (array length=length): the paths located directly below dir

 

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

client

a DConfClient

 

result

the GAsyncResult passed to the GAsyncReadyCallback

 

error

a pointer to a GError, or NULL

 

Types and Values

DConfClient

typedef struct _DConfClient DConfClient;

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