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 /common | |
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 'common')
-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 |
4 files changed, 208 insertions, 97 deletions
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); |