[glib/gdbus-merge] Fill out the export section of the migration guide

[Matthias Clasen <matthiasc src gnome org>]

commit 2d75583fb2a8fdb71b9ee880dc0cf4605ab7bc6c
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu May 13 01:04:29 2010 -0400

    Fill out the export section of the migration guide

 docs/reference/gio/migrating-gdbus.xml |   66 ++++++++++++++++++++++++++++++++
 gio/tests/gdbus-example-export.c       |    6 ++-
 2 files changed, 70 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gio/migrating-gdbus.xml b/docs/reference/gio/migrating-gdbus.xml
index 48a87fc..14e70b7 100644
--- a/docs/reference/gio/migrating-gdbus.xml
+++ b/docs/reference/gio/migrating-gdbus.xml
@@ -287,6 +287,72 @@ on_proxy_appeared (GDBusConnection *connection,
 
   <section>
     <title>Exporting objects</title>
+
+    <para>
+      With dbus-glib, exporting an object over D-Bus works by generating
+      a bunch of glue code from your introspection XML with
+      <command>dbus-binding-tool</command>. The glue code gets included in
+      your source, and you need to call
+      <informalexample><programlisting>
+  dbus_g_object_type_install_info (TYPE_MYOBJECT,
+                                   &amp;dbus_glib_myobject_object_info);
+      </programlisting></informalexample>
+      in your class_init() function to tell dbus-glib about your type.
+      To actually export an instance, you call
+      <informalexample><programlisting>
+  dbus_g_connection_register_g_object (system_bus_connection,
+                                       my_object_path,
+                                       G_OBJECT (my_object));
+      </programlisting></informalexample>
+
+    </para>
+    <para>
+      The GDBus way of exporting an object works by embedding the
+      introspection XML in the source, creating introspection data
+      structures from it with g_dbus_node_info_new_for_xml(), and
+      passing that along when you register the object:
+      <informalexample><programlisting><![CDATA[
+
+  static const gchar introspection_xml[] =
+    "<node>"
+    "  <interface name='org.gtk.GDBus.TestPeerInterface'>"
+    "    <method name='HelloWorld'>"
+    "      <arg type='s' name='greeting' direction='in'/>"
+    "      <arg type='s' name='response' direction='out'/>"
+    "    </method>"
+    "  </interface>"
+    "</node>";
+
+  /* parse introspection data */
+  introspection_data = g_dbus_node_info_new_for_xml (introspection_xml, NULL);
+
+  /
+  id = g_dbus_connection_register_object (connection,
+                                          "/org/gtk/GDBus/TestObject",
+                                          "org.gtk.GDBus.TestPeerInterface",
+                                          introspection_data->interfaces[0],
+                                          &interface_vtable,
+                                          NULL,  /* user_data */
+                                          NULL,  /* user_data_free_func */
+                                          NULL); /* GError** */
+
+]]>
+    </programlisting></informalexample>
+    </para>
+    <para>
+      The actual implementation of the exported object is done by specifying
+      a #GDBusInterfaceVTable that has method_call(), get_property() and
+      set_property() methods. There is no direct support beyond that for
+      exporting #GObjects, so there is quite a bit of manual work involved,
+      as you can see in the following example.
+    </para>
+    <para>
+      Since the VTable methods don't have any direct #GObject support, we
+      pass the exported object as @user_data. Also note that we have to handle
+      the emission of the PropertiesChanged signal ourselves, by connecting
+      to ::notify.
+    </para>
+     <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
   </section>
 
 </chapter>
diff --git a/gio/tests/gdbus-example-export.c b/gio/tests/gdbus-example-export.c
index 5965ed8..0f222ce 100644
--- a/gio/tests/gdbus-example-export.c
+++ b/gio/tests/gdbus-example-export.c
@@ -1,7 +1,7 @@
 #include <gio/gio.h>
 #include <stdlib.h>
 
-* ---------------------------------------------------------------------------------------------------- */
+/* ---------------------------------------------------------------------------------------------------- */
 
 /* The object we want to export */
 typedef struct _MyObjectClass MyObjectClass;
@@ -129,6 +129,8 @@ my_object_change_count (MyObject *myobj,
   g_object_notify (G_OBJECT (myobj), "count");
 }
 
+/* ---------------------------------------------------------------------------------------------------- */
+
 static GDBusNodeInfo *introspection_data = NULL;
 
 /* Introspection data for the service we are exporting */
@@ -247,7 +249,7 @@ send_property_change (GObject         *obj,
   g_dbus_connection_emit_signal (connection,
                                  NULL,
                                  "/org/myorg/MyObject",
-                                 "org.myorg.MyObject",
+                                 "org.freedesktop.DBus.Properties",
                                  "PropertiesChanged",
                                  g_variant_new ("(sa{sv})",
                                                 "org.myorg.MyObject",