Spiff up the "Migrating to GDBus" docs a bit

Signed-off-by: David Zeuthen <davidz@redhat.com>

docs/reference/gio/migrating-gdbus.xml

@@ -84,8 +84,8 @@
                g_dbus_proxy_new_for_bus_sync(), also see g_dbus_proxy_new()</entry></row>
           <row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
           <row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
-          <row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object()</entry></row>
+          <row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object() - also see g_dbus_object_manager_server_export()</entry></row>
-          <row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object()</entry></row>
+          <row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object() - also see g_dbus_object_manager_server_unexport()</entry></row>
           <row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
                an object, see g_dbus_connection_register_object()</entry></row>
           <row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_call()</entry></row>
@@ -259,11 +259,15 @@ gdbus-codegen --c-namespace Example 				      \
 ]]></programlisting></informalexample>
       then two files <filename>generated-code.h</filename> and
       <filename>generated-code.c</filename> are
-      generated. Additionally a single XML file
+      generated. Additionally, two XML files
-      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename>
+      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename> and
-      with Docbook XML is generated. For an example of what the docs look
+      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat</filename>
+      with Docbook XML are generated. For an example of what the docs look
       like see <link
-      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Animal">this page</link>.
+      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Animal">the Animal D-Bus interface documentation</link>.
+      and
+      <link
+      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Cat">the Cat D-Bus interface documentation</link>.
     </para>
     <para>
       While the contents of <filename>generated-code.h</filename> and
@@ -283,5 +287,6 @@ gdbus-codegen --c-namespace Example 				      \
   </section>
 
   <xi:include href="../../../../gio/tests/gdbus-example-objectmanager-generated-org.gtk.GDBus.Example.ObjectManager.Animal.xml"/>
+  <xi:include href="../../../../gio/tests/gdbus-example-objectmanager-generated-org.gtk.GDBus.Example.ObjectManager.Cat.xml"/>
 
 </chapter>

gio/tests/Makefile.am

@@ -486,7 +486,7 @@ test.mo: de.po
 	$(MKDIR_P) de/LC_MESSAGES; \
 	cp -f test.mo de/LC_MESSAGES
 
-CLEANFILES = gdbus-test-codegen-generated.[ch] gdbus-test-codegen-generated-doc-*.xml
+CLEANFILES = gdbus-test-codegen-generated.[ch] gdbus-test-codegen-generated-doc-*.xml gdbus-example-objectmanager-generated-*.xml
 
 DISTCLEANFILES = \
 	applications/mimeinfo.cache	\

gio/tests/gdbus-example-objectmanager-client.c

