Top | ![]() |
![]() |
![]() |
![]() |
DConfClient * | dconf_client_new () |
GVariant * | dconf_client_read () |
GVariant * | dconf_client_read_full () |
gchar ** | dconf_client_list () |
gchar ** | dconf_client_list_locks () |
gboolean | dconf_client_is_writable () |
gboolean | dconf_client_write_fast () |
gboolean | dconf_client_write_sync () |
gboolean | dconf_client_change_fast () |
gboolean | dconf_client_change_sync () |
void | dconf_client_watch_fast () |
void | dconf_client_watch_sync () |
void | dconf_client_unwatch_fast () |
void | dconf_client_unwatch_sync () |
void | dconf_client_sync () |
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.
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.
GVariant * dconf_client_read_full (DConfClient *client
,const gchar *key
,DConfReadFlags flags
,const GQueue *read_through
);
Reads the current value of key
.
If flags
contains DCONF_READ_USER_VALUE
then only the user value
will be read. Locks are ignored, which means that it is possible to
use this API to read "invisible" user values which are hidden by
system locks.
If flags
contains DCONF_READ_DEFAULT_VALUE
then only non-user
values will be read. The result will be exactly equivalent to the
value that would be read if the current value of the key were to be
reset.
Flags may not contain both DCONF_READ_USER_VALUE
and
DCONF_READ_DEFAULT_VALUE
.
If read_through
is non-NULL
, DCONF_READ_DEFAULT_VALUE
is not
given then read_through
is checked for the key in question, subject
to the restriction that the key in question is writable. This
effectively answers the question of "what would happen if these
changes were committed".
If there are outstanding "fast" changes in progress they may affect the result of this call.
If flags
is DCONF_READ_FLAGS_NONE
and read_through
is NULL
then
this call is exactly equivalent to dconf_client_read()
.
client |
||
key |
the key to read the default value of |
|
flags |
||
read_through |
a GQueue of DConfChangeset |
Since 0.26
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.
gchar ** dconf_client_list_locks (DConfClient *client
,const gchar *dir
,gint *length
);
Lists all locks under dir
in effect for client
.
If no locks are in effect, an empty list is returned. If no keys are
writable at all then a list containing dir
is returned.
The returned list will be NULL
-terminated.
Since 0.26
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.
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.
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.
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.
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. If changeset
makes no changes then tag
may be
non-unique (eg: the empty string may be used for empty changesets).
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.
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 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.
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).
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).
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.
no flags |
||
read the default value, ignoring any values in writable databases or any queued changes. This is effectively equivalent to asking what value would be read after a reset was written for the key in question. |
||
read the user value, ignoring any system databases, including ignoring locks. It is even possible to read "invisible" values in the user database in this way, which would have normally been ignored because of locks. |
Since 0.26