From f72c693f48d8be621e912366457699f787089400 Mon Sep 17 00:00:00 2001 From: Ross Burton Date: Mon, 19 Dec 2005 18:11:05 +0000 Subject: Add documentation on glib client bindings and annotations --- doc/dbus-tutorial.xml | 264 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 240 insertions(+), 24 deletions(-) (limited to 'doc') diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index a5b210b6..78e8489c 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -15,9 +15,7 @@ Pennington Red Hat, Inc. -
- hp@pobox.com -
+
hp@pobox.com
 @@ -29,9 +27,7 @@ Palmieri Red Hat, Inc. -
- johnp@redhat.com -
+
johnp@redhat.com
 @@ -39,9 +35,7 @@ Walters Red Hat, Inc. -
- walters@redhat.com -
+
walters@redhat.com
 @@ -470,7 +464,7 @@ The GLib binding is defined in the header file - <dbus/dbus-glib.h>. + <dbus/dbus-glib.h>. @@ -511,22 +505,22 @@ INT16 G_TYPE_INT - Will be changed to a G_TYPE_INT16 once GLib has it + Will be changed to a G_TYPE_INT16 once GLib has it UINT16 G_TYPE_UINT - Will be changed to a G_TYPE_UINT16 once GLib has it + Will be changed to a G_TYPE_UINT16 once GLib has it INT32 G_TYPE_INT - Will be changed to a G_TYPE_INT32 once GLib has it + Will be changed to a G_TYPE_INT32 once GLib has it UINT32 G_TYPE_UINT - Will be changed to a G_TYPE_UINT32 once GLib has it + Will be changed to a G_TYPE_UINT32 once GLib has it INT64 G_TYPE_GINT64 @@ -545,12 +539,12 @@ STRING G_TYPE_STRING - g_free + g_free OBJECT_PATH DBUS_TYPE_G_PROXY - g_object_unref + g_object_unref The returned proxy does not have an interface set; use dbus_g_proxy_set_interface to invoke methods @@ -581,7 +575,7 @@ First, D-BUS type signatures which have an "obvious" - corresponding builtin GLib type are mapped using that type: + corresponding built-in GLib type are mapped using that type: @@ -600,14 +594,14 @@ Array of strings G_TYPE_STRV char ** - g_strfreev + g_strfreev v Generic value container G_TYPE_VALUE GValue * - g_value_unset + g_value_unset The calling conventions for values expect that method callers have allocated return values; see below. @@ -836,7 +830,7 @@ main (int argc, char **argv) You have a number of choices for method invocation. First, as used above, dbus_g_proxy_call sends a - method call to the remote object, and blocks until reply is + method call to the remote object, and blocks until a reply is recieved. The outgoing arguments are specified in the varargs array, terminated with G_TYPE_INVALID. Next, pointers to return values are specified, followed again @@ -1073,6 +1067,83 @@ main (int argc, char **argv) + + + Generated Bindings + + By using the Introspection XML files, convenient client-side bindings + can be automatically created to ease the use of a remote DBus object. + + + Here is a sample XML file which describes an object that exposes + one method, named ManyArgs. + +<?xml version="1.0" encoding="UTF-8" ?> +<node name="/com/example/MyObject"> + <interface name="com.example.MyObject"> + <method name="ManyArgs"> + <arg type="u" name="x" direction="in" /> + <arg type="s" name="str" direction="in" /> + <arg type="d" name="trouble" direction="in" /> + <arg type="d" name="d_ret" direction="out" /> + <arg type="s" name="str_ret" direction="out" /> + </method> + </interface> +</node> + + + + Run dbus-binding-tool --mode=glib-client + FILENAME > + HEADER_NAME to generate the header + file. For example: dbus-binding-tool --mode=glib-client + my-object.xml > my-object-bindings.h. This will generate + inline functions with the following prototypes: + +/* This is a blocking call */ +gboolean +com_example_MyObject_many_args (DBusGProxy *proxy, const guint IN_x, + const char * IN_str, const gdouble IN_trouble, + gdouble* OUT_d_ret, char ** OUT_str_ret, + GError **error); + +/* This is a non-blocking call */ +DBusGProxyCall* +com_example_MyObject_many_args_async (DBusGProxy *proxy, const guint IN_x, + const char * IN_str, const gdouble IN_trouble, + com_example_MyObject_many_args_reply callback, + gpointer userdata); + +/* This is the typedef for the non-blocking callback */ +typedef void +(*com_example_MyObject_many_args_reply) +(DBusGProxy *proxy, gdouble OUT_d_ret, char * OUT_str_ret, + GError *error, gpointer userdata); + + The first argument in all functions is a DBusGProxy + *, which you should create with the usual + dbus_g_proxy_new_* functions. Following that are the + "in" arguments, and then either the "out" arguments and a + GError * for the synchronous (blocking) function, or + callback and user data arguments for the asynchronous (non-blocking) + function. The callback in the asynchronous function passes the + DBusGProxy *, the returned "out" arguments, an + GError * which is set if there was an error otherwise + NULL, and the user data. + + + As with the server-side bindings support (see ), the exact behaviour of the client-side + bindings can be manipulated using "annotations". Currently the only + annotation used by the client bindings is + org.freedesktop.DBus.GLib.NoReply, which sets the + flag indicating that the client isn't expecting a reply to the method + call, so a reply shouldn't be sent. This is often used to speed up + rapid method calls where there are no "out" arguments, and not knowing + if the method succeeded is an acceptable compromise to half the traffic + on the bus. + + @@ -1118,13 +1189,13 @@ main (int argc, char **argv) Once you have written this XML, run dbus-binding-tool --mode=glib-server FILENAME > HEADER_NAME. to - generate a header file. For example: dbus-binding-tool --mode=glib-server my-objet.xml > my-object-glue.h. + generate a header file. For example: dbus-binding-tool --mode=glib-server my-object.xml > my-object-glue.h. Next, include the generated header in your program, and invoke - dbus_g_object_class_install_info, passing the - object class and "object info" included in the header. For - example: + dbus_g_object_class_install_info in the class + initializer, passing the object class and "object info" included in the + header. For example: dbus_g_object_type_install_info (COM_FOO_TYPE_MY_OBJECT, &com_foo_my_object_info); @@ -1177,6 +1248,151 @@ main (int argc, char **argv) obj); + + + Server-side Annotations + + There are several annotations that are used when generating the + server-side bindings. The most common annotation is + org.freedesktop.DBus.GLib.CSymbol but there are other + annotations which are often useful. + + + org.freedesktop.DBus.GLib.CSymbol + + + This annotation is used to specify the C symbol names for + the various types (interface, method, etc), if it differs from the + name DBus generates. + + + + + org.freedesktop.DBus.GLib.Async + + + This annotation marks the method implementation as an + asynchronous function, which doesn't return a response straight + away but will send the response at some later point to complete + the call. This is used to implement non-blocking services where + method calls can take time. + + + When a method is asynchronous, the function prototype is + different. It is required that the function conform to the + following rules: + + + + The function must return a value of type gboolean; + TRUE on success, and FALSE + otherwise. TODO: the return value is currently ignored. + + + + + The first parameter is a pointer to an instance of the object. + + + + + Following the object instance pointer are the method + input values. + + + + + The final parameter must be a + DBusGMethodInvocation *. This is used + when sending the response message back to the client, by + calling dbus_g_method_return or + dbus_g_method_return_error. + + + + + + + + org.freedesktop.DBus.GLib.Const + + This attribute can only be applied to "out" + <arg> nodes, and specifies that the + parameter isn't being copied when returned. For example, this + turns a 's' argument from a char ** to a + const char **, and results in the argument not + being freed by DBus after the message is sent. + + + + + org.freedesktop.DBus.GLib.ReturnVal + + + This attribute can only be applied to "out" + <arg> nodes, and alters the expected + function signature. It currently can be set to two values: + "" or "error". The + argument marked with this attribute is not returned via a + pointer argument, but by the function's return value. If the + attribute's value is the empty string, the GError + * argument is also omitted so there is no standard way + to return an error value. This is very useful for interfacing + with existing code, as it is possible to match existing APIs. + If the attribute's value is "error", then the + final argument is a GError * as usual. + + + Some examples to demonstrate the usage. This introspection XML: + +<method name="Increment"> + <arg type="u" name="x" /> + <arg type="u" direction="out" /> +</method> + + Expects the following function declaration: + +gboolean +my_object_increment (MyObject *obj, gint32 x, gint32 *ret, GError **error); + + + + This introspection XML: + +<method name="IncrementRetval"> + <arg type="u" name="x" /> + <arg type="u" direction="out" > + <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/> + </arg> +</method> + + Expects the following function declaration: + +gint32 +my_object_increment_retval (MyObject *obj, gint32 x) + + + + This introspection XML: + +<method name="IncrementRetvalError"> + <arg type="u" name="x" /> + <arg type="u" direction="out" > + <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/> + </arg> +</method> + + Expects the following function declaration: + +gint32 +my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) + + + + + + + -- cgit