@@ -3,6 +3,52 @@
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+static void
+print_objects (GDBusObjectManager *manager)
+{
+  GList *objects;
+  GList *l;
+
+  g_print ("Object manager at %s\n", g_dbus_object_manager_get_object_path (manager));
+  objects = g_dbus_object_manager_get_objects (manager);
+  for (l = objects; l != NULL; l = l->next)
+    {
+      GDBusObject *object = G_DBUS_OBJECT (l->data);
+      GList *interfaces;
+      GList *ll;
+      g_print (" - Object at %s\n", g_dbus_object_get_object_path (object));
+
+      interfaces = g_dbus_object_get_interfaces (object);
+      for (ll = interfaces; ll != NULL; ll = ll->next)
+        {
+          GDBusInterface *interface = G_DBUS_INTERFACE (ll->data);
+          g_print ("   - Interface %s\n", g_dbus_interface_get_info (interface)->name);
+
+          /* Note that @interface is really a GDBusProxy instance - and additionally also
+           * an ExampleAnimal or ExampleCat instance - either of these can be used to
+           * invoke methods on the remote object. For example, the generated function
+           *
+           *  void example_animal_call_poke_sync (ExampleAnimal  *proxy,
+           *                                      gboolean        make_sad,
+           *                                      gboolean        make_happy,
+           *                                      GCancellable   *cancellable,
+           *                                      GError        **error);
+           *
+           * can be used to call the Poke() D-Bus method on the .Animal interface.
+           * Additionally, the generated function
+           *
+           *  const gchar *example_animal_get_mood (ExampleAnimal *object);
+           *
+           * can be used to get the value of the :Mood property.
+           */
+        }
+      g_list_foreach (interfaces, (GFunc) g_object_unref, NULL);
+      g_list_free (interfaces);
+    }
+  g_list_foreach (objects, (GFunc) g_object_unref, NULL);
+  g_list_free (objects);
+}
+
 static void
 on_object_added (GDBusObjectManager *manager,
                  GDBusObject        *object,
@@ -10,7 +56,7 @@ on_object_added (GDBusObjectManager *manager,
 {
   gchar *owner;
   owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
-  g_debug ("added object at %s (owner %s)", g_dbus_object_get_object_path (object), owner);
+  g_print ("Added object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
   g_free (owner);
 }
 
@@ -21,7 +67,7 @@ on_object_removed (GDBusObjectManager *manager,
 {
   gchar *owner;
   owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
-  g_debug ("removed object at %s (owner %s)", g_dbus_object_get_object_path (object), owner);
+  g_print ("Removed object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
   g_free (owner);
 }
 
@@ -34,7 +80,7 @@ on_notify_name_owner (GObject    *object,
   gchar *name_owner;
 
   name_owner = g_dbus_object_manager_client_get_name_owner (manager);
-  g_debug ("name-owner: %s", name_owner);
+  g_print ("name-owner: %s\n", name_owner);
   g_free (name_owner);
 }
 
@@ -69,8 +115,6 @@ main (gint argc, gchar *argv[])
   GMainLoop *loop;
   GError *error;
   gchar *name_owner;
-  GList *objects;
-  GList *l;
 
   manager = NULL;
   loop = NULL;
@@ -94,17 +138,10 @@ main (gint argc, gchar *argv[])
     }
 
   name_owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
-  g_debug ("name-owner: %s", name_owner);
+  g_print ("name-owner: %s\n", name_owner);
   g_free (name_owner);
 
-  objects = g_dbus_object_manager_get_objects (manager);
+  print_objects (manager);
-  for (l = objects; l != NULL; l = l->next)
-    {
-      GDBusObject *object = G_DBUS_OBJECT (l->data);
-      g_debug ("proxy has object at %s", g_dbus_object_get_object_path (object));
-    }
-  g_list_foreach (objects, (GFunc) g_object_unref, NULL);
-  g_list_free (objects);
 
   g_signal_connect (manager,
                     "notify::name-owner",

gio/tests/gdbus-example-objectmanager-server.c

@@ -12,7 +12,6 @@ on_animal_poke (ExampleAnimal          *animal,
                 gboolean                make_happy,
                 gpointer                user_data)
 {
-
   if ((make_sad && make_happy) || (!make_sad && !make_happy))
     {
       g_dbus_method_invocation_return_dbus_error (invocation,
@@ -66,30 +65,49 @@ on_bus_acquired (GDBusConnection *connection,
   GDBusObjectStub *object;
   guint n;
 
-  g_debug ("bus acquired");
+  g_print ("Acquired a message bus connection\n");
 
+  /* Create a new org.freedesktop.DBus.ObjectManager rooted at /example/Animals */
   manager = g_dbus_object_manager_server_new (connection, "/example/Animals");
+
   for (n = 0; n < 10; n++)
     {
       gchar *s;
       ExampleAnimal *animal;
 
+      /* Create a new D-Bus object at the path /example/Animals/N where N is 000..009 */
       s = g_strdup_printf ("/example/Animals/%03d", n);
       object = g_dbus_object_stub_new (s);
       g_free (s);
 
+      /* Make the newly created object export the interface
+       * org.gtk.GDBus.Example.ObjectManager.Animal (note
+       * that @object takes its own reference to @animal).
+       */
       animal = example_animal_stub_new ();
       example_animal_set_mood (animal, "Happy");
+      g_dbus_object_stub_add_interface (object, G_DBUS_INTERFACE_STUB (animal));
+      g_object_unref (animal);
 
-      /* Handle Poke() method invocations */
+      /* Cats are odd animals - so some of our objects implement the
+       * org.gtk.GDBus.Example.ObjectManager.Cat interface in addition
+       * to the .Animal interface
+       */
+      if (n % 2 == 1)
+        {
+          ExampleCat *cat;
+          cat = example_cat_stub_new ();
+          g_dbus_object_stub_add_interface (object, G_DBUS_INTERFACE_STUB (cat));
+          g_object_unref (cat);
+        }
+
+      /* Handle Poke() D-Bus method invocations on the .Animal interface */
       g_signal_connect (animal,
                         "handle-poke",
                         G_CALLBACK (on_animal_poke),
                         NULL); /* user_data */
 
-      g_dbus_object_stub_add_interface (object, G_DBUS_INTERFACE_STUB (animal));
+      /* Export the object (@manager takes its own reference to @object) */
-      g_object_unref (animal);
-
       g_dbus_object_manager_server_export (manager, object);
       g_object_unref (object);
     }
@@ -100,7 +118,7 @@ on_name_acquired (GDBusConnection *connection,
                   const gchar     *name,
                   gpointer         user_data)
 {
-  g_debug ("name acquired");
+  g_print ("Acquired the name %s\n", name);
 }
 
 static void
@@ -108,7 +126,7 @@ on_name_lost (GDBusConnection *connection,
               const gchar     *name,
               gpointer         user_data)
 {
-  g_debug ("name lost");
+  g_print ("Lost the name %s\n", name);
 }
 
 

gio/tests/gdbus-example-objectmanager.xml

@@ -1,6 +1,6 @@
 <node>
   <!-- org.gtk.GDBus.Example.ObjectManager.Animal:
-       @short_description: Example docs generated by gdbus-codegen(1)
+       @short_description: Example docs generated by gdbus-codegen
 
        This D-Bus interface is used to describe a simple animal.
     -->
@@ -42,4 +42,20 @@
       <arg type="d" name="height"/>
     </signal>
   </interface>
+
+  <!-- org.gtk.GDBus.Example.ObjectManager.Cat:
+       @short_description: Another interface doc generated by gdbus-codegen
+
+       This D-Bus interface is used to describe a cat. Right now there
+       are no properties, methods or signals associated with this
+       interface so it is essentially a <ulink
+       url="http://en.wikipedia.org/wiki/Marker_interface_pattern">Marker
+       Interface</ulink>.
+
+       Note that D-Bus objects implementing this interface also
+       implement the #org.gtk.GDBus.Example.ObjectManager.Animal
+       interface.
+    -->
+  <interface name="org.gtk.GDBus.Example.ObjectManager.Cat">
+  </interface>
 </node>