Overview

The low-level API for D-Bus is written in C but application developers usually use higher level bindings like libdbus-glib, libdbus-qt, and Python for easier use and improved functionality. If you are writing in C, then the glib bindings are recommended. In this tutorial, we will cover the D-Bus programming with libdbus-glib because it is commonly used in Moblin applications. For D-Bus low-level API and other higher level bindings, we provide some useful links for your reference.

Install the Library Package

Add D-Bus Reference into Build File

After the packages are installed, you should modify the build file configure.ac or configure.in to tell the compiler where to find the header files and inform the linker what library file should be linked into the application.

Include the Right Header File

Useful Tools

dbus-send and dbus-monitor are useful tools for you to develop applications that use D-Bus. These tool are already installed if you have D-Bus installed.

• The dbus-send tool is used to send a message to a D-Bus message bus^[10]. For more details about dbus-send, refer to http://dbus.freedesktop.org/doc/dbus-send.1.html.
• The dbus-monitor tool is used to monitor messages going through a D-Bus message bus^[11]. For more details about dbus-monitor, refer to http://dbus.freedesktop.org/doc/dbus-monitor.1.html.

Overview

Here is a list of the general steps you can follow to implement the D-Bus operation of exposing a method to be called.

1. Run dbus-binding-tool to generate the dbus-glib binding code for server side
2. Create a simple GObject for D-Bus
• Create the per-instance and per-class state structures
• Define convenience macros in a way expected for all GTypes
• Implement the instance initialization and class initialization
• Implement the method functions
3. Register the object to the D-Bus
• Initialize the GType system and open a connection to the session bus
• Attach the server to a well-known name
• Create an instance of your object and register it to the D-Bus

We will cover more detailed information in next parts and provide the sample code for your reference.

Generate the dbus-glib Binding Code for Server Side

A tool called dbus-binding-tool can help developers generate the dbus-glib binding code for both the server (exposing a method) and client (calling a method) side. It uses an XML file which describes the method and signal definitions as input.

An example xml file should look like this:

When the XML interface file is ready, you can use it as the input to run dbus-binding-tool to generate the glib binding code for the server side.

After running the command, the file example-expose-method.h should be generated.

The method table lists the method function address, the function to use to marshal data and the offset into the introspection data.

The _object_info structure will be passed to D-Bus daemon when you create the instance of your object and register with D-Bus to register it to the D-Bus. The structure includes format_version, methodinfo structure, method datas, signal datas etc.

Create a Simple GObject for D-Bus

1. Create the Per-instance and Per-class State Structures

First, you should create per-class and per-instance state structures for your object. The per-class structure contains the bare minimum contents, which are required for all classes in GObject. The per-instance structure contains the required parent object state and some internal values.^[8]
[glib-dbus-method/src/example-expose-method.c]
typedef struct
{
    GObject parent;
    gint ret_value;
}SampleObject;

typedef struct
{
    GObjectClass parent;
}SampleObjectClass;

2. Define Convenience Macros in a Way Expected for All GTypes

Then you can continue by defining convenience macros in a way expected for all GTypes.^[8] For more details about GType macros, refer to http://maemo.org/api_refs/4.0/gobject/index.html.
[glib-dbus-method/src/example-expose-method.c]
/* Forward declaration of the function that will return the GType of
   the Value implementation. Not used in this program. */
GType Sample_object_get_type (void);

/* Macro for the above. It is common to define macros using the
   naming convention (seen below) for all GType implementations,
   and that's why we're going to do that here as well. */
#define SAMPLE_TYPE_OBJECT              (sample_object_get_type ())
#define SAMPLE_OBJECT(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), SAMPLE_TYPE_OBJECT, SampleObject))
#define SAMPLE_OBJECT_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), SAMPLE_TYPE_OBJECT, SampleObjectClass))
#define SAMPLE_IS_OBJECT(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), SAMPLE_TYPE_OBJECT))
#define SAMPLE_IS_OBJECT_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), SAMPLE_TYPE_OBJECT))
#define SAMPLE_OBJECT_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), SAMPLE_TYPE_OBJECT, SampleObjectClass))

G_DEFINE_TYPE(SampleObject, sample_object, G_TYPE_OBJECT)

3. Implement the Instance Initialization and Class Initialization

After the macros, you should finish the instance initialization and class initialization functions. The class initialization function contains the integration call into GLib/D-Bus: dbus_g_object_type_install_info, which take a pointer to the structure describing the D-Bus integration (dbus_glib_value_object_object_info). This function will create all the necessary runtime information for GType.^[8]
[glib-dbus-method/src/example-expose-method.c]
/*
 * Object initializer
 * Set ret_value to 0
 */
static void
sample_object_init (SampleObject *obj)
{
    g_print (PROGNAME " : sample_object_init is called.\n");
    g_assert(obj != NULL);
    obj->ret_value = 0;
}

/*
 * Class initializer
 */
static void
sample_object_class_init (SampleObjectClass *klass)
{
    g_print (PROGNAME " : sample_object_class_init is called.\n");
    g_assert(klass != NULL);

    g_print (PROGNAME " : Binding to Glib/D-Bus.\n");
    /*Bind this GType into the Glib/D-Bus wrappers*/
    dbus_g_object_type_install_info (SAMPLE_TYPE_OBJECT, &dbus_glib_example_object_object_info);
}

