[dconf] More cleanups and gtk-doc fill-in
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [dconf] More cleanups and gtk-doc fill-in
- Date: Wed, 4 Aug 2010 01:03:53 +0000 (UTC)
commit 4f72d7e55ac02f0d3c0a5a73b415578e6c68ffa7
Author: Ryan Lortie <desrt desrt ca>
Date: Tue Aug 3 20:58:35 2010 -0400
More cleanups and gtk-doc fill-in
client/.gitignore | 2 +-
client/Makefile.am | 2 +-
client/dconf-client.h | 27 ++++---
client/dconf-client.vala | 153 +++++++++++++++++++++++++++++++++++---
client/engine.vapi | 2 +
client/extra-docs.c | 89 ++++++++++++++++++++++
common/dconf-paths.c | 14 ++++
docs/dconf-docs.xml | 2 +-
docs/dconf-sections.txt | 6 +-
engine/dconf-engine.c | 7 +--
engine/dconf-engine.h | 4 +-
gsettings/dconfsettingsbackend.c | 7 +--
12 files changed, 268 insertions(+), 47 deletions(-)
---
diff --git a/client/.gitignore b/client/.gitignore
index 241653e..bb66dd5 100644
--- a/client/.gitignore
+++ b/client/.gitignore
@@ -1,5 +1,5 @@
dconf.vapi
-*.c
+dconf-client.c
*.stamp
*.deps
libdconf.so
diff --git a/client/Makefile.am b/client/Makefile.am
index 9d716ce..c661a52 100644
--- a/client/Makefile.am
+++ b/client/Makefile.am
@@ -42,7 +42,7 @@ libdconf_so_0_SOURCES = \
dconf-client.vala engine.vapi
libdconf_so_0_VALAFLAGS = --library dconf --pkg=gio-2.0
-EXTRA_DIST = dconf.vapi
+EXTRA_DIST = dconf.vapi extra-docs.c
dconf.vapi: libdconf.so.0
dconf.deps:
diff --git a/client/dconf-client.h b/client/dconf-client.h
index 9dca7b2..019bb38 100644
--- a/client/dconf-client.h
+++ b/client/dconf-client.h
@@ -59,8 +59,7 @@ gchar ** dconf_client_list (DConfCl
gint *length);
gboolean dconf_client_is_writable (DConfClient *client,
- const gchar *key,
- GError **error);
+ const gchar *key);
gboolean dconf_client_write (DConfClient *client,
const gchar *key,
@@ -95,32 +94,34 @@ gboolean dconf_client_set_locked_finish (DConfCl
GError **error);
gboolean dconf_client_write_many (DConfClient *client,
- const gchar *prefix,
- const gchar * const *keys,
+ const gchar *dir,
+ const gchar * const *rels,
GVariant **values,
- gsize n_values,
+ gint n_values,
gchar **tag,
GCancellable *cancellable,
GError **error);
+
+/* write_many_async currently disabled due to missing Vala functionality
void dconf_client_write_many_async (DConfClient *client,
- const gchar *prefix,
- const gchar * const *keys,
+ const gchar *dir,
+ const gchar * const *rels,
GVariant **values,
- gsize n_values,
+ gint n_values,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean dconf_client_write_many_finish (DConfClient *client,
GAsyncResult *result,
gchar **tag,
- GError **error);
+ GError **error);*/
gboolean dconf_client_watch (DConfClient *client,
- const gchar *name,
+ const gchar *path,
GCancellable *cancellable,
GError **error);
void dconf_client_watch_async (DConfClient *client,
- const gchar *name,
+ const gchar *path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
@@ -128,11 +129,11 @@ gboolean dconf_client_watch_finish (DConfCl
GAsyncResult *result,
GError **error);
gboolean dconf_client_unwatch (DConfClient *client,
- const gchar *name,
+ const gchar *path,
GCancellable *cancellable,
GError **error);
void dconf_client_unwatch_async (DConfClient *client,
- const gchar *name,
+ const gchar *path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
diff --git a/client/dconf-client.vala b/client/dconf-client.vala
index b929241..2be8be9 100644
--- a/client/dconf-client.vala
+++ b/client/dconf-client.vala
@@ -59,6 +59,22 @@ namespace DConf {
}
/**
+ * dconf_client_is_writable:
+ * @client: a #DConfClient
+ * @key: a dconf key
+ * Returns: %TRUE is @key is writable
+ *
+ * Checks if @key is writable (ie: the key has no mandatory setting).
+ *
+ * This call does not verify that writing to the key will actually be successful. It only checks for
+ * the existence of mandatory keys/locks that might affect writing to @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.
+ **/
+ public bool is_writable (string key) {
+ return engine.is_writable (key);
+ }
+
+ /**
* dconf_client_write:
* @client: a #DConfClient
* @key: a dconf key
@@ -66,7 +82,7 @@ namespace DConf {
* @tag: (out) (allow-none): the tag from this write
* @cancellable: a #GCancellable, or %NULL
* @error: a pointer to a #GError, or %NULL
- * @returns: %TRUE if the write is successful
+ * Returns: %TRUE if the write is successful
*
* Write a value to the given @key, or reset @key to its default value.
*
@@ -95,7 +111,7 @@ namespace DConf {
* @callback: the function to call when complete
* @user_data: the user data for @callback
*
- * Writes a value to the given @key, or reset @key to its default value.
+ * Write a value to the given @key, or reset @key to its default value.
*
* This is the asynchronous version of dconf_client_write(). You should call
* dconf_client_write_finish() from @callback to collect the result.
@@ -106,13 +122,65 @@ namespace DConf {
}
/**
+ * dconf_client_write_many:
+ * @client: a #DConfClient
+ * @dir: the dconf directory under which to make the writes
+ * @rels: a %NULL-terminated array of relative keys
+ * @values: an array of possibly-%NULL #GVariant pointers
+ * @n_values: the length of @values, which must be equal to the length of @rels
+ * @tag: (out) (allow-none): the tag from this write
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a #GError, or %NULL
+ * Returns: %TRUE if the write is successful
+ *
+ * Write multiple values at once.
+ *
+ * For each pair of items from @rels and @values, the value is written to the result of concatenating
+ * @dir with the relative path. As with dconf_client_write(), if a given value is %NULL then the effect
+ * is that the specified key is reset.
+ *
+ * If @tag is non-%NULL then it is set to the unique tag associated with this write. This is the same
+ * tag that appears in change notifications.
+ **/
+ public bool write_many (string dir, [CCode (array_length = false, array_null_terminated = true)] string[] rels, Variant?[] values, out string? tag = null, Cancellable? cancellable = null) throws Error {
+ if (&tag == null) { /* bgo #591673 */
+ string junk;
+ call_sync (engine.write_many (dir, rels, values), out junk, cancellable);
+ } else {
+ call_sync (engine.write_many (dir, rels, values), out tag, cancellable);
+ }
+ return true;
+ }
+
+ /*< disabled due to Vala compiler bugs >
+ * dconf_client_write_many_async:
+ * @client: a #DConfClient
+ * @dir: the dconf directory under which to make the writes
+ * @rels: a %NULL-terminated array of relative keys
+ * @values: an array of possibly-%NULL #GVariant pointers
+ * @n_values: the length of @values, which must be equal to the length of @rels
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback to call when finished
+ * @user_data: a pointer to pass as the last argument to @callback
+ *
+ * Write multiple values at once.
+ *
+ * This is the asynchronous version of dconf_client_write_many(). You should call
+ * dconf_client_write_many_finish() from @callback to collect the result.
+ *
+ public async bool write_many_async (string dir, [CCode (array_length = false, array_null_terminated = true)] string[] rels, Variant?[] values, out string? tag = null, Cancellable? cancellable = null) throws Error {
+ yield call_async (engine.write_many (dir, rels, values), out tag, cancellable);
+ return true;
+ }*/
+
+ /**
* dconf_client_set_locked:
* @client: a #DConfClient
* @path: a dconf path
* @locked: %TRUE to lock, %FALSE to unlock
* @cancellable: a #GCancellable, or %NULL
* @error: a pointer to a #GError, or %NULL
- * @returns: %TRUE if setting the lock was successful
+ * Returns: %TRUE if setting the lock was successful
*
* Marks a dconf path as being locked.
*
@@ -140,7 +208,7 @@ namespace DConf {
* Marks a dconf path as being locked.
*
* This is the asynchronous version of dconf_client_set_locked(). You should call
- * dconf_client_write_finish() from @callback to collect the result.
+ * dconf_client_set_locked_finish() from @callback to collect the result.
**/
public async bool set_locked_async (string key, bool locked, Cancellable? cancellable = null) throws Error {
yield call_async (engine.set_locked (key, locked), null, cancellable);
@@ -148,12 +216,13 @@ namespace DConf {
}
/**
+ * dconf_client_read:
* @client: a #DConfClient
* @key: a valid dconf key
- * @returns: the value corresponding to @key, or %NULL if there is none
+ * Returns: the value corresponding to @key, or %NULL if there is none
*
* Reads the value named by @key from dconf. If no such value exists, %NULL is returned.
- */
+ **/
public Variant? read (string key) {
return engine.read (key);
}
@@ -162,7 +231,7 @@ namespace DConf {
* dconf_client_read_default:
* @client: a #DConfClient
* @key: a valid dconf key
- * @returns: the default value corresponding to @key, or %NULL if there is none
+ * Returns: the default value corresponding to @key, or %NULL if there is none
*
* Reads the value named by @key from any existing default/mandatory databases but ignoring any value
* set by the user. The result is as if the named key had just been reset.
@@ -175,7 +244,7 @@ namespace DConf {
* dconf_client_read_no_default:
* @client: a #DConfClient
* @key: a valid dconf key
- * @returns: the user value corresponding to @key, or %NULL if there is none
+ * Returns: the user value corresponding to @key, or %NULL if there is none
*
* Reads the value named by @key as set by the user, ignoring any default/mandatory databases. Normal
* applications will never want to do this, but it may be useful for administrative or configuration
@@ -195,7 +264,7 @@ namespace DConf {
* @client: a #DConfClient
* @dir: a dconf dir
* @length: the number of items that were returned
- * @returns: (array length=length): the paths located directly below @dir
+ * Returns: (array length=length): the paths located directly below @dir
*
* Lists the keys and dirs located directly below @dir.
*
@@ -205,21 +274,81 @@ namespace DConf {
return engine.list (dir);
}
- public bool watch (string name, Cancellable? cancellable = null) throws GLib.Error {
- call_sync (engine.watch (name), null, cancellable);
+ /**
+ * dconf_client_watch:
+ * @client: a #DConfClient
+ * @path: a dconf path
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
+ * Returns: %TRUE on success, else %FALSE with @error set
+ *
+ * Requests monitoring of a portion of the dconf database.
+ *
+ * If @path is a key (ie: doesn't end with a slash) then a single key is monitored for changes. If
+ * @path is a dir (ie: sending with a slash) then all keys that have @path as a prefix are monitored.
+ *
+ * This function blocks until the watch has definitely been established with the bus daemon. If you
+ * would like a non-blocking version of this call, see dconf_client_watch_async().
+ **/
+ public bool watch (string path, Cancellable? cancellable = null) throws GLib.Error {
+ call_sync (engine.watch (path), null, cancellable);
return true;
}
+ /**
+ * dconf_client_watch_async:
+ * @client: a #DConfClient
+ * @path: a dconf path
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback to call when finished
+ * @user_data: a pointer to pass as the last argument to @callback
+ *
+ * Requests monitoring of a portion of the dconf database.
+ *
+ * This is the asynchronous version of dconf_client_watch(). You should call
+ * dconf_client_watch_finish() from @callback to collect the result.
+ **/
public async bool watch_async (string name, Cancellable? cancellable = null) throws GLib.Error {
yield call_async (engine.watch (name), null, cancellable);
return true;
}
+ /**
+ * dconf_client_unwatch:
+ * @client: a #DConfClient
+ * @path: a dconf path
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
+ * Returns: %TRUE on success, else %FALSE with @error set
+ *
+ * Cancels the effect of a previous call to dconf_client_watch().
+ *
+ * If the same path has been watched multiple times then only one of the watches is cancelled and the
+ * net effect is that the path is still watched.
+ *
+ * This function blocks until the watch has definitely been removed from the bus daemon. It is possible
+ * that notifications in transit will arrive after this call returns. For an asynchronous version of
+ * this call, see dconf_client_unwatch_async().
+ **/
public bool unwatch (string name, Cancellable? cancellable = null) throws GLib.Error {
call_sync (engine.unwatch (name), null, cancellable);
return true;
}
+ /**
+ * dconf_client_unwatch_async:
+ * @client: a #DConfClient
+ * @path: a dconf path
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback to call when finished
+ * @user_data: a pointer to pass as the last argument to @callback
+ *
+ * Cancels the effect of a previous call to dconf_client_watch().
+ *
+ * This is the asynchronous version of dconf_client_unwatch(). You should call
+ * dconf_client_unwatch_finish() from @callback to collect the result. No additional notifications will
+ * be delivered for this watch after @callback is called.
+ **/
public async bool unwatch_async (string name, Cancellable? cancellable = null) throws GLib.Error {
yield call_async (engine.unwatch (name), null, cancellable);
return true;
@@ -242,7 +371,7 @@ namespace DConf {
* @watch_func: the function to call when changes occur
* @user_data: the user_data to pass to @watch_func
* @notify: the function to free @user_data when no longer needed
- * @returns: a new #DConfClient
+ * Returns: a new #DConfClient
*
* Creates a new #DConfClient for the given context.
*
diff --git a/client/engine.vapi b/client/engine.vapi
index bf955c5..eb3e7bc 100644
--- a/client/engine.vapi
+++ b/client/engine.vapi
@@ -3,7 +3,9 @@ namespace DConf {
[CCode (cheader_filename = "dconf-engine.h")]
class Engine {
internal Engine (string? profile);
+ internal bool is_writable (string key);
internal EngineMessage write (string key, GLib.Variant? value) throws GLib.Error;
+ internal EngineMessage write_many (string dir, [CCode (array_length = false, array_null_terminated = true, type = "const gchar * const *")] string[] keys, [CCode (array_length = false)] GLib.Variant?[] values) throws GLib.Error;
internal GLib.Variant? read (string key);
internal GLib.Variant? read_default (string key);
internal GLib.Variant? read_no_default (string key);
diff --git a/client/extra-docs.c b/client/extra-docs.c
new file mode 100644
index 0000000..2f12951
--- /dev/null
+++ b/client/extra-docs.c
@@ -0,0 +1,89 @@
+/* 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-paths.c b/common/dconf-paths.c
index 8a63704..1278d64 100644
--- a/common/dconf-paths.c
+++ b/common/dconf-paths.c
@@ -22,6 +22,20 @@
#include "dconf-paths.h"
+/**
+ * SECTION:paths
+ * @title: DConf Paths
+ * @short_description: utility functions to validate dconf paths
+ *
+ * Various places in the dconf API speak of "paths", "keys", "dirs" and
+ * relative versions of each of these. This file contains functions to
+ * check if a given string is a valid member of each of these classes
+ * and to report errors when a string is not.
+ *
+ * See each function in this section for a precise description of what
+ * makes a string a valid member of a given class.
+ **/
+
#define vars gchar c, l
#define DCONF_ERROR 0
diff --git a/docs/dconf-docs.xml b/docs/dconf-docs.xml
index 4a8745c..31df0b3 100644
--- a/docs/dconf-docs.xml
+++ b/docs/dconf-docs.xml
@@ -12,7 +12,7 @@
<chapter>
<title>DConf Client API</title>
<xi:include href='xml/paths.xml'/>
- <xi:include href='xml/dconf-client.xml'/>
+ <xi:include href='xml/client.xml'/>
</chapter>
<chapter id='object-tree'>
diff --git a/docs/dconf-sections.txt b/docs/dconf-sections.txt
index ae4b1b2..475522f 100644
--- a/docs/dconf-sections.txt
+++ b/docs/dconf-sections.txt
@@ -1,6 +1,5 @@
<SECTION>
-<FILE>dconf-client</FILE>
-DConfClientClass
+<FILE>client</FILE>
DConfClient
DConfWatchFunc
dconf_client_new
@@ -16,8 +15,6 @@ dconf_client_set_locked
dconf_client_set_locked_async
dconf_client_set_locked_finish
dconf_client_write_many
-dconf_client_write_many_async
-dconf_client_write_many_finish
dconf_client_watch
dconf_client_watch_async
dconf_client_watch_finish
@@ -25,6 +22,7 @@ dconf_client_unwatch
dconf_client_unwatch_async
dconf_client_unwatch_finish
<SUBSECTION Standard>
+DConfClientClass
DCONF_CLIENT
DCONF_IS_CLIENT
DCONF_TYPE_CLIENT
diff --git a/engine/dconf-engine.c b/engine/dconf-engine.c
index 4960c4c..cf57431 100644
--- a/engine/dconf-engine.c
+++ b/engine/dconf-engine.c
@@ -466,13 +466,8 @@ dconf_engine_unwatch (DConfEngine *engine,
gboolean
dconf_engine_is_writable (DConfEngine *engine,
- const gchar *name,
- DConfEngineMessage *dcem,
- GError **error)
+ const gchar *name)
{
- dcem->bus_type = 'e';
- dcem->body = g_variant_new ("()");
-
return TRUE;
}
diff --git a/engine/dconf-engine.h b/engine/dconf-engine.h
index 5cc2a09..229c1a1 100644
--- a/engine/dconf-engine.h
+++ b/engine/dconf-engine.h
@@ -70,9 +70,7 @@ void dconf_engine_get_service_info (DConfEn
const gchar **destination,
const gchar **object_path);
gboolean dconf_engine_is_writable (DConfEngine *engine,
- const gchar *name,
- DConfEngineMessage *message,
- GError **error);
+ const gchar *name);
gboolean dconf_engine_write (DConfEngine *engine,
const gchar *key,
GVariant *value,
diff --git a/gsettings/dconfsettingsbackend.c b/gsettings/dconfsettingsbackend.c
index 121d52f..42db04e 100644
--- a/gsettings/dconfsettingsbackend.c
+++ b/gsettings/dconfsettingsbackend.c
@@ -495,13 +495,8 @@ dconf_settings_backend_get_writable (GSettingsBackend *backend,
const gchar *name)
{
DConfSettingsBackend *dcsb = (DConfSettingsBackend *) backend;
- DConfEngineMessage dcem;
- GDBusConnection *bus;
-
- if (!dconf_engine_is_writable (dcsb->engine, name, &dcem, NULL))
- return FALSE;
- return dconf_settings_backend_get_bus (dcsb, &bus, &dcem);
+ return dconf_engine_is_writable (dcsb->engine, name);
}
static void
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
