Editing Documentation/Maemo 5 Developer Guide/DBus/DBus Basics

A bus exists in the system in the form of a ''bus daemon'', a process that specializes in passing messages from one process to another. The daemon also forwards notifications to all applications on the bus. At the lowest level, D-Bus only supports point-to-point communication, normally using the local domain sockets (<code>AF_UNIX</code>) between the application and the bus daemon. The point-to-point aspect of D-Bus is, however, abstracted by the bus daemon, which implements the addressing and message passing functionality. This means that applications do not need to care about which specific process receives each method call or notification.

** Object paths look like file paths (elements separated with the '<code>/</code>' character).

<source lang="c">

#define SYSNOTE_NAME  "org.freedesktop.Notifications"

#define SYSNOTE_OPATH "/org/freedesktop/Notifications"

#define SYSNOTE_IFACE "org.freedesktop.Notifications"

#define SYSNOTE_NOTE  "SystemNoteDialog"

</source>

[sbox-DIABLO_X86: ~] > run-standalone.sh dbus-send --print-reply  \

--type=method_call --dest=org.freedesktop.Notifications  \

/org/freedesktop/Notifications org.freedesktop.Notifications.SystemNoteDialog  \

string:'Hello, world!' uint32:0 string:'NAO OK!'

method return sender=:1.1 -> dest=:1.15

  uint32 4

[[Image:dbus-send-SystemNoteDialog.png|frame|center|alt=Screenshot of Note dialog showing text ‘Hello, world!’|System note dialog]]

<source lang="c">

/**

  * Uses the low-level libdbus which should not be used directly.

  * As the D-Bus API reference puts it "If you use this low-level API

  * directly, you are signing up for some pain".

  */

</source>

