[dconf/wip/reorg: 463/523] Add a HACKING

[Ryan Lortie <ryanl src gnome org>]

commit 6a675a5bdef5949e2397b0d5ca9d0c8a36ccedfd
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Jul 1 18:46:23 2012 -0400

    Add a HACKING

 HACKING               |   80 +++++++++++++++
 client/.gitignore     |    4 -
 client/dconf-client.c |  264 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 344 insertions(+), 4 deletions(-)
---
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..64a6984
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,80 @@
+dconf is split into a large number of small modules.  This is required
+because of the client/server architecture as well as the wide variety of
+situations that dconf is used in on the client side.
+
+gvdb/:
+
+  This code implements the GVDB file format used for the on-disk
+  database.  GVDB is shared with a number of other users and lives in a
+  separate 'gvdb' module on git.gnome.org.
+
+  Changes should never be made to this directory.  Instead, they should
+  be made against the 'gvdb' module and merged using git.
+
+  The code is split into a reader and a writer (builder).
+
+  This directory doesn't produce any libraries.  The source files are
+  included into other libraries and executables by direct inclusion of
+  these source files into the Makefiles of other directories.
+
+common/:
+
+  Sources in this directory are used in both the dconf-service and
+  client-side library implementations.
+
+  This directory produces two libraries: libdconf-common.a and
+  libdconf-common-shared.a.  They are exactly the same, except that
+  libdconf-common-shared.a was compiled with -fPIC.
+
+engine/:
+
+  This directory contains most of the core logic for implementing the
+  client-side of dconf.
+
+  The engine code requires (but does not contain) glue code for speaking
+  to D-Bus.  All users of the engine must therefore include a module
+  that implements this glue.
+
+  This directory produces one library: libdconf-engine.a.  This library
+  includes the gvdb-reader.
+
+gdbus/:
+
+  This directory contains the glue code for dconf over GDBus.
+
+  This directory produces one library: libdconf-gdbus.a.
+
+client/:
+
+  This is the standard GObject client-side library used for direct access to
+  dconf.  It uses the GDBus glue from the gdbus/ directory above.
+
+  This directory produces the libdconf.so shared library.
+
+gsettings/:
+
+  This is the GSettings backend for dconf.  It also uses GDBus.
+
+  This directory produces the libdconfsettings.so GIOModule.
+
+dbus-1/:
+
+  This directory contains a client-side library based on libdbus-1.  It
+  also contains the D-Bus glue code for libdbus-1 (since it is the only
+  client-side library that is using it).
+
+  This directory produces the libdconf-dbus-1.so shared library.
+
+bin/:
+
+  This is the 'dconf' commandline tool.  It uses the library from
+  client/ above.
+
+editor/:
+
+  This is the graphical dconf-editor.  It also uses the client/ library.
+
+service/:
+
+  This is the dconf-service required for any client side library to do
+  writes.
diff --git a/client/.gitignore b/client/.gitignore
index 6b4b55c..8cad688 100644
--- a/client/.gitignore
+++ b/client/.gitignore
@@ -1,7 +1,3 @@
-dconf.vapi
-dconf-client.c
-*.stamp
-*.deps
 libdconf.so
 libdconf.so.0
 libdconf.so.0.0.0
