Top | ![]() |
![]() |
![]() |
![]() |
void | (*DConfWatchFunc) () |
DConfClient * | dconf_client_new () |
GVariant * | dconf_client_read () |
GVariant * | dconf_client_read_default () |
GVariant * | dconf_client_read_no_default () |
gchar ** | dconf_client_list () |
gboolean | dconf_client_is_writable () |
gboolean | dconf_client_write () |
void | dconf_client_write_async () |
gboolean | dconf_client_write_finish () |
gboolean | dconf_client_write_many () |
gboolean | dconf_client_watch () |
void | dconf_client_watch_async () |
gboolean | dconf_client_watch_finish () |
gboolean | dconf_client_unwatch () |
void | dconf_client_unwatch_async () |
gboolean | dconf_client_unwatch_finish () |
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.
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.
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 |
|
tag |
the tag associated with the change |
|
user_data |
the user data given to |
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.
profile |
the dconf profile to use, or |
|
watch_func |
the function to call when changes occur |
|
user_data |
the user_data to pass to |
|
notify |
the function to free |
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.
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.
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.
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.
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.
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.
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.
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()
.
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.
client |
||
dir |
the dconf directory under which to make the writes |
|
rels |
a |
|
values |
an array of possibly- |
|
n_values |
the length of |
|
tag |
the tag from this write. |
[out][allow-none] |
cancellable |
a GCancellable, or |
|
error |
a pointer to a GError, or |
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()
.
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.
gboolean dconf_client_watch_finish (DConfClient *client
,GAsyncResult *result
,GError **error
);
Collects the result from a prior call to dconf_client_watch_async()
.
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()
.
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.
gboolean dconf_client_unwatch_finish (DConfClient *client
,GAsyncResult *result
,GError **error
);
Collects the result from a prior call to
dconf_client_unwatch_async()
.