![]() |
![]() |
![]() |
dconf Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
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);
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);
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 "/".
|
a possible key |
Returns : |
TRUE if key is valid
|
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.
|
a possible path |
Returns : |
TRUE if path is valid
|
gboolean dconf_is_key_or_path (const gchar *key_or_path);
Determines if key_or_path
is a valid key or path.
|
a possible key or path |
Returns : |
TRUE if key_or_path is valid
|
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.
|
a possible relative key |
Returns : |
TRUE if relative_key is valid
|
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.
|
a dconf key or path |
|
a dconf key or path |
Returns : |
TRUE iff key_or_path1 matches key_or_path2
|
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()
).
|
a dconf key |
|
a GVariant, or NULL
|
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()
).
|
a dconf path |
|
a pointer to the length of the return value |
|
a NULL -terminated list of strings
|
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()
).
|
a dconf key or path |
|
TRUE if writing to key_or_path would work
|
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()
).
|
a dconf key or path |
|
TRUE if key_or_path is locked
|
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()
).
|
a dconf key |
|
a GVariant, which will be sunk |
|
a pointer for the event ID return, or NULL
|
|
a pointer to a NULL GError pointer, or NULL
|
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.
|
a dconf key |
|
a GVariant, on which g_variant_ref_sink() will be called
|
|
the completion callback |
|
user data for callback
|
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()
.
|
the DConfAsyncResult given to your callback |
|
a pointer for the event ID return, or NULL
|
|
a pointer to a NULL GError pointer, or NULL
|
|
TRUE on success
|
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()
).
|
a dconf key or path |
|
a pointer to a NULL GError pointer, or NULL
|
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.
|
a dconf key or path |
|
the completion callback |
|
user data for callback
|
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()
.
|
the DConfAsyncResult given to your callback |
|
a pointer to a NULL GError pointer, or NULL
|
|
TRUE on success
|
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()
).
|
a dconf key |
|
a pointer for the event ID return, or NULL
|
|
a pointer to a NULL GError pointer, or NULL
|
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.
|
a dconf key |
|
the completion callback |
|
user data for callback
|
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()
.
|
the DConfAsyncResult given to your callback |
|
a pointer for the event ID return, or NULL
|
|
a pointer to a NULL GError pointer, or NULL
|
|
TRUE on success
|
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.
|
the common part of the path to write to |
|
a list of the values to store |
|
a pointer for the event ID return, or NULL
|
|
a pointer to a NULL GError pointer, or NULL
|
|
TRUE on success
|
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.
|
the common part of the path to write to |
|
a list of the values to store |
|
the completion callback |
|
user data for callback
|
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()
.
|
the DConfAsyncResult given to your callback |
|
a pointer for the event ID return, or NULL
|
|
a pointer to a NULL GError pointer, or NULL
|
|
TRUE on success
|
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.
|
a key or path to watch |
|
a DConfWatchFunc |
|
user data for callback
|
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.
|
the exact key or path given to dconf_watch()
|
|
the exact callback given to dconf_watch()
|
|
the exact user data given to dconf_watch()
|