diff --git a/client/dconf-client.c b/client/dconf-client.c
new file mode 100644
index 0000000..1300269
--- /dev/null
+++ b/client/dconf-client.c
@@ -0,0 +1,264 @@
+/*
+ * Copyright  2010 Codethink Limited
+ * Copyright  2012 Canonical Limited
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the licence, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Ryan Lortie <desrt desrt ca>
+ */
+
+#include "dconf-client.h"
+
+#include "dconf-engine.h"
+
+struct _DConfClient
+{
+  GObject parent_class;
+
+  DConfEngine  *engine;
+  GMainContext *context;
+};
+
+G_DEFINE_TYPE (DConfClient, dconf_client, G_TYPE_OBJECT)
+
+enum
+{
+  SIGNAL_CHANGED,
+  N_SIGNALS
+};
+
+static guint dconf_client_signals[N_SIGNALS];
+
+static void
+dconf_client_finalize (GObject *object)
+{
+  DConfClient *client = DCONF_CLIENT (object);
+
+  dconf_engine_free (client->engine);
+  g_main_context_unref (client->context);
+
+  G_OBJECT_CLASS (dconf_client_parent_class)
+    ->finalize (object);
+}
+
+static void
+dconf_client_init (DConfClient *client)
+{
+}
+
+static void
+dconf_client_class_init (DConfClientClass *class)
+{
+  class->finalize = dconf_client_finalize;
+
+  dconf_client_signals[SIGNAL_CHANGED] =
+    g_signal_new ("changed", DCONF_TYPE_CLIENT, G_SIGNAL_RUN_FIRST,
+                  0, NULL, NULL, NULL, G_TYPE_NONE, 2,
+                  G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE,
+                  G_TYPE_STRV | G_SIGNAL_TYPE_STATIC_SCOPE);
+}
+
+typedef struct
+{
+  DConfClient  *client;
+  gchar        *prefix;
+  gchar       **changes;
+} DConfClientChange;
+
+static gboolean
+dconf_engine_emit_changed (gpointer user_data)
+{
+  DConfClientChange *change = user_data;
+
+  g_signal_emit (change->client, dconf_client_signals[SIGNAL_CHANGED], 0, change->prefix, change->changes);
+
+  g_free (change->prefix);
+  g_strfreev (change->changes);
+  g_object_unref (change->client);
+  g_slice_free (DConfClientChange, change);
+
+  return G_SOURCE_REMOVE;
+}
+
+void
+dconf_engine_change_notify (DConfEngine         *engine,
+                            const gchar         *prefix,
+                            const gchar * const *changes,
+                            gpointer             user_data)
+{
+  DConfClient *client = user_data;
+  DConfClientChange *change;
+
+  g_return_if_fail (DCONF_IS_CLIENT (client));
+
+  change = g_slice_new (DConfClientChange);
+  change->prefix = g_strdup (prefix);
+  change->changes = g_strdupv ((gchar **) changes);
+  change->client = g_object_ref (client);
+
+  g_main_context_invoke (client->context,
+                         dconf_engine_emit_changed,
+                         change);
+}
+
+GVariant *
+dconf_client_read (DConfClient *client,
+                   const gchar *key)
+{
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), NULL);
+
+  return dconf_engine_read (client->engine, NULL, key);
+}
+
+gchar **
+dconf_client_list (DConfClient *client,
+                   const gchar *dir)
+{
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), NULL);
+
+  return NULL;
+
+  /*: return dconf_engine_list (client->engine, NULL, dir); */
+}
+
+gboolean
+dconf_client_is_writable (DConfClient *client,
+                          const gchar *key)
+{
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), FALSE);
+
+  return dconf_engine_is_writable (client->engine, key);
+}
+
+static DConfChangeset *
+dconf_client_make_simple_change (const gchar *key,
+                                 GVariant    *value)
+{
+  DConfChangeset *changeset;
+
+  changeset = dconf_changeset_new ();
+  dconf_changeset_set (changeset, key, value);
+
+  return changeset;
+}
+
+gboolean
+dconf_client_write_fast (DConfClient  *client,
+                         const gchar  *key,
+                         GVariant     *value,
+                         GError      **error)
+{
+  DConfChangeset *changeset;
+  gboolean success;
+
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), FALSE);
+
+  changeset = dconf_client_make_simple_change (key, value);
+  success = dconf_engine_change_fast (client->engine, changeset, error);
+  dconf_changeset_unref (changeset);
+
+  return success;
+}
+
+gboolean
+dconf_client_write_sync (DConfClient   *client,
+                         const gchar   *key,
+                         GVariant      *value,
+                         gchar        **tag,
+                         GCancellable  *cancellable,
+                         GError       **error)
+{
+  DConfChangeset *changeset;
+  gboolean success;
+
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), FALSE);
+
+  changeset = dconf_client_make_simple_change (key, value);
+  success = dconf_engine_change_sync (client->engine, changeset, tag, error);
+  dconf_changeset_unref (changeset);
+
+  return success;
+}
+
+gboolean
+dconf_client_change_fast (DConfClient     *client,
+                          DConfChangeset  *changeset,
+                          GError         **error)
+{
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), FALSE);
+
+  return dconf_engine_change_fast (client->engine, changeset, error);
+}
+
+gboolean
+dconf_client_change_sync (DConfClient     *client,
+                          DConfChangeset  *changeset,
+                          gchar          **tag,
+                          GCancellable    *cancellable,
+                          GError         **error)
+{
+  g_return_val_if_fail (DCONF_IS_CLIENT (client), FALSE);
+
+  return dconf_engine_change_sync (client->engine, changeset, tag, error);
+}
+
+void
+dconf_client_watch_fast (DConfClient *client,
+                         const gchar *path)
+{
+  g_return_if_fail (DCONF_IS_CLIENT (client));
+
+  dconf_engine_watch_fast (client->engine, path);
+}
+
+void
+dconf_client_watch_sync (DConfClient   *client,
+                         const gchar   *path)
+{
+  g_return_if_fail (DCONF_IS_CLIENT (client));
+
+  dconf_engine_watch_sync (client->engine, path);
+}
+
+void
+dconf_client_unwatch_fast (DConfClient *client,
+                           const gchar *path)
+{
+  g_return_if_fail (DCONF_IS_CLIENT (client));
+
+  dconf_engine_unwatch_fast (client->engine, path);
+}
+
+void
+dconf_client_unwatch_sync (DConfClient *client,
+                           const gchar *path)
+{
+  g_return_if_fail (DCONF_IS_CLIENT (client));
+
+  dconf_engine_unwatch_sync (client->engine, path);
+}
+
+DConfClient *
+dconf_client_new (void)
+{
+  DConfClient *client;
+
+  client = g_object_new (DCONF_TYPE_CLIENT, NULL);
+  client->engine = dconf_engine_new (client);
+  client->context = g_main_context_ref_thread_default ();
+
+  return client;
+}