From cd33e8dd6227e5f66114178ca1dc0f3677893252 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 10 Aug 2004 04:18:31 +0000 Subject: 2004-08-10 Havoc Pennington * doc/dbus-tutorial.xml: add some more info on GLib bindings --- doc/dbus-tutorial.xml | 152 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 145 insertions(+), 7 deletions(-) (limited to 'doc/dbus-tutorial.xml') 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 @@
D-BUS Tutorial - Version 0.1 - 02 October 2003 + Version 0.2 + 10 August 2004 Havoc @@ -58,6 +58,12 @@ + + If you just want to use D-BUS and don't care how it works, jump directly + to . + Otherwise, read on. + + libdbus only supports one-to-one connections, just like a raw network socket. However, rather than sending byte streams over the connection, you @@ -245,7 +251,7 @@ Each object supports one or more interfaces. 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 type of an object instance. @@ -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. @@ -425,29 +431,159 @@ GLib API: Using Remote Objects + + 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>. + + + + The GLib bindings are incomplete, see the TODO file and comments in the + source code. + + + +Here is a D-BUS program using the GLib bindings. + +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; +} + + + + + + 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. + + + + + + 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.) + + + + + + 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(). + + + GLib API: Implementing Objects + + 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. + + + + 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. + + Qt API: Using Remote Objects + The Qt bindings are not yet documented. + Qt API: Implementing Objects - + The Qt bindings are not yet documented. @@ -455,14 +591,16 @@ Python API: Using Remote Objects - + The Python bindings are not yet documented, but the + bindings themselves are in good shape. Python API: Implementing Objects - + The Python bindings are not yet documented, but the + bindings themselves are in good shape. -- cgit