diff options
author | Ryan Lortie <desrt@desrt.ca> | 2012-07-10 09:30:24 -0400 |
---|---|---|
committer | Ryan Lortie <desrt@desrt.ca> | 2012-07-10 09:30:24 -0400 |
commit | 1f08d55b68740d917bbaf5c2c6ca3dcb81c396e3 (patch) | |
tree | 89b99367e3266bdcb49682e4bac87e38feecb3e8 /client | |
parent | a8fe07c1238d6b2345672f54a1ce875191b5bef7 (diff) | |
download | dconf-1f08d55b68740d917bbaf5c2c6ca3dcb81c396e3.tar.gz |
big docs cleanup
We're now back at 100% docs coverage with no warnings.
Diffstat (limited to 'client')
-rw-r--r-- | client/dconf-client.c | 276 | ||||
-rw-r--r-- | client/extra-docs.c | 89 |
2 files changed, 276 insertions, 89 deletions
diff --git a/client/dconf-client.c b/client/dconf-client.c index eced4f1..fad445c 100644 --- a/client/dconf-client.c +++ b/client/dconf-client.c @@ -25,6 +25,30 @@ #include "../engine/dconf-engine.h" #include <glib-object.h> +/** + * SECTION:client + * @title: DConfClient + * @short_description: Direct read and write access to DConf, based on GDBus + * + * 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. + **/ + +/** + * DConfClient: + * + * The main object for interacting with dconf. This is a #GObject, so + * you should manage it with g_object_ref() and g_object_unref(). + **/ struct _DConfClient { GObject parent_instance; @@ -64,6 +88,45 @@ dconf_client_class_init (DConfClientClass *class) { class->finalize = dconf_client_finalize; + /** + * DConfClient::changed: + * @client: the #DConfClient reporting the change + * @prefix: the prefix under which the changes happened + * @changes: the list of paths that were changed, relative to @prefix + * @tag: the tag for the change, if it originated from the service + * + * This signal is emitted when the #DConfClient has a possible change + * to report. The signal is an indication that a change may have + * occured; it's possible that the keys will still have the same value + * as before. + * + * To ensure that you receive notification about changes to paths that + * you are interested in you must call dconf_client_watch_fast() or + * dconf_client_watch_sync(). You may still receive notifications for + * paths that you did not explicitly watch. + * + * @prefix will be an absolute dconf path; see dconf_is_path(). + * @changes is a %NULL-terminated array of dconf rel paths; see + * dconf_is_rel_path(). + * + * @tag is an opaque tag string, or %NULL. The only thing you should + * do with @tag is to compare it to tag values returned by + * dconf_client_write_sync() or dconf_client_change_sync(). + * + * The number of changes being reported is equal to the length of + * @changes. Appending each item in @changes to @prefix will give the + * absolute path of each changed item. + * + * If a single key has changed then @prefix will be equal to the key + * and @changes will contain a single item: the empty string. + * + * If a single dir has changed (indicating that any key under the dir + * may have changed) then @prefix will be equal to the dir and + * @changes will contain a single empty string. + * + * If more than one change is being reported then @changes will have + * more than one item. + **/ dconf_client_signals[SIGNAL_CHANGED] = g_signal_new ("changed", DCONF_TYPE_CLIENT, G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 3, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE, @@ -132,6 +195,13 @@ dconf_client_free_weak_ref (gpointer data) g_slice_free (GWeakRef, weak_ref); } +/** + * dconf_client_new: + * + * Creates a new #DConfClient. + * + * Returns: a new #DConfClient + **/ DConfClient * dconf_client_new (void) { @@ -147,6 +217,20 @@ dconf_client_new (void) return client; } +/** + * dconf_client_read: + * @client: a #DConfClient + * @key: the key to read the value of + * + * 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. + * + * Returns: a #GVariant, or %NULL + **/ GVariant * dconf_client_read (DConfClient *client, const gchar *key) @@ -156,6 +240,23 @@ dconf_client_read (DConfClient *client, return dconf_engine_read (client->engine, NULL, key); } +/** + * dconf_client_list: + * @client: a #DConfClient + * @dir: the dir to list the contents of + * @length: the length of the returned list + * + * 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. + * + * Returns: an array of strings, never %NULL. + **/ gchar ** dconf_client_list (DConfClient *client, const gchar *dir, @@ -166,6 +267,21 @@ dconf_client_list (DConfClient *client, return dconf_engine_list (client->engine, dir, length); } +/** + * dconf_client_is_writable: + * @client: a #DConfClient + * @key: the key to check for writability + * + * 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. + * + * Returns: %TRUE is @key is writable + **/ gboolean dconf_client_is_writable (DConfClient *client, const gchar *key) @@ -175,6 +291,33 @@ dconf_client_is_writable (DConfClient *client, return dconf_engine_is_writable (client->engine, key); } +/** + * dconf_client_write_fast: + * @client: a #DConfClient + * @key: the key to write to + * @value: a #GVariant, the value to write + * @error: a pointer to a %NULL #GError, or %NULL + * + * 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. + * + * 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. + * + * Returns: %TRUE if the write was queued + **/ gboolean dconf_client_write_fast (DConfClient *client, const gchar *key, @@ -193,6 +336,31 @@ dconf_client_write_fast (DConfClient *client, return success; } +/** + * dconf_client_write_sync: + * @client: a #DConfClient + * @key: the key to write to + * @value: a #GVariant, the value to write + * @tag: (out) (allow-none): the tag from this write + * @cancellable: a #GCancellable, or %NULL + * @error: a pointer to a %NULL #GError, or %NULL + * + * 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. + * + * Returns: %TRUE on success, else %FALSE with @error set + **/ gboolean dconf_client_write_sync (DConfClient *client, const gchar *key, @@ -213,6 +381,31 @@ dconf_client_write_sync (DConfClient *client, return success; } +/** + * dconf_client_change_fast: + * @client: a #DConfClient + * @changeset: the changeset describing the requested change + * @error: a pointer to a %NULL #GError, or %NULL + * + * 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. + * + * 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. + * + * Returns: %TRUE if the requested changed was queued + **/ gboolean dconf_client_change_fast (DConfClient *client, DConfChangeset *changeset, @@ -223,6 +416,30 @@ dconf_client_change_fast (DConfClient *client, return dconf_engine_change_fast (client->engine, changeset, error); } +/** + * dconf_client_change_sync: + * @client: a #DConfClient + * @changeset: the changeset describing the requested change + * @tag: (out) (allow-none): the tag from this write + * @cancellable: a #GCancellable, or %NULL + * @error: a pointer to a %NULL #GError, or %NULL + * + * 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. + * + * Returns: %TRUE on success, else %FALSE with @error set + **/ gboolean dconf_client_change_sync (DConfClient *client, DConfChangeset *changeset, @@ -235,6 +452,23 @@ dconf_client_change_sync (DConfClient *client, return dconf_engine_change_sync (client->engine, changeset, tag, error); } +/** + * dconf_client_watch_fast: + * @client: a #DConfClient + * @path: a path to watch + * + * 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_fast (DConfClient *client, const gchar *path) @@ -244,6 +478,22 @@ dconf_client_watch_fast (DConfClient *client, dconf_engine_watch_fast (client->engine, path); } +/** + * dconf_client_watch_sync: + * @client: a #DConfClient + * @path: a path to watch + * + * 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 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_watch_sync (DConfClient *client, const gchar *path) @@ -253,6 +503,19 @@ dconf_client_watch_sync (DConfClient *client, dconf_engine_watch_sync (client->engine, path); } +/** + * dconf_client_unwatch_fast: + * @client: a #DConfClient + * @path: a path previously watched + * + * 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_fast (DConfClient *client, const gchar *path) @@ -262,6 +525,19 @@ dconf_client_unwatch_fast (DConfClient *client, dconf_engine_unwatch_fast (client->engine, path); } +/** + * dconf_client_unwatch_sync: + * @client: a #DConfClient + * @path: a path previously watched + * + * 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_unwatch_sync (DConfClient *client, const gchar *path) diff --git a/client/extra-docs.c b/client/extra-docs.c deleted file mode 100644 index 2f12951..0000000 --- a/client/extra-docs.c +++ /dev/null @@ -1,89 +0,0 @@ -/* extra docs here until we can emit them with Vala */ - -/** - * SECTION:client - * @title: DConfClient - * @short_description: Direct read and write access to DConf, based on GDBus - * - * 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. - **/ - -/** - * DConfWatchFunc: - * @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() - * - * 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. - **/ - -/** - * DConfClient: - * - * An opaque structure type. May only be used with the following - * functions. - **/ - -/** - * dconf_client_write_finish: - * @client: a #DConfClient - * @result: the #GAsyncResult passed to the #GAsyncReadyCallback - * @tag: (out) (allow-none): the tag from this write - * @error: a pointer to a #GError, or %NULL - * - * Collects the result from a prior call to dconf_client_write_async(). - **/ - -/** - * dconf_client_set_locked_finish: - * @client: a #DConfClient - * @result: the #GAsyncResult passed to the #GAsyncReadyCallback - * @error: a pointer to a #GError, or %NULL - * - * Collects the result from a prior call to - * dconf_client_set_locked_async(). - **/ - -/** - * dconf_client_watch_finish: - * @client: a #DConfClient - * @result: the #GAsyncResult passed to the #GAsyncReadyCallback - * @error: a pointer to a #GError, or %NULL - * - * Collects the result from a prior call to dconf_client_watch_async(). - **/ - -/** - * dconf_client_unwatch_finish: - * @client: a #DConfClient - * @result: the #GAsyncResult passed to the #GAsyncReadyCallback - * @error: a pointer to a #GError, or %NULL - * - * Collects the result from a prior call to - * dconf_client_unwatch_async(). - **/ |