[dconf/wip/reorg] big docs cleanup
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [dconf/wip/reorg] big docs cleanup
- Date: Tue, 10 Jul 2012 13:55:34 +0000 (UTC)
commit 1f08d55b68740d917bbaf5c2c6ca3dcb81c396e3
Author: Ryan Lortie <desrt desrt ca>
Date: Tue Jul 10 09:30:24 2012 -0400
big docs cleanup
We're now back at 100% docs coverage with no warnings.
client/dconf-client.c | 276 ++++++++++++++++++++++++++++++++++++++++++++++
client/extra-docs.c | 89 ---------------
common/dconf-changeset.c | 231 ++++++++++++++++++++++++++++-----------
common/dconf-changeset.h | 48 ++++----
common/dconf-paths.c | 24 +++--
common/dconf-paths.h | 2 +-
docs/Makefile.am | 12 --
docs/dconf-docs.xml | 5 +-
docs/dconf-sections.txt | 40 +++++---
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/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);
}
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
