2004-08-10 Havoc Pennington <hp@redhat.com>

	* doc/dbus-tutorial.xml: add some more info on GLib bindings

2 files changed, 149 insertions, 7 deletions

diff --git a/ChangeLog b/ChangeLog
index f54f01e3..f9344e7e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-08-10  Havoc Pennington  <hp@redhat.com>
+
+	* doc/dbus-tutorial.xml: add some more info on GLib bindings
+
 2004-08-09  Havoc Pennington  <hp@redhat.com>
 
 	* COPYING: switch to Academic Free License version 2.1 instead of
diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml
index 2bb67a4e..6d1b7f3b 100644
--- a/doc/dbus-tutorial.xml
+++ b/doc/dbus-tutorial.xml
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-BUS Tutorial</title>
-    <releaseinfo>Version 0.1</releaseinfo>
-    <date>02 October 2003</date>
+    <releaseinfo>Version 0.2</releaseinfo>
+    <date>10 August 2004</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -59,6 +59,12 @@
     </para>
 
     <para>
+      If you just want to use D-BUS and don't care how it works, jump directly
+      to <xref linkend="concepts"/>.
+      Otherwise, read on.
+    </para>
+
+    <para>
       libdbus only supports one-to-one connections, just like a raw network
       socket. However, rather than sending byte streams over the connection, you
       send <firstterm>messages</firstterm>. Messages have a header identifying
@@ -245,7 +251,7 @@
       <para>
         Each object supports one or more <firstterm>interfaces</firstterm>.
         Think of an interface as a named group of methods and signals, 
-        just as it is in GLib or Qt. Interfaces define the 
+        just as it is in GLib or Qt or Java. Interfaces define the 
         <emphasis>type</emphasis> of an object instance.
       </para>
     </sect2>
@@ -407,7 +413,7 @@
         The service is in brackets to indicate that it's optional -- you only
         provide a service name to route the method call to the right application
         when using the bus daemon. If you have a direct connection to another
-        application, services aren't used.
+        application, services aren't used; there's no bus daemon.
       </para>
 
       <para>
@@ -425,29 +431,159 @@
 
   <sect1 id="glib-client">
     <title>GLib API: Using Remote Objects</title>
+
     <para>
       
+      The GLib binding is defined in the header file
+      &lt;dbus/dbus-glib.h&gt;. The API is very small, in sharp contrast to the
+      low-level &lt;dbus/dbus.h&gt;.
+
     </para>
+
+    <para>
+      The GLib bindings are incomplete, see the TODO file and comments in the
+      source code.
+    </para>
+
+    <para>
+Here is a D-BUS program using the GLib bindings.
+<programlisting>      
+int
+main (int argc, char **argv)
+{
+  DBusGConnection *connection;
+  GError *error;
+  DBusGProxy *proxy;
+  DBusGPendingCall *call;
+  char **service_list;
+  int service_list_len;
+  int i;
+  
+  g_type_init ();
+
+  error = NULL;
+  connection = dbus_g_bus_get (DBUS_BUS_SESSION,
+                               &amp;error);
+  if (connection == NULL)
+    {
+      g_printerr ("Failed to open connection to bus: %s\n",
+                  error->message);
+      g_error_free (error);
+      exit (1);
+    }
+
+  /* Create a proxy object for the "bus driver" (service org.freedesktop.DBus) */
+  
+  proxy = dbus_g_proxy_new_for_service (connection,
+                                        DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
+                                        DBUS_PATH_ORG_FREEDESKTOP_DBUS,
+                                        DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS);
+
+  /* Call ListServices method */
+  
+  call = dbus_g_proxy_begin_call (proxy, "ListServices", DBUS_TYPE_INVALID);
+
+  error = NULL;
+  if (!dbus_g_proxy_end_call (proxy, call, &amp;error,
+                              DBUS_TYPE_ARRAY, DBUS_TYPE_STRING,
+                              &amp;service_list, &amp;service_list_len,
+                              DBUS_TYPE_INVALID))
+    {
+      g_printerr ("Failed to complete ListServices call: %s\n",
+                  error->message);
+      g_error_free (error);
+      exit (1);
+    }
+
+  /* Print the results */
+ 
+  g_print ("Services on the message bus:\n");
+  i = 0;
+  while (i &lt; service_list_len)
+    {
+      g_assert (service_list[i] != NULL);
+      g_print ("  %s\n", service_list[i]);
+      ++i;
+    }
+  g_assert (service_list[i] == NULL);
+
+  g_strfreev (service_list);
+
+  return 0;
+}
+</programlisting>
+    </para>
+
+    <para>
+
+      DBusGProxy represents a remote object. dbus_g_proxy_begin_call() sends 
+      a method call to the remote object, and dbus_g_proxy_end_call() retrieves 
+      any return values or exceptions resulting from the method call. 
+      There are also DBusGProxy functions to connect and disconnect signals, 
+      not shown in the code example.
+
+    </para>
+
+    <para>
+      
+      dbus_g_bus_get() assumes that the application will use GMainLoop. The
+      created connection will be associated with the main loop such that
+      messages will be sent and received when the main loop runs.  However, in
+      the above code example the main loop never runs; D-BUS will not run the
+      loop implicitly. Instead, dbus_g_proxy_end_call() will block until the
+      method call has been sent and the reply received. A more complex GUI
+      application might run the main loop while waiting for the method call
+      reply.  (DBusGPendingCall is currently missing the "notify me when the
+      call is complete" functionality found in DBusPendingCall, but it should be
+      added.)
+
+    </para>
+
+    <para>
+      
+      Future plans (see doc/TODO) are to use G_TYPE_STRING in place of
+      DBUS_TYPE_STRING and so forth. In fact the above code is slightly
+      incorrect at the moment, since it uses g_strfreev() to free a string array
+      that was not allocated with g_malloc(). dbus_free_string_array() should
+      really be used. However, once the GLib bindings are complete the returned
+      data from dbus_g_proxy_end_call() will be allocated with g_malloc().
+
+    </para>
+
   </sect1>
 
   <sect1 id="glib-server">
     <title>GLib API: Implementing Objects</title>
+
     <para>
       
+      The GLib binding is defined in the header file
+      &lt;dbus/dbus-glib.h&gt;. To implement an object, it's also necessary
+      to use the dbus-glib-tool command line tool.
+
     </para>
+
+    <para>
+      The GLib bindings are incomplete.  Implementing an object is not yet
+      possible, see the TODO file and comments in the source code for details
+      on what work needs doing.
+    </para>
+      
   </sect1>
 
   <sect1 id="qt-client">
     <title>Qt API: Using Remote Objects</title>
     <para>
       
+      The Qt bindings are not yet documented.
+
     </para>
   </sect1>
 
   <sect1 id="qt-server">
     <title>Qt API: Implementing Objects</title>
     <para>
-      
+      The Qt bindings are not yet documented.
     </para>
   </sect1>
 
@@ -455,14 +591,16 @@
   <sect1 id="python-client">
     <title>Python API: Using Remote Objects</title>
     <para>
-      
+      The Python bindings are not yet documented, but the 
+      bindings themselves are in good shape.
     </para>
   </sect1>
 
   <sect1 id="python-server">
     <title>Python API: Implementing Objects</title>
     <para>
-      
+      The Python bindings are not yet documented, but the 
+      bindings themselves are in good shape.
     </para>
   </sect1>