diff options
author | Havoc Pennington <hp@redhat.com> | 2004-08-10 04:18:31 +0000 |
---|---|---|
committer | Havoc Pennington <hp@redhat.com> | 2004-08-10 04:18:31 +0000 |
commit | cd33e8dd6227e5f66114178ca1dc0f3677893252 (patch) | |
tree | 9fa00a793d466c453cc307880b979632c429f2b2 | |
parent | 43605a6f4e78a8c28afb4b1e924dff0301e0e95c (diff) |
2004-08-10 Havoc Pennington <hp@redhat.com>
* doc/dbus-tutorial.xml: add some more info on GLib bindings
-rw-r--r-- | ChangeLog | 4 | ||||
-rw-r--r-- | doc/dbus-tutorial.xml | 152 |
2 files changed, 149 insertions, 7 deletions
@@ -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 + <dbus/dbus-glib.h>. The API is very small, in sharp contrast to the + low-level <dbus/dbus.h>. + </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, + &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, &error, + DBUS_TYPE_ARRAY, DBUS_TYPE_STRING, + &service_list, &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 < 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 + <dbus/dbus-glib.h>. 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> |