The first step is to introduce the necessary header files. [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

<source lang="c">

#include <dbus/dbus.h> /* Pull in all of D-Bus headers. */

#include <stdio.h>    /* printf, fprintf, stderr */

#include <stdlib.h>    /* EXIT_FAILURE, EXIT_SUCCESS */

#include <assert.h>    /* assert */

/* Symbolic defines for the D-Bus well-known name, interface, object

  path and method name that we are going to use. */

#define SYSNOTE_NAME  "org.freedesktop.Notifications"

#define SYSNOTE_OPATH "/org/freedesktop/Notifications"

#define SYSNOTE_IFACE "org.freedesktop.Notifications"

#define SYSNOTE_NOTE  "SystemNoteDialog"

</source>

Connecting to the session bus yields a <code>DBusConnection</code> structure: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

<source lang="c">

/**

  * The main program that demonstrates a simple "fire & forget" RPC

  * method invocation.

  */

int main(int argc, char** argv) {

 

  /* Structure representing the connection to a bus. */

  DBusConnection* bus = NULL;

  /* The method call message. */

  DBusMessage* msg = NULL;

 

  /* D-Bus reports problems and exceptions using the DBusError

    structure. We allocate one in stack (so that we don't need to

    free it explicitly. */

  DBusError error;

 

  /* Message to display. */

  const char* dispMsg = "Hello World!";

  /* Text to use for the acknowledgement button. "" means default. */

  const char* buttonText = "";

  /* Type of icon to use in the dialog (1 = OSSO_GN_ERROR). We could

    have just used the symbolic version here as well, but that would

    have required pulling the LibOSSO-header files. And this example

    must work without LibOSSO, so this is why a number is used. */

  int iconType = 1;

 

  /* Clean the error state. */

  dbus_error_init(&error);

 

  printf("Connecting to Session D-Bus\n");

  bus = dbus_bus_get(DBUS_BUS_SESSION, &error);

  terminateOnError("Failed to open Session bus\n", &error);

  assert(bus != NULL);

</source>

To communicate errors, libdbus uses <code>DBusError</code> structures, whose contents are simple. The dbus_error_init is used for guaranteeing that the error structure contains a non-error state before connecting to the bus. If there is an error, it is handled in <code>terminateOnError</code>: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

<source lang="c">

/**

  * Utility to terminate if given DBusError is set.

  * Prints out the message and error before terminating.

  *

  * If error is not set, does nothing.

  *

  * NOTE: In real applications you should spend a moment or two

  *      thinking about the exit-paths from your application and

  *      whether you need to close/unreference all resources that you

  *      have allocated. In this program, we rely on the kernel to do

  *      all necessary cleanup (closing sockets, releasing memory),

  *      but in real life you need to be more careful.

  *

  *      One possible solution model to this is implemented in

  *      "flashlight", a simple program that is presented later.

  */

static void terminateOnError(const char* msg,

                            const DBusError* error) {

  if (dbus_error_is_set(error)) {

    fprintf(stderr, msg);

    fprintf(stderr, "DBusError.name: %s\n", error->name);

    fprintf(stderr, "DBusError.message: %s\n", error->message);

    /* If the program does not exit because of the error, freeing the

      DBusError needs to be done (with dbus_error_free(error)).

        dbus_error_free(error) would only free the error if it was

        set, so it is safe to use even when you are unsure. */

     exit(EXIT_FAILURE);

</source>

libdbus also contains some utility functions so that everything does not have to be coded manually. One such utility is <code>dbus_bus_name_has_owner</code>, that checks whether there is at least some process that owns the given well-known name at that moment: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

<source lang="c">

  /* Normally one would just do the RPC call immediately without

    to check whether a specific name even exists on a platform on

 

 

    startable/activateable by D-Bus. In that case, if the recipient

    recipient (a process that has been registered for that

    owned, our RPC call (below) fails anyway. */

</source>

 

Creating a method call using libdbus is slightly more tedious than using the higher-level interfaces. The process is separated into two steps: creating a message structure, and appending the arguments to the message: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

 

<source lang="c">

    Parameters are added later. The internal type of the message

    is DBUS_MESSAGE_TYPE_METHOD_CALL. */

  printf("Creating a message object\n");

  msg = dbus_message_new_method_call(SYSNOTE_NAME, /* destination */

                                    SYSNOTE_OPATH,  /* obj. path */

                                    SYSNOTE_IFACE,  /* interface */

                                    SYSNOTE_NOTE); /* method str */

  if (msg == NULL) {

    fprintf(stderr, "Ran out of memory when creating a message\n");

    exit(EXIT_FAILURE);

  }

 

  /*... Listing cut for brevity ...*/

 

  /* Add the arguments to the message. For the Note dialog, we need

    three arguments:

      arg0: (STRING) "message to display, in UTF-8"

      arg1: (UINT32) type of dialog to display. We use 1.

                      (libosso.h/OSSO_GN_ERROR).

      arg2: (STRING) "text to use for the ack button". "" means

                      default text (OK in our case).

 

    When listing the arguments, the type needs to be specified first

    (by using the libdbus constants) and then a pointer to the

    argument content needs to be given.

 

    NOTE: It is always a pointer to the argument value, not the value

          itself!

 

    We terminate the list with DBUS_TYPE_INVALID. */

  printf("Appending arguments to the message\n");

  if (!dbus_message_append_args(msg,

                                DBUS_TYPE_STRING, &dispMsg,

                                DBUS_TYPE_UINT32, &iconType,

                                DBUS_TYPE_STRING, &buttonText,

                                DBUS_TYPE_INVALID)) {

    fprintf(stderr, "Ran out of memory while constructing args\n");

    exit(EXIT_FAILURE);

  }

</source>

The arguments are encoded, so that their type code is followed by the pointer where the marshaling functions can find the content. The argument list is terminated with <code>DBUS_TYPE_INVALID</code>, so that the function knows where the argument list ends (since the function prototype ends with an ellipsis, ...). [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

<source lang="c">

  /* Set the "no-reply-wanted" flag into the message. This also means

    that we cannot reliably know whether the message was delivered or

    not, but because we do not have reply message handling here, it

    does not matter. The "no-reply" is a potential flag for the remote

    end so that they know that they do not need to respond to us.

    If the no-reply flag is set, the D-Bus daemon makes sure that the

    possible reply is discarded and not sent to us. */

  dbus_message_set_no_reply(msg, TRUE);

</source>

Once the message is fully constructed, it can be added to the sending queue of the program. Messages are not sent immediately by libdbus. Normally this allows the message queue to accumulate to more than one message, and all of the messages are sent at once to the daemon. This in turn cuts down the number of the necessary context switches. In this case, this message is the only message that the program ever sends, so the send queue is instructed to be flushed immediately, which in turn instructs the library to send all messages to the daemon without a delay: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

 

 

 

 

 

 

  /* Free-up the connection. libdbus attempts to share existing

    connections for the same client, so instead of closing down a

    connection object, it is unreferenced. The D-Bus library

    keeps an internal reference to each shared connection, to

     prevent accidental closing of shared connections before the

     library is finalized. */

  dbus_connection_unref(bus);

  bus = NULL;

  return EXIT_SUCCESS;

}

</source>

[[Image:libdbus-example.png|frame|center|alt=Screenshot of message ‘Hello World!’|The friendly error message, using low-level D-Bus]]

To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo 5 Developer Guide/GNU Build System#GNU Make and Makefiles|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System|GNU Build System]], if necessary): [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/Makefile libdbus-example/Makefile]

<source lang="make">

# Define a list of pkg-config packages we want to use

pkg_packages := dbus-glib-1

PKG_CFLAGS  := $(shell pkg-config -cflags $(pkg_packages))

PKG_LDFLAGS := $(shell pkg-config -libs $(pkg_packages))

# Additional flags for the compiler:

#    -g : Add debugging symbols

# -Wall : Enable most gcc warnings

ADD_CFLAGS := -g -Wall

# Combine user supplied, additional, and pkg-config flags

CFLAGS  := $(PKG_CFLAGS) $(ADD_CFLAGS) $(CFLAGS)

LDFLAGS := $(PKG_LDFLAGS) $(LDFLAGS)

</source>