diff options
| -rw-r--r-- | client/dconf-client.c | 276 | ||||
| -rw-r--r-- | client/extra-docs.c | 89 | ||||
| -rw-r--r-- | common/dconf-changeset.c | 231 | ||||
| -rw-r--r-- | common/dconf-changeset.h | 48 | ||||
| -rw-r--r-- | common/dconf-paths.c | 24 | ||||
| -rw-r--r-- | common/dconf-paths.h | 2 | ||||
| -rw-r--r-- | docs/Makefile.am | 12 | ||||
| -rw-r--r-- | docs/dconf-docs.xml | 5 | ||||
| -rw-r--r-- | docs/dconf-sections.txt | 40 | ||||
| -rw-r--r-- | tests/paths.c | 12 |
10 files changed, 520 insertions, 219 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(). - **/ diff --git a/common/dconf-changeset.c b/common/dconf-changeset.c index 1dcee39..195841a 100644 --- a/common/dconf-changeset.c +++ b/common/dconf-changeset.c @@ -25,12 +25,38 @@ #include <string.h> #include <stdlib.h> +/** + * SECTION:changeset + * @title: DConfChangeset + * @Short_description: A set of changes to a dconf database + * + * #DConfChangeset represents a set of changes that can be made to a + * dconf database. Currently supported operations are writing new + * values to keys and resetting keys and dirs. + * + * Create the changeset with dconf_changeset_new() and populate it with + * dconf_changeset_set(). Submit it to dconf with + * dconf_client_change_fast() or dconf_client_change_sync(). + * dconf_changeset_new_write() is a convenience constructor for the + * common case of writing or resetting a single value. + **/ + +/** + * DConfChangeset: + * + * This is a reference counted opaque structure type. It is not a + * #GObject. + * + * Use dconf_changeset_ref() and dconf_changeset_unref() to manipuate + * references. + **/ + struct _DConfChangeset { GHashTable *table; gint ref_count; - gchar *root; + gchar *prefix; const gchar **paths; GVariant **values; }; @@ -52,47 +78,55 @@ unref_gvariant0 (gpointer data) DConfChangeset * dconf_changeset_new (void) { - DConfChangeset *change; + DConfChangeset *changeset; - change = g_slice_new0 (DConfChangeset); - change->table = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, unref_gvariant0); - change->ref_count = 1; + changeset = g_slice_new0 (DConfChangeset); + changeset->table = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, unref_gvariant0); + changeset->ref_count = 1; - return change; + return changeset; } /** * dconf_changeset_unref: - * @change: a #DConfChangeset + * @changeset: a #DConfChangeset * * Releases a #DConfChangeset reference. **/ void -dconf_changeset_unref (DConfChangeset *change) +dconf_changeset_unref (DConfChangeset *changeset) { - if (g_atomic_int_dec_and_test (&change->ref_count)) + if (g_atomic_int_dec_and_test (&changeset->ref_count)) { - g_free (change->root); - g_free (change->paths); - g_free (change->values); + g_free (changeset->prefix); + g_free (changeset->paths); + g_free (changeset->values); - g_hash_table_unref (change->table); + g_hash_table_unref (changeset->table); - g_slice_free (DConfChangeset, change); + g_slice_free (DConfChangeset, changeset); } } +/** + * dconf_changeset_ref: + * @changeset: a #DConfChangeset + * + * Increases the reference count on @changeset + * + * Returns: @changeset + **/ DConfChangeset * -dconf_changeset_ref (DConfChangeset *change) +dconf_changeset_ref (DConfChangeset *changeset) { - g_atomic_int_inc (&change->ref_count); + g_atomic_int_inc (&changeset->ref_count); - return change; + return changeset; } /** * dconf_changeset_set: - * @change: a #DConfChangeset + * @changeset: a #DConfChangeset * @path: a path to modify * @value: the value for the key, or %NULL to reset * @@ -105,11 +139,11 @@ dconf_changeset_ref (DConfChangeset *change) * %NULL. It is not permitted to assign a #GVariant value to a dir. **/ void -dconf_changeset_set (DConfChangeset *change, +dconf_changeset_set (DConfChangeset *changeset, const gchar *path, GVariant *value) { - g_return_if_fail (change->root == NULL); + g_return_if_fail (changeset->prefix == NULL); g_return_if_fail (dconf_is_path (path, NULL)); /* Check if we are performing a path reset */ @@ -123,23 +157,23 @@ dconf_changeset_set (DConfChangeset *change, /* When we reset a path we must also reset all keys within that * path. */ - g_hash_table_iter_init (&iter, change->table); + g_hash_table_iter_init (&iter, changeset->table); while (g_hash_table_iter_next (&iter, &key, NULL)) if (g_str_has_prefix (key, path)) g_hash_table_iter_remove (&iter); /* Record the reset itself. */ - g_hash_table_insert (change->table, g_strdup (path), NULL); + g_hash_table_insert (changeset->table, g_strdup (path), NULL); } /* else, just a normal value write or reset */ else - g_hash_table_insert (change->table, g_strdup (path), value ? g_variant_ref_sink (value) : NULL); + g_hash_table_insert (changeset->table, g_strdup (path), value ? g_variant_ref_sink (value) : NULL); } /** * dconf_changeset_get: - * @change: a #DConfChangeset + * @changeset: a #DConfChangeset * @key: the key to check * @value: a return location for the value, or %NULL * @@ -156,13 +190,13 @@ dconf_changeset_set (DConfChangeset *change, * Returns: %TRUE if the key is being modified by the change */ gboolean -dconf_changeset_get (DConfChangeset *change, +dconf_changeset_get (DConfChangeset *changeset, const gchar *key, GVariant **value) { gpointer tmp; - if (!g_hash_table_lookup_extended (change->table, key, NULL, &tmp)) + if (!g_hash_table_lookup_extended (changeset->table, key, NULL, &tmp)) return FALSE; if (value) @@ -173,10 +207,10 @@ dconf_changeset_get (DConfChangeset *change, /** * dconf_changeset_is_similar_to: - * @change: a #DConfChangeset + * @changeset: a #DConfChangeset * @other: another #DConfChangeset * - * Checks if @change is similar to @other. + * Checks if @changeset is similar to @other. * * Two changes are considered similar if they write to the exact same * set of keys. The values written are not considered. @@ -193,16 +227,16 @@ dconf_changeset_get (DConfChangeset *change, * Returns: %TRUE if the changes are similar **/ gboolean -dconf_changeset_is_similar_to (DConfChangeset *change, +dconf_changeset_is_similar_to (DConfChangeset *changeset, DConfChangeset *other) { GHashTableIter iter; gpointer key; - if (g_hash_table_size (change->table) != g_hash_table_size (other->table)) + if (g_hash_table_size (changeset->table) != g_hash_table_size (other->table)) return FALSE; - g_hash_table_iter_init (&iter, change->table); + g_hash_table_iter_init (&iter, changeset->table); while (g_hash_table_iter_next (&iter, &key, NULL)) if (!g_hash_table_contains (other->table, key)) return FALSE; @@ -211,9 +245,23 @@ dconf_changeset_is_similar_to (DConfChangeset *change, } /** + * DConfChangesetPredicate: + * @path: a path, as per dconf_is_path() + * @value: a #GVariant, or %NULL + * @user_data: user data pointer + * + * Callback function type for predicates over items in a + * #DConfChangeset. + * + * Use with dconf_changeset_all(). + * + * Returns: %TRUE if the predicate is met for the given @path and @value + **/ + +/** * dconf_changeset_all: - * @change: a #DConfChangeset - * @predicate: a #DConfChangePredicate + * @changeset: a #DConfChangeset + * @predicate: a #DConfChangesetPredicate * @user_data: user data to pass to @predicate * * Checks if all changes in the changeset satisfy @predicate. @@ -225,17 +273,17 @@ dconf_changeset_is_similar_to (DConfChangeset *change, * %FALSE. If not (including the case of no items) then this function * returns %TRUE. * - * Returns: %TRUE if all items in @change satisfy @predicate + * Returns: %TRUE if all items in @changeset satisfy @predicate */ gboolean -dconf_changeset_all (DConfChangeset *change, +dconf_changeset_all (DConfChangeset *changeset, DConfChangesetPredicate predicate, gpointer user_data) { GHashTableIter iter; gpointer key, value; - g_hash_table_iter_init (&iter, change->table); + g_hash_table_iter_init (&iter, changeset->table); while (g_hash_table_iter_next (&iter, &key, &value)) if (!(* predicate) (key, value, user_data)) return FALSE; @@ -254,12 +302,12 @@ dconf_changeset_string_ptr_compare (gconstpointer a_p, } static void -dconf_changeset_build_description (DConfChangeset *change) +dconf_changeset_build_description (DConfChangeset *changeset) { gsize prefix_length; gint n_items; - n_items = g_hash_table_size (change->table); + n_items = g_hash_table_size (changeset->table); /* If there are no items then what is there to describe? */ if (n_items == 0) @@ -291,7 +339,7 @@ dconf_changeset_build_description (DConfChangeset *change) const gchar *first; gpointer key; - g_hash_table_iter_init (&iter, change->table); + g_hash_table_iter_init (&iter, changeset->table); /* We checked above that we have at least one item. */ if (!g_hash_table_iter_next (&iter, &key, NULL)) @@ -329,7 +377,7 @@ dconf_changeset_build_description (DConfChangeset *change) prefix_length--; } - change->root = g_strndup (first, prefix_length); + changeset->prefix = g_strndup (first, prefix_length); } /* Pass 2: collect the list of keys, dropping the prefix */ @@ -338,63 +386,94 @@ dconf_changeset_build_description (DConfChangeset *change) gpointer key; gint i = 0; - change->paths = g_new (const gchar *, n_items + 1); + changeset->paths = g_new (const gchar *, n_items + 1); - g_hash_table_iter_init (&iter, change->table); + g_hash_table_iter_init (&iter, changeset->table); while (g_hash_table_iter_next (&iter, &key, NULL)) { const gchar *path = key; - change->paths[i++] = path + prefix_length; + changeset->paths[i++] = path + prefix_length; } - change->paths[i] = NULL; + changeset->paths[i] = NULL; g_assert (i == n_items); /* Sort the list of keys */ - qsort (change->paths, n_items, sizeof (const gchar *), dconf_changeset_string_ptr_compare); + qsort (changeset->paths, n_items, sizeof (const gchar *), dconf_changeset_string_ptr_compare); } /* Pass 3: collect the list of values */ { gint i; - change->values = g_new (GVariant *, n_items); + changeset->values = g_new (GVariant *, n_items); for (i = 0; i < n_items; i++) /* We dropped the prefix when collecting the array. * Bring it back temporarily, for the lookup. */ - change->values[i] = g_hash_table_lookup (change->table, change->paths[i] - prefix_length); + changeset->values[i] = g_hash_table_lookup (changeset->table, changeset->paths[i] - prefix_length); } } +/** + * dconf_changeset_describe: + * @changeset: a #DConfChangeset + * @prefix: the prefix under which changes have been requested + * @paths: the list of paths changed, relative to @prefix + * @values: the list of values changed + * + * Describes @changeset. + * + * @prefix and @paths are presented in the same way as they are for the + * DConfClient::changed signal. @values is an array of the same length + * as @paths. For each key described by an element in @paths, @values + * will contain either a #GVariant (the requested new value of that key) + * or %NULL (to reset a reset). + * + * The @paths array is returned in an order such that dir will always + * come before keys contained within those dirs. + * + * Returns: the number of changes (the length of @changes and @values). + **/ guint -dconf_changeset_describe (DConfChangeset *change, - const gchar **root, +dconf_changeset_describe (DConfChangeset *changeset, + const gchar **prefix, const gchar * const **paths, GVariant * const **values) { gint n_items; - n_items = g_hash_table_size (change->table); + n_items = g_hash_table_size (changeset->table); - if (n_items && !change->root) - dconf_changeset_build_description (change); + if (n_items && !changeset->prefix) + dconf_changeset_build_description (changeset); - if (root) - *root = change->root; + if (prefix) + *prefix = changeset->prefix; if (paths) - *paths = change->paths; + *paths = changeset->paths; if (values) - *values = change->values; + *values = changeset->values; return n_items; } +/** + * dconf_changeset_serialise: + * @changeset: a #DConfChangeset + * + * Serialises a #DConfChangeset. + * + * The returned value has no particular format and should only be passed + * to dconf_changeset_deserialise(). + * + * Returns: a floating #GVariant + **/ GVariant * -dconf_changeset_serialise (DConfChangeset *change) +dconf_changeset_serialise (DConfChangeset *changeset) { GVariantBuilder builder; GHashTableIter iter; @@ -402,22 +481,37 @@ dconf_changeset_serialise (DConfChangeset *change) g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{smv}")); - g_hash_table_iter_init (&iter, change->table); + g_hash_table_iter_init (&iter, changeset->table); while (g_hash_table_iter_next (&iter, &key, &value)) g_variant_builder_add (&builder, "{smv}", key, value); return g_variant_builder_end (&builder); } +/** + * dconf_changeset_deserialise: + * @serialised: a #GVariant from dconf_changeset_serialise() + * + * Creates a #DConfChangeset according to a serialised description + * returned from an earlier call to dconf_changeset_serialise(). + * + * @serialised has no particular format -- you should only pass a value + * that reasulted from an earlier serialise operation. + * + * This call never fails, even if @serialised is not in the correct + * format. Improperly-formatted parts are simply ignored. + * + * Returns: a new #DConfChangeset + **/ DConfChangeset * dconf_changeset_deserialise (GVariant *serialised) { - DConfChangeset *change; + DConfChangeset *changeset; GVariantIter iter; const gchar *key; GVariant *value; - change = dconf_changeset_new (); + changeset = dconf_changeset_new (); g_variant_iter_init (&iter, serialised); while (g_variant_iter_loop (&iter, "{&smv}", &key, &value)) { @@ -431,18 +525,29 @@ dconf_changeset_deserialise (GVariant *serialised) if (value == NULL) { if (dconf_is_path (key, NULL)) - g_hash_table_insert (change->table, g_strdup (key), NULL); + g_hash_table_insert (changeset->table, g_strdup (key), NULL); } else { if (dconf_is_key (key, NULL)) - g_hash_table_insert (change->table, g_strdup (key), g_variant_ref (value)); + g_hash_table_insert (changeset->table, g_strdup (key), g_variant_ref (value)); } } - return change; + return changeset; } +/** + * dconf_changeset_new_write: + * @path: a dconf path + * @value: a #GVariant, or %NULL + * + * Creates a new #DConfChangeset with one change. This is equivalent to + * calling dconf_changeset_new() and then dconf_changeset_set() with + * @path and @value. + * + * Returns: a new #DConfChangeset + **/ DConfChangeset * dconf_changeset_new_write (const gchar *path, GVariant *value) diff --git a/common/dconf-changeset.h b/common/dconf-changeset.h index de062fa..c2a5435 100644 --- a/common/dconf-changeset.h +++ b/common/dconf-changeset.h @@ -26,39 +26,39 @@ typedef struct _DConfChangeset DConfChangeset; -typedef gboolean (* DConfChangesetPredicate) (const gchar *key, - GVariant *value, - gpointer user_data); +typedef gboolean (* DConfChangesetPredicate) (const gchar *path, + GVariant *value, + gpointer user_data); DConfChangeset * dconf_changeset_new (void); -DConfChangeset * dconf_changeset_new_write (const gchar *key, - GVariant *value); +DConfChangeset * dconf_changeset_new_write (const gchar *path, + GVariant *value); -DConfChangeset * dconf_changeset_ref (DConfChangeset *changeset); -void dconf_changeset_unref (DConfChangeset *changeset); +DConfChangeset * dconf_changeset_ref (DConfChangeset *changeset); +void dconf_changeset_unref (DConfChangeset *changeset); -void dconf_changeset_set (DConfChangeset *changeset, - const gchar *key, - GVariant *value); +void dconf_changeset_set (DConfChangeset *changeset, + const gchar *path, + GVariant *value); -gboolean dconf_changeset_get (DConfChangeset *changeset, - const gchar *key, - GVariant **value); +gboolean dconf_changeset_get (DConfChangeset *changeset, + const gchar *key, + GVariant **value); -gboolean dconf_changeset_is_similar_to (DConfChangeset *changeset, - DConfChangeset *other); +gboolean dconf_changeset_is_similar_to (DConfChangeset *changeset, + DConfChangeset *other); -gboolean dconf_changeset_all (DConfChangeset *changeset, - DConfChangesetPredicate predicate, - gpointer user_data); +gboolean dconf_changeset_all (DConfChangeset *changeset, + DConfChangesetPredicate predicate, + gpointer user_data); -guint dconf_changeset_describe (DConfChangeset *changeset, - const gchar **change_root, - const gchar * const **changes, - GVariant * const **values); +guint dconf_changeset_describe (DConfChangeset *changeset, + const gchar **prefix, + const gchar * const **paths, + GVariant * const **values); -GVariant * dconf_changeset_serialise (DConfChangeset *changeset); -DConfChangeset * dconf_changeset_deserialise (GVariant *serialised); +GVariant * dconf_changeset_serialise (DConfChangeset *changeset); +DConfChangeset * dconf_changeset_deserialise (GVariant *serialised); #endif /* __dconf_changeset_h__ */ diff --git a/common/dconf-paths.c b/common/dconf-paths.c index 6f82ee9..33a6f74 100644 --- a/common/dconf-paths.c +++ b/common/dconf-paths.c @@ -106,13 +106,14 @@ * dconf_is_path: * @string: a string * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned - * Returns: %TRUE if @string is a path * * Checks if @string is a valid dconf path. dconf keys must start with * '/' and not contain '//'. * * A dconf path may be either a key or a dir. See dconf_is_key() and * dconf_is_dir() for examples of each. + * + * Returns: %TRUE if @string is a path **/ gboolean dconf_is_path (const gchar *string, @@ -127,7 +128,6 @@ dconf_is_path (const gchar *string, * dconf_is_key: * @string: a string * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned - * Returns: %TRUE if @string is a key * * Checks if @string is a valid dconf key. dconf keys must start with * '/', not contain '//' and not end with '/'. @@ -138,6 +138,8 @@ dconf_is_path (const gchar *string, * "/a", "/a/b" and "/a/b/c" are examples of keys. "", "/", "a", "a/b", * "//a/b", "/a//b", and "/a/" are examples of strings that are not * keys. + * + * Returns: %TRUE if @string is a key **/ gboolean dconf_is_key (const gchar *string, @@ -152,7 +154,6 @@ dconf_is_key (const gchar *string, * dconf_is_dir: * @string: a string * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned - * Returns: %TRUE if @string is a dir * * Checks if @string is a valid dconf dir. dconf dirs must start and * end with '/' and not contain '//'. @@ -164,6 +165,8 @@ dconf_is_key (const gchar *string, * "/", "/a/" and "/a/b/" are examples of dirs. "", "a/", "a/b/", * "//a/b/", "/a//b/" and "/a" are examples of strings that are not * dirs. + * + * Returns: %TRUE if @string is a dir **/ gboolean dconf_is_dir (const gchar *string, @@ -175,10 +178,9 @@ dconf_is_dir (const gchar *string, } /** - * dconf_is_rel: + * dconf_is_rel_path: * @string: a string * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned - * Returns: %TRUE if @string is a relative path * * Checks if @string is a valid dconf relative path. A relative path is * a string that, when concatenated to a dir, forms a valid dconf path. @@ -186,10 +188,12 @@ dconf_is_dir (const gchar *string, * * A dconf rel may be either a relative key or a relative dir. See * dconf_is_rel_key() and dconf_is_rel_dir() for examples of each. + * + * Returns: %TRUE if @string is a relative path **/ gboolean -dconf_is_rel (const gchar *string, - GError **error) +dconf_is_rel_path (const gchar *string, + GError **error) { #define type "relative path" vars; nonnull; relative; no_double_slash; path; @@ -201,7 +205,6 @@ dconf_is_rel (const gchar *string, * dconf_is_rel_key: * @string: a string * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned - * Returns: %TRUE if @string is a relative key * * Checks if @string is a valid dconf relative key. A relative key is a * string that, when concatenated to a dir, forms a valid dconf key. @@ -211,6 +214,8 @@ dconf_is_rel (const gchar *string, * "a", "a/b" and "a/b/c" are examples of relative keys. "", "/", "/a", * "/a/b", "//a/b", "/a//b", and "a/" are examples of strings that are * not relative keys. + * + * Returns: %TRUE if @string is a relative key **/ gboolean dconf_is_rel_key (const gchar *string, @@ -225,7 +230,6 @@ dconf_is_rel_key (const gchar *string, * dconf_is_rel_dir: * @string: a string * @error: a pointer to a #GError, or %NULL, set when %FALSE is returned - * Returns: %TRUE if @string is a relative dir * * Checks if @string is a valid dconf relative dir. A relative dir is a * string that, when appended to a dir, forms a valid dconf dir. This @@ -237,6 +241,8 @@ dconf_is_rel_key (const gchar *string, * "", "a/" and "a/b/" are examples of relative dirs. "/", "/a/", * "/a/b/", "//a/b/", "a//b/" and "a" are examples of strings that are * not relative dirs. + * + * Returns: %TRUE if @string is a relative dir **/ gboolean dconf_is_rel_dir (const gchar *string, diff --git a/common/dconf-paths.h b/common/dconf-paths.h index fa4d1e9..48e2182 100644 --- a/common/dconf-paths.h +++ b/common/dconf-paths.h @@ -32,7 +32,7 @@ gboolean dconf_is_key (const g gboolean dconf_is_dir (const gchar *string, GError **error); -gboolean dconf_is_rel (const gchar *string, +gboolean dconf_is_rel_path (const gchar *string, GError **error); gboolean dconf_is_rel_key (const gchar *string, GError **error); diff --git a/docs/Makefile.am b/docs/Makefile.am index cf13ffc..2f83c10 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -12,15 +12,3 @@ MKDB_OPTIONS = --output-format=xml INCLUDES = $(gio_CFLAGS) GTKDOC_LIBS = $(gio_LIBS) -L../client -ldconf -Wl,-rpath=../client - -IGNORE_HFILES = \ - dconf-engine.h \ - dconf-shmdir.h \ - dconf-resetlist.h \ - dconf-readtype.h \ - dconf-rebuilder.h \ - gvdb-builder.h \ - gvdb-reader.h \ - gvdb-format.h - - diff --git a/docs/dconf-docs.xml b/docs/dconf-docs.xml index 31df0b3..0def819 100644 --- a/docs/dconf-docs.xml +++ b/docs/dconf-docs.xml @@ -12,18 +12,21 @@ <chapter> <title>DConf Client API</title> <xi:include href='xml/paths.xml'/> + <xi:include href='xml/changeset.xml'/> <xi:include href='xml/client.xml'/> </chapter> <chapter id='object-tree'> <title>Object Hierarchy</title> <xi:include href='xml/tree_index.sgml'/> + <xi:include href='xml/object_index.sgml'/> </chapter> <index id='api-index-full'> <title>API Index</title> <xi:include href='xml/api-index-full.xml'><xi:fallback /></xi:include> + <xi:include href='xml/api-index-deprecated.xml'><xi:fallback /></xi:include> </index> - <xi:include href='xml/annotation-glossary.xml'><xi:fallback /></xi:include> + <xi:include href='xml/annotation-glossary.xml'/> </book> diff --git a/docs/dconf-sections.txt b/docs/dconf-sections.txt index 7867ddf..693ecbc 100644 --- a/docs/dconf-sections.txt +++ b/docs/dconf-sections.txt @@ -1,23 +1,18 @@ <SECTION> <FILE>client</FILE> DConfClient -DConfWatchFunc dconf_client_new dconf_client_read -dconf_client_read_default -dconf_client_read_no_default dconf_client_list dconf_client_is_writable -dconf_client_write -dconf_client_write_async -dconf_client_write_finish -dconf_client_write_many -dconf_client_watch -dconf_client_watch_async -dconf_client_watch_finish -dconf_client_unwatch -dconf_client_unwatch_async -dconf_client_unwatch_finish +dconf_client_write_fast +dconf_client_write_sync +dconf_client_change_fast +dconf_client_change_sync +dconf_client_watch_fast +dconf_client_watch_sync +dconf_client_unwatch_fast +dconf_client_unwatch_sync <SUBSECTION Standard> DConfClientClass DCONF_CLIENT @@ -31,7 +26,24 @@ dconf_client_get_type dconf_is_dir dconf_is_key dconf_is_path -dconf_is_rel +dconf_is_rel_path dconf_is_rel_dir dconf_is_rel_key </SECTION> + +<SECTION> +<FILE>changeset</FILE> +DConfChangeset +DConfChangesetPredicate +dconf_changeset_all +dconf_changeset_describe +dconf_changeset_deserialise +dconf_changeset_get +dconf_changeset_is_similar_to +dconf_changeset_new +dconf_changeset_new_write +dconf_changeset_ref +dconf_changeset_serialise +dconf_changeset_set +dconf_changeset_unref +</SECTION> diff --git a/tests/paths.c b/tests/paths.c index 57eede2..5774333 100644 --- a/tests/paths.c +++ b/tests/paths.c @@ -76,12 +76,12 @@ test_paths (void) const gchar *string = cases[i].string; guint flags; - flags = (dconf_is_path (string, NULL) ? 001 : 000) | - (dconf_is_key (string, NULL) ? 002 : 000) | - (dconf_is_dir (string, NULL) ? 004 : 000) | - (dconf_is_rel (string, NULL) ? 010 : 000) | - (dconf_is_rel_key (string, NULL) ? 020 : 000) | - (dconf_is_rel_dir (string, NULL) ? 040 : 000); + flags = (dconf_is_path (string, NULL) ? 001 : 000) | + (dconf_is_key (string, NULL) ? 002 : 000) | + (dconf_is_dir (string, NULL) ? 004 : 000) | + (dconf_is_rel_path (string, NULL) ? 010 : 000) | + (dconf_is_rel_key (string, NULL) ? 020 : 000) | + (dconf_is_rel_dir (string, NULL) ? 040 : 000); g_assert_cmphex (flags, ==, cases[i].flags); } |