[dconf] simplify API, add gobject-introspection

[Ryan Lortie <ryanl src gnome org>]

commit 5369692701dc4d3194dddb356e6d11517d6aa4a2
Author: Ryan Lortie <desrt desrt ca>
Date:   Fri May 28 00:05:58 2010 -0400

    simplify API, add gobject-introspection

 .gitignore            |    2 +
 bin/dconf.c           |    4 +-
 client/Makefile.am    |   17 ++++++++
 client/dconf-client.c |  104 ++++++++++++++++++++++++++++++++++++++++++++----
 client/dconf-client.h |    9 +++-
 configure.ac          |    1 +
 6 files changed, 123 insertions(+), 14 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index edd1617..fada155 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,8 @@ Makefile
 *.lo
 *.la
 *.pc
+*.gir
+*.typelib
 
 # autofoo stuff here
 compile
diff --git a/bin/dconf.c b/bin/dconf.c
index e6eea16..4cdde3e 100644
--- a/bin/dconf.c
+++ b/bin/dconf.c
@@ -122,7 +122,7 @@ do_sync_command (DConfClient  *client,
       if (!ensure ("key", key, dconf_is_key, error))
         return FALSE;
 
-      value = dconf_client_read (client, key, DCONF_READ_NORMAL);
+      value = dconf_client_read (client, key);
 
       if (value == NULL)
         return TRUE;
@@ -170,7 +170,7 @@ do_sync_command (DConfClient  *client,
       if (!ensure ("dir", dir, dconf_is_dir, error))
         return FALSE;
 
-      list = dconf_client_list (client, dir, NULL, NULL);
+      list = dconf_client_list (client, dir, NULL);
 
       while (*list)
         g_print ("%s\n", *list++);
diff --git a/client/Makefile.am b/client/Makefile.am
index 22b9d30..83d1740 100644
--- a/client/Makefile.am
+++ b/client/Makefile.am
@@ -1,6 +1,15 @@
+include $(INTROSPECTION_MAKEFILE)
+
 AM_CFLAGS = -std=c89 -Wall -Wmissing-prototypes -Wwrite-strings
 INCLUDES = -I$(top_srcdir)/{common,gvdb,engine} $(gio_CFLAGS)
 
+dconf-0.3.gir: libdconf.la
+dconf_0_3_gir_INCLUDES = Gio-2.0
+dconf_0_3_gir_CFLAGS = $(INCLUDES)
+dconf_0_3_gir_LIBS = libdconf.la
+dconf_0_3_gir_FILES = dconf-client.c dconf-client.h ../engine/dconf-resetlist.h
+INTROSPECTION_GIRS = dconf-0.3.gir
+
 lib_LTLIBRARIES = libdconf.la
 
 dconfinclude_HEADERS = \
@@ -16,3 +25,11 @@ libdconf_la_SOURCES = \
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = dconf.pc
+
+girdir = $(datadir)/gir-1.0
+dist_gir_DATA = $(INTROSPECTION_GIRS)
+
+typelibdir = $(libdir)/girepository-1.0
+typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)
+
+CLEANFILES = $(dist_gir_DATA) $(typelib_DATA)
diff --git a/client/dconf-client.c b/client/dconf-client.c
index daf449f..c6e50c1 100644
--- a/client/dconf-client.c
+++ b/client/dconf-client.c
@@ -2,8 +2,6 @@
 #include "dconf-client.h"
 #include <string.h>
 
-typedef GObjectClass DConfClientClass;
-
 struct _DConfClient
 {
   GObject parent_instance;
@@ -183,9 +181,21 @@ dconf_client_init (DConfClient *client)
 static void
 dconf_client_class_init (DConfClientClass *class)
 {
-  class->finalize = dconf_client_finalize;
+  GObjectClass *object_class = G_OBJECT_CLASS (class);
+
+  object_class->finalize = dconf_client_finalize;
 }
 
+/**
+ * dconf_client_new:
+ * @context: the context string (must by %NULL for now)
+ * @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
+ *
+ * Creates a new #DConfClient for the given context.
+ **/
 DConfClient *
 dconf_client_new (const gchar          *context,
                   DConfWatchFunc        watch_func,
@@ -202,12 +212,64 @@ dconf_client_new (const gchar          *context,
   return client;
 }
 
+/**
+ * dconf_client_read:
+ * @client: a #DConfClient
+ * @key: a valid dconf key
+ * @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.
+ **/
 GVariant *
 dconf_client_read (DConfClient   *client,
-                   const gchar   *key,
-                   DConfReadType  type)
+                   const gchar   *key)
+{
+  return dconf_engine_read (client->engine, key, DCONF_READ_NORMAL);
+}
+
+/**
+ * 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
+ *
+ * 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.
+ **/
+GVariant *
+dconf_client_read_default (DConfClient *client,
+                           const gchar *key)
 {
-  return dconf_engine_read (client->engine, key, type);
+  return dconf_engine_read (client->engine, key, DCONF_READ_RESET);
+}
+
+/**
+ * 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
+ *
+ * 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
+ * tweaking utilities to have access to this information.
+ *
+ * Note that in the case of mandatory keys, the result of
+ * dconf_client_read_no_default() with a fallback to
+ * dconf_client_read_default() is not necessarily the same as the result
+ * of a dconf_client_read().  This is because the user may have set a
+ * value before the key became marked as mandatory, in which case this
+ * call will see the user's (otherwise inaccessible) key.
+ **/
+GVariant *
+dconf_client_read_no_default (DConfClient *client,
+                              const gchar *key)
+{
+  return dconf_engine_read (client->engine, key, DCONF_READ_SET);
 }
 
 static gboolean
@@ -248,6 +310,20 @@ dconf_client_call_sync (DConfClient          *client,
   return TRUE;
 }
 
+/**
+ * dconf_client_write:
+ * @client: a #DConfClient
+ * @value (allow-none): a #GVariant, or %NULL
+ * @sequence: (out) (allow-none): the sequence number of this write
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a #GError, or %NULL
+ * @returns: %TRUE if the write is successful
+ *
+ * Write a 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.
+ **/
 gboolean
 dconf_client_write (DConfClient   *client,
                     const gchar   *key,
@@ -291,14 +367,24 @@ dconf_client_write_finish (DConfClient   *client,
                                        sequence, error);
 }
 
-
+/**
+ * dconf_client_list:
+ * @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
+ *
+ * Lists the keys and dirs located directly below @dir.
+ *
+ * You should free the return result with g_strfreev() when it is no
+ * longer needed.
+ **/
 gchar **
 dconf_client_list (DConfClient    *client,
                    const gchar    *prefix,
-                   DConfResetList *resets,
                    gsize          *length)
 {
-  return dconf_engine_list (client->engine, prefix, resets, length);
+  return dconf_engine_list (client->engine, prefix, NULL, length);
 }
 
 gboolean
diff --git a/client/dconf-client.h b/client/dconf-client.h
index 77ec0cb..59bc784 100644
--- a/client/dconf-client.h
+++ b/client/dconf-client.h
@@ -11,6 +11,7 @@ G_BEGIN_DECLS
 #define DCONF_CLIENT(inst)      (G_TYPE_CHECK_INSTANCE_CAST ((inst), DCONF_TYPE_CLIENT, DConfClient))
 #define DCONF_IS_CLIENT(inst)   (G_TYPE_CHECK_INSTANCE_TYPE ((inst), DCONF_TYPE_CLIENT))
 
+typedef GObjectClass DConfClientClass;
 typedef struct _DConfClient DConfClient;
 
 typedef void          (*DConfWatchFunc)                                 (DConfClient          *client,
@@ -25,12 +26,14 @@ DConfClient *           dconf_client_new                                (const g
                                                                          GDestroyNotify        notify);
 
 GVariant *              dconf_client_read                               (DConfClient          *client,
-                                                                         const gchar          *key,
-                                                                         DConfReadType         type);
+                                                                         const gchar          *key);
+GVariant *              dconf_client_read_default                       (DConfClient          *client,
+                                                                         const gchar          *key);
+GVariant *              dconf_client_read_no_default                    (DConfClient          *client,
+                                                                         const gchar          *key);
 
 gchar **                dconf_client_list                               (DConfClient          *client,
                                                                          const gchar          *prefix,
-                                                                         DConfResetList       *resets,
                                                                          gsize                *length);
 
 gboolean                dconf_client_is_writable                        (DConfClient          *client,
diff --git a/configure.ac b/configure.ac
index 50643fa..eaa9ef4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,6 +1,7 @@
 AC_INIT(dconf, 0.3.2)
 AM_INIT_AUTOMAKE
 AM_SILENT_RULES(yes)
+GOBJECT_INTROSPECTION_CHECK([0.6.7])
 AC_PROG_LIBTOOL
 AC_PROG_CC