dconf

dconf

Synopsis

typedef             DConfAsyncResult;
void                (*DConfAsyncReadyCallback)          (DConfAsyncResult *result,
                                                         gpointer user_data);
void                (*DConfWatchFunc)                   (const gchar *prefix,
                                                         const gchar * const *items,
                                                         gint items_length,
                                                         const gchar *event_id,
                                                         gpointer user_data);

gboolean            dconf_is_key                        (const gchar *key);
gboolean            dconf_is_path                       (const gchar *path);
gboolean            dconf_is_key_or_path                (const gchar *key_or_path);
gboolean            dconf_is_relative_key               (const gchar *relative_key);

gboolean            dconf_match                         (const gchar *key_or_path1,
                                                         const gchar *key_or_path2);

GVariant *          dconf_get                           (const gchar *key);

gchar **            dconf_list                          (const gchar *path,
                                                         gint *length);

gboolean            dconf_get_writable                  (const gchar *key_or_path);
gboolean            dconf_get_locked                    (const gchar *key_or_path);

gboolean            dconf_set                           (const gchar *key,
                                                         GVariant *value,
                                                         gchar **event_id,
                                                         GError **error);
void                dconf_set_async                     (const gchar *key,
                                                         GVariant *value,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            dconf_set_finish                    (DConfAsyncResult *result,
                                                         gchar **event_id,
                                                         GError **error);

gboolean            dconf_set_locked                    (const gchar *key_or_path,
                                                         gboolean locked,
                                                         GError **error);
void                dconf_set_locked_async              (const gchar *key_or_path,
                                                         gboolean locked,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            dconf_set_locked_finish             (DConfAsyncResult *result,
                                                         GError **error);

gboolean            dconf_reset                         (const gchar *key,
                                                         gchar **event_id,
                                                         GError **error);
void                dconf_reset_async                   (const gchar *key,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            dconf_reset_finish                  (DConfAsyncResult *result,
                                                         gchar **event_id,
                                                         GError **error);

gboolean            dconf_merge                         (const gchar *prefix,
                                                         GTree *tree,
                                                         gchar **event_id,
                                                         GError **error);
void                dconf_merge_async                   (const gchar *prefix,
                                                         GTree *tree,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            dconf_merge_finish                  (DConfAsyncResult *result,
                                                         gchar **event_id,
                                                         GError **error);

void                dconf_watch                         (const gchar *match,
                                                         DConfWatchFunc func,
                                                         gpointer user_data);
void                dconf_unwatch                       (const gchar *match,
                                                         DConfWatchFunc func,
                                                         gpointer user_data);

Description

Details

DConfAsyncResult

typedef struct OPAQUE_TYPE__DConfAsyncResult                DConfAsyncResult;

DConfAsyncReadyCallback ()

void                (*DConfAsyncReadyCallback)          (DConfAsyncResult *result,
                                                         gpointer user_data);

DConfWatchFunc ()

void                (*DConfWatchFunc)                   (const gchar *prefix,
                                                         const gchar * const *items,
                                                         gint items_length,
                                                         const gchar *event_id,
                                                         gpointer user_data);

dconf_is_key ()

gboolean            dconf_is_key                        (const gchar *key);

Determines if key is a valid key.

A key is valid if it starts with a slash, does not end with a slash, and contains no two consecutive slashes. A key is different from a path in that it does not end with "/".

key :

a possible key

Returns :

TRUE if key is valid

dconf_is_path ()

gboolean            dconf_is_path                       (const gchar *path);

Determines if path is a valid key for use with the dconf_list() function.

A path is valid if it starts with a slash, ends with a slash and contains no two consecutive slashes. A path is different from a key in that it ends with "/".

"/" is a valid path.

path :

a possible path

Returns :

TRUE if path is valid

dconf_is_key_or_path ()

gboolean            dconf_is_key_or_path                (const gchar *key_or_path);

Determines if key_or_path is a valid key or path.

key_or_path :

a possible key or path

Returns :

TRUE if key_or_path is valid

dconf_is_relative_key ()

gboolean            dconf_is_relative_key               (const gchar *relative_key);

Determines if relative_key is a valid relative key.

A relative key is valid if it does not start with a slash, does not end with a slash, and contains no two consecutive slashes. The empty string is not a valid relative key.

Another definition is that a relative key is any string that may be appended to a valid path to form a valid key.

relative_key :

a possible relative key

Returns :

TRUE if relative_key is valid

dconf_match ()

gboolean            dconf_match                         (const gchar *key_or_path1,
                                                         const gchar *key_or_path2);

Checks if key_or_path1 matches key_or_path2.

Match is a symmetric predicate on a pair of strings defined as follows: two strings match if and only if they are exactly equal or one of them ends with a slash and is a prefix of the other.

The match predicate is of significance in two parts of the dconf API.

First, when registering watches for change notifications, any key that matches the requested watch will be reported. This means that if your watch string ends with a slash then changes to any key that has the watch string as the initial part of its path will be reported.

Second, any lock set on the database will restrict write access to any key that matches the lock. This means that if your lock string ends with a slash then no key that has the lock string as it prefix may be written to.

key_or_path1 :

a dconf key or path

key_or_path2 :

a dconf key or path

Returns :

TRUE iff key_or_path1 matches key_or_path2

dconf_get ()

GVariant *          dconf_get                           (const gchar *key);

Lookup a key in dconf.

If the key exists, it is returned. If the key does not exist then NULL is returned.

dconf doesn't really have errors when reading keys. If, for example, the configuration database file does not exist then it is equivalent to being empty (ie: NULL will always be returned).

It is a programmer error to call this function with a key that is not a valid dconf key (as per dconf_is_key()).

key :

a dconf key

returns :

a GVariant, or NULL

dconf_list ()

gchar **            dconf_list                          (const gchar *path,
                                                         gint *length);

Get a list of sub-items directly below a given path in dconf.

Directory existence in dconf is not strong -- that is, directories exist only to hold keys. There is no distinction between an "empty directory" and a directory that does not exist. For this reason, this function will always return a list -- it may simply be empty.

Additionally, dconf doesn't really have errors when reading keys. If, for example, the configuration database file does not exist then it is equivalent to being empty (ie: the empty list will always be returned).

If length is non-NULL then it will be set to the length of the return array, excluding the NULL.

It is appropriate to free the return value using g_strfreev().

It is a programmer error to call this function with a path that is not a valid dconf path (as per dconf_is_path()).

path :

a dconf path

length :

a pointer to the length of the return value

returns :

a NULL-terminated list of strings

dconf_get_writable ()

gboolean            dconf_get_writable                  (const gchar *key_or_path);

Checks if writing to a given key_or_path would work. For a key to be writable, it may not be locked in any database nor may any of its parents.

This is the value you would use to determine if a settings widget should be displayed in a UI as sensitive.

If the path doesn't exist in the tree then FALSE is returned.

It is a programmer error to call this function with a key_or_path that is not a valid dconf path (as per dconf_is_path()) or key (as per dconf_is_key()).

key_or_path :

a dconf key or path

returns :

TRUE if writing to key_or_path would work

dconf_get_locked ()

gboolean            dconf_get_locked                    (const gchar *key_or_path);

Checks if a lock exists at the current position in the tree. This call is the exact dual of dconf_set_locked(); the return value here is exactly equal to what was last set with dconf_set_locked() on the exact same key_or_path.

This is the value you would show in a lockdown editor for it a lock exists at the current point.

If the path doesn't exist in the tree then FALSE is returned.

This result of this function is not impacted by locks installed in 'default' databases -- only those in the toplevel database that the user would modify by calling dconf_set_locked(). It is also not impacted by entire-directory locks installed at higher points in the tree. See dconf_get_writable() if you are interested in that.

It is a programmer error to call this function with a key_or_path that is not a valid dconf path (as per dconf_is_path()) or key (as per dconf_is_key()).

key_or_path :

a dconf key or path

returns :

TRUE if key_or_path is locked

dconf_set ()

gboolean            dconf_set                           (const gchar *key,
                                                         GVariant *value,
                                                         gchar **event_id,
                                                         GError **error);

Sets the value of a key in the dconf database.

If value has a floating reference, it will be consumed by this call.

value may not be NULL. If you wish to reset the value of a key, then use dconf_reset().

In the event of a failure of any kind then no changes will be made to the database, error (if non-NULL) will be set and FALSE will be returned.

If the set is successful then TRUE will be returned. If event_id is non-NULL it will be set to the event ID number of the merge. The event ID will be the same as the ID that is sent for the change notification corresponding to this modification and is unique for the life of the program. It has no particular format.

It is a programmer error to call this function with a key that is not a valid dconf key (as per dconf_is_key()).

key :

a dconf key

value :

a GVariant, which will be sunk

event_id :

a pointer for the event ID return, or NULL

error :

a pointer to a NULL GError pointer, or NULL

dconf_set_async ()

void                dconf_set_async                     (const gchar *key,
                                                         GVariant *value,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);

Sets the value of a key in the dconf database.

This is the asynchronous variant of dconf_set(). When the merge is complete, callback will be called with a DConfAsyncResult and user_data. You should pass the DConfAsyncResult to dconf_set_finish() to collect the result.

key :

a dconf key

value :

a GVariant, on which g_variant_ref_sink() will be called

callback :

the completion callback

user_data :

user data for callback

dconf_set_finish ()

gboolean            dconf_set_finish                    (DConfAsyncResult *result,
                                                         gchar **event_id,
                                                         GError **error);

Collects the results from a call to dconf_set_async().

This is the second half of the asynchronous variant of dconf_set().

result :

the DConfAsyncResult given to your callback

event_id :

a pointer for the event ID return, or NULL

error :

a pointer to a NULL GError pointer, or NULL

returns :

TRUE on success

dconf_set_locked ()

gboolean            dconf_set_locked                    (const gchar *key_or_path,
                                                         gboolean locked,
                                                         GError **error);

Locks or unlocks a key or path in the dconf database.

This marks a given key or set of keys in the dconf database as locked. Writes will be prevented to any key that is locked or is contained inside of a path that is locked.

If the operation is successful then TRUE will be returned. In the event of a failure of any kind then no changes will be made to the database, error (if non-NULL) will be set and FALSE will be returned.

It is a programmer error to call this function with a key_or_path that is not a valid dconf path (as per dconf_is_path()) or key (as per dconf_is_key()).

key_or_path :

a dconf key or path

error :

a pointer to a NULL GError pointer, or NULL

dconf_set_locked_async ()

void                dconf_set_locked_async              (const gchar *key_or_path,
                                                         gboolean locked,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);

Locks or unlocks a key or path in the dconf database.

This is the asynchronous variant of dconf_set_locked(). When the operation is complete, callback will be called with a DConfAsyncResult and user_data. You should pass the DConfAsyncResult to dconf_set_locked_finish() to collect the result.

key_or_path :

a dconf key or path

callback :

the completion callback

user_data :

user data for callback

dconf_set_locked_finish ()

gboolean            dconf_set_locked_finish             (DConfAsyncResult *result,
                                                         GError **error);

Collects the results from a call to dconf_set_locked_async().

This is the second half of the asynchronous variant of dconf_set_locked().

result :

the DConfAsyncResult given to your callback

error :

a pointer to a NULL GError pointer, or NULL

returns :

TRUE on success

dconf_reset ()

gboolean            dconf_reset                         (const gchar *key,
                                                         gchar **event_id,
                                                         GError **error);

Resets the value of a key in the dconf database.

This unsets the value in the toplevel database. This will either result in the key no longer existing, or it reverting to a default value (as specified in a lower-level database).

In the event of a failure of any kind then no changes will be made to the database, error (if non-NULL) will be set and FALSE will be returned.

If the reset is successful then TRUE will be returned. If event_id is non-NULL it will be set to the event ID number of the merge. The event ID will be the same as the ID that is sent for the change notification corresponding to this modification and is unique for the life of the program. It has no particular format.

It is a programmer error to call this function with a key that is not a valid dconf key (as per dconf_is_key()).

key :

a dconf key

event_id :

a pointer for the event ID return, or NULL

error :

a pointer to a NULL GError pointer, or NULL

dconf_reset_async ()

void                dconf_reset_async                   (const gchar *key,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);

Resets the value of a key in the dconf database.

This is the asynchronous variant of dconf_reset(). When the merge is complete, callback will be called with a DConfAsyncResult and user_data. You should pass the DConfAsyncResult to dconf_reset_finish() to collect the result.

key :

a dconf key

callback :

the completion callback

user_data :

user data for callback

dconf_reset_finish ()

gboolean            dconf_reset_finish                  (DConfAsyncResult *result,
                                                         gchar **event_id,
                                                         GError **error);

Collects the results from a call to dconf_reset_async().

This is the second half of the asynchronous variant of dconf_reset().

result :

the DConfAsyncResult given to your callback

event_id :

a pointer for the event ID return, or NULL

error :

a pointer to a NULL GError pointer, or NULL

returns :

TRUE on success

dconf_merge ()

gboolean            dconf_merge                         (const gchar *prefix,
                                                         GTree *tree,
                                                         gchar **event_id,
                                                         GError **error);

Atomically set the value of several keys in the dconf database.

This is a "merge" in the sense that the values in tree are merged into the existing configuration database at prefix.

tree should be a GTree created by a call to dconf_tree_new().

There are two ways to use this call.

In the simple case for setting the value of a single key, prefix should be equal to the path of the key to set and tree should contain a single entry: a key of "" and a value of the GVariant value to set at prefix.

In the case of setting more than one key, prefix should be equal to the largest common prefix of the key shared by each of the keys to be set (up to and including the nearest '/'). Each key in tree should then be a path relative to this common prefix and each corresponding value should be the GVariant value to store at that path.

It is not an error to call this function with a prefix that is not the largest it could possibly be. It is also not an error to call this function with prefix being a path and tree containing a single item with a key that is not equal to "". Using a prefix that is not specific to a single backend database (ie: specifying '/') is an error, however, and using shorter prefixes will generally result in unnecessary wakeups (for example, using a prefix of '/user/' will result in waking up every process watching for any change notification anywhere within '/user/').

In the event of a failure of any kind then no changes will be made to the database, error (if non-NULL) will be set and FALSE will be returned.

If the merge is successful then TRUE will be returned. If event_id is non-NULL it will be set to the event ID number of the merge. The event ID will be the same as the ID that is sent for the change notification corresponding to this modification and is unique for the life of the program. It has no particular format.

prefix :

the common part of the path to write to

tree :

a list of the values to store

event_id :

a pointer for the event ID return, or NULL

error :

a pointer to a NULL GError pointer, or NULL

returns :

TRUE on success

dconf_merge_async ()

void                dconf_merge_async                   (const gchar *prefix,
                                                         GTree *tree,
                                                         DConfAsyncReadyCallback callback,
                                                         gpointer user_data);

Atomically set the value of several keys in the dconf database.

This is the asynchronous variant of dconf_merge(). When the merge is complete, callback will be called with a DConfAsyncResult and user_data. You should pass the DConfAsyncResult to dconf_merge_finish() to collect the result.

prefix :

the common part of the path to write to

values :

a list of the values to store

callback :

the completion callback

user_data :

user data for callback

dconf_merge_finish ()

gboolean            dconf_merge_finish                  (DConfAsyncResult *result,
                                                         gchar **event_id,
                                                         GError **error);

Collects the results from a call to dconf_merge_async().

This is the second half of the asynchronous variant of dconf_merge().

result :

the DConfAsyncResult given to your callback

event_id :

a pointer for the event ID return, or NULL

error :

a pointer to a NULL GError pointer, or NULL

returns :

TRUE on success

dconf_watch ()

void                dconf_watch                         (const gchar *match,
                                                         DConfWatchFunc func,
                                                         gpointer user_data);

Watch part of the database for changes.

If match ends with a '/' then any key that changes under the path given by match will result in callback being called.

If match does not end with a '/' then the key exactly specified by match will result in callback being called.

You will currently get spurious callbacks. This will be fixed.

match :

a key or path to watch

callback :

a DConfWatchFunc

user_data :

user data for callback

dconf_unwatch ()

void                dconf_unwatch                       (const gchar *match,
                                                         DConfWatchFunc func,
                                                         gpointer user_data);

Removes an existing watch. The given arguments must exactly match the ones given to an earlier call to dconf_watch() (callback and user_data must be identical; match need only be equal by string comparison).

In the event that more than one watch was registered with the same values then this call removes only one of them.

match :

the exact key or path given to dconf_watch()

callback :

the exact callback given to dconf_watch()

user_data :

the exact user data given to dconf_watch()