4. Implement the Method Functions

Next, you can implement the method functions which are dictated by the method table in the generated binding code.
The example_object_hello_method function in our example includes four parameters:

• SampleObject *obj – The pointer to the object.
• const char *hello_message – The input parameters.
• gint *ret – The pointer to method return value. Note that the return value is not done by using “return Val”, instead return values are written with the given pointer^[8].
• GError **error – The pointer to the GError objects to store the error messages.
 [glib-dbus-method/src/example-expose-method.c]
/*
 * Function that gets executed on "hello_method".
 */
gboolean
example_object_hello_method (SampleObject *obj, const char *hello_message, gint *ret, GError **error)
{
    g_assert(obj != NULL);

    obj->ret_value ++;
    *ret = obj->ret_value;
 
    g_print (PROGNAME " : hello_method is Called, arg = %s, ret = %d.\n", hello_message, *ret); 

    return TRUE;
}

Register the Object to the D-Bus

After the D-Bus method function is implemented, you should add the code for registering the object to the D-Bus. All the code is added to the main function in our test program (glib-dbus-method/src/example-expose-method.c).

1. Initialize the GType System and Open a Connection to the Session Bus
First, the GType system should be initialized by calling g_type_init, before using any of the GType, and then you should open a connection to the session bus. [glib-dbus-method/src/example-expose-method.c]
/*
 * The main service code
 */
int
main (int argc, char **argv)
{
    /* The GObject representing a D-Bus connection. */
    DBusGConnection *bus;
    /* Proxy object representing the D-Bus service object. */
    DBusGProxy *bus_proxy;
    /* Will hold one instance of SampleObject that will serve all the requsts. */
    SampleObject *obj;
    /* GMainLoop object */
    GMainLoop *mainloop;
    guint result;
    GError *error = NULL;

    /* Initialize the GType/GObject system. */
    g_type_init ();
 
    /* Create a main loop that will dispatch callbacks. */
    mainloop = g_main_loop_new (NULL, FALSE);
    if (mainloop == NULL) {
      /* Print error and terminate. */
      g_print (PROGNAME " : Couldn't create GMainLoop.\n");
      exit(1);
    }
   
    /*Connect to the session bus*/
    g_print (PROGNAME " : Connecting to Session D-Bus.\n");
    bus = dbus_g_bus_get (DBUS_BUS_SESSION, &error);
    if (bus == NULL) {
      g_print (PROGNAME " : Couldn't connect to session bus, %s\n", error->message);
      exit(1);
    }



2. Attach the Server to a Well-known Name
For prospective clients to find the object on the session bus, you should attach the server to a well-known name. This is done with the RequestName method call on the D-Bus server. For more details about D-Bus introspection, refer to http://maemo.org/maemo_training_material/maemo4.x/html/maemo_Platform_Development/
Chapter_03_Using_the_GLib_wrappers_for_DBus.html.
[glib-dbus-method/src/example-expose-method.c]
bus_proxy = dbus_g_proxy_new_for_name (bus, "org.freedesktop.DBus",
                               "/org/freedesktop/DBus",
                               "org.freedesktop.DBus");
    /* Attempt to register the well-known name. */
    if (!dbus_g_proxy_call (bus_proxy, "RequestName", &error,
                     G_TYPE_STRING, SAMPLE_SERVICE_NAME,
                     G_TYPE_UINT, 0,
                     G_TYPE_INVALID,
                     G_TYPE_UINT, &result,
                     G_TYPE_INVALID)) {
        /* Print error and terminate. */
        g_print (PROGNAME " : D-Bus.RequestName RPC failed %s\n", error->message);
        exit(1);
    }

    g_print (PROGNAME " : RequestName returned %d.\n", result);
    /*Check the result*/
    if(result != 1) {
        /* Print error and terminate. */
        g_print (PROGNAME " : Failed to get the primary well-known name.\n");
        exit(1);
    }



3. Create an Instance of Your Object and Register It to the D-Bus
After the name is successfully registered, you should create an instance of the SampleObject and register it to the D-Bus. All the callback registration will be done automatically by the Glib/D-Bus wrappers on this operation. Next, main will enter into the main loop, and start to serve client requests.^[8]
[glib-dbus-method/src/example-expose-method.c]
/*Create one instance*/
    obj = g_object_new (SAMPLE_TYPE_OBJECT, NULL);
    if(!obj) {
        /* Print error and terminate. */
        g_print (PROGNAME " : Failed to create one instance.\n");
        exit(1);
    }
    /*Register the instance to D-Bus*/
    dbus_g_connection_register_g_object (bus, SAMPLE_SERVICE_OBJECT_PATH, G_OBJECT (obj));

    printf ("service running\n");

    /*Run the program*/
    g_main_loop_run (mainloop);

    return (1);
}
         

Build and Run Sample Code

You can write a Makefile.am for automake to generate makefile template – Makefile.in.

For more details about the makefile.am, refer to SDK doc, Using GNU Autotools.

After Makefile.am is ready, you can build and run program example-expose-method.

Calling a Method

Emitting a Signal

Catching a Signal