Documentation/Maemo 5 Developer Guide/DBus/DBus Basics

= D-Bus =

For interprocess communications (IPC), maemo relies heavily on D-Bus. D-Bus makes it possible for programs to export their programming interfaces, so that other processes can call them in a consistent manner, without having to define a custom IPC protocol. Using these exported APIs is also language agnostic, so as long as programming language supports D-Bus, it can also access the interfaces.

A maemo-specific library called libosso provides helpful wrappers for D-BUS communication. It also contains the required functionality for every maemo application. Applications must be initialized using this library. With it, applications can connect to listen to system hardware state messages, such as "battery low". The library is used also for application state saving and auto-save functionality. Section LibOSSO Library [/node7.html#sec:libosso_library 6.18.2] of the chapter Application Development of Maemo Reference Manual provides a good introduction to libosso.

Introduction
D-Bus (the D originally stood for "Desktop") is a relatively new interprocess communication (IPC) mechanism designed to be used as a unified middleware layer in free desktop environments. Some example projects, where D-Bus is used, are GNOME and Hildon. Compared to other middleware layers for IPC, D-Bus lacks many of the more refined (and complicated) features, and thus is faster and simpler.

D-Bus does not directly compete with low-level IPC mechanisms, such as sockets, shared memory or message queues. Each of these mechanisms have their uses, which normally do not overlap the ones in D-Bus. Instead, D-Bus aims to provide higher level functionality, such as:


 * Structured name spaces
 * Architecture-independent data formatting
 * Support for the most common data elements in messages
 * A generic remote call interface with support for exceptions (errors)
 * A generic signaling interface to support "broadcast" type communication
 * Clear separation of per-user and system-wide scopes, which is important when dealing with multi-user systems
 * No bindings to any specific programming languages (while providing a design that readily maps to most higher level languages, via language-specific bindings)

The design of D-Bus benefits from the long experience of using other middleware IPC solutions in the desktop arena, and this has allowed the design to be optimized. Also, it does not yet suffer from "creeping featurism", e.g. having extra features just to satisfy niche use cases.

All this said, the main problem area that D-Bus aims to solve is facilitating easy IPC between related (often graphical) desktop software applications.

D-Bus has a very important role in maemo, as it is the IPC mechanism to use when using the services provided in the platform (and devices). Providing services over D-Bus is also the easiest way to assure component re-use from other applications.

D-Bus Architecture and Terminology
In D-Bus, the bus is a central concept. It is the channel through which applications can make the method calls, send signals and listen to signals. Two pre-defined buses exist: the session bus and the system bus.


 * The session bus is meant for communication between applications that are connected to the same desktop session, and normally started and run by one user (using the same user identifier, or UID).
 * The system bus is meant for communication when applications (or services), running with disparate sessions, wish to communicate with each other. The most common use for this bus is sending system-wide notifications, when system-wide events occur. Adding of a new storage device, network connectivity change events and shutdown-related events are all examples of when system bus would be the more suitable bus for communication.

In addition to the single system bus will exist, a system may a separate session bus for each desktop session. Because all user applications in a Maemo compatible device run with the same user ID, the device only has one session bus as well.

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 will also forward 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 (AF_UNIX) between the application and the bus daemon. The point-to-point aspect of D-Bus is however abstracted by the bus daemon, which will implement addressing and message passing functionality, so that applications do not need to care about which specific process will receive each method call or notification.

The above means that sending a message using D-Bus will always involve the following steps (under normal conditions):


 * Creation and sending of the message to the bus daemon. This will cause at minimum two context switches.
 * Processing of the message by the bus daemon and forwarding it to the target process. This will again cause at minimum two context switches.
 * The target application will receive the message. Depending on the message type, it will either need to acknowledge it, respond with a reply or ignore it. The last case is only possible with notifications (i.e., signals in D-Bus terminology). An acknowledgment or reply will cause further context switches.

Coupled together, the above rules mean that if planning to transfer large amounts of data between processes, D-Bus will not be the most efficient way to do it. The most efficient way would be using some kind of shared memory arrangement. However, it is often quite complex to implement correctly.

Addressing and Names in D-Bus
In order for the messages to reach the intended recipient, the IPC mechanism needs to support some form of addressing. The addressing scheme in D-Bus has been designed to be flexible, but at the same time efficient. Each bus has its private name space, which is not directly related to any other bus.

In order to send a message, a destination address is needed. It is formed in a hierarchical manner from the following elements:


 * The bus on which the message is to be sent. A bus is normally opened only once per application lifetime. The bus connection will then be used for sending and receiving messages for as long as necessary. This way, the target bus will form a transparent part of the message address (i.e., it is not specified separately for each message sent).
 * The well-known name for the service provided by the recipient. A close analogy to this would be the DNS system in Internet, where people normally use names to connect to services, instead of specific IP addresses providing the services. The idea in D-Bus well-known names is very similar, since the same service might be implemented in different ways in different applications. It should be noted, however, that currently most of the existing D-Bus services are "unique" in that each of them provides their own well-known name, and replacing one implementation with another is not common.
 * A well-known name consists of characters A-Z (lower or uppercase), dot characters, dashes and underscores. A well-known name must contain at least two dot-separated elements. Unlike DNS, the dots do not carry any additional information about management (zones), meaning that the well-known names are NOT hierarchical.
 * In order to reduce clashes in the D-Bus name space, it is recommended that the name is formed by reversing the order of labels of a DNS domain that you own. A similar approach is used in Java for package names.
 * Examples: org.maemo.Alert and org.freedesktop.Notifications.
 * Each service can contain multiple different objects, each of which provides a different (or same) service. In order to separate one object from another, object paths are used. A PIM information store, for example, might include separate objects to manage the contact information and synchronization.
 * Object paths look like file paths (elements separated with the character '/').
 * In D-Bus, it is also possible to make a "lazy binding", so that a specific function in the recipient will be called on all remote method calls, irrespective of object paths in the calls. This allows on-demand targeting of method calls, so that a user might remove a specific object in an address book service (using an object path similar to /org/maemo/AddressBook/Contacts/ShortName). Due to the limitations in characters that can be put into the object path, this is not recommended. A better way would be to supply the ShortName as a method call argument instead (as a UTF-8 formatted string).
 * It is common to form the object path using the same elements as in the well-known name, but replacing the dots with slashes, and appending a specific object name to the end. For example: /org/maemo/Alert/Alerter. It is a convention, but also solves a specific problem, when a process might re-use an existing D-Bus connection without explicitly knowing about it (using a library that encapsulates D-Bus functionality). Using short names here would increase the risk of name-space collisions within that process.
 * Similar to well-known names, object paths do not have inherent hierarchy, even if the path separator is used. The only place where some hierarchy might be seen because of path components is the introspection interface (which is out of the scope of this material).
 * In order to support object-oriented mapping, where objects are the units providing the service, D-Bus also implements a naming unit called the interface. The interface specifies the legal (i.e. defined and implemented) method calls, their parameters (called arguments in D-Bus) and possible signals. It is then possible to re-use the same interface across multiple separate objects implementing the same service, or more commonly, a single object can implement multiple different services. An example of the latter is the implementation of the org.freedesktop.DBus.Introspectable interface, which defines the method necessary to support D-Bus introspection (more about this later on). When using the GLib/D-Bus wrappers to generate parts of the D-Bus code, the objects will automatically also support the introspection interface.
 * Interface names use the same naming rules as well-known names. This might seem somewhat confusing at start, since well-known names serve a completely different purpose, but with time, one will get used to it.
 * For simple services, it is common to repeat the well-known name in the interface name. This is the most common scenario with existing services.
 * The last part of the message address is the member name. When dealing with remote procedure calls, this is also sometimes called method name, and when dealing with signals, signal name. The member name selects the procedure to call, or the signal to emit. It needs to be unique only within the interface that an object will implement.
 * Member names can have letters, digits and underscores in them. For example: RetrieveQuote.
 * For a more in-depth review on these, please see the Introductionto D-Bus page.

That about covers the most important rules in D-Bus addresses that one is likely to encounter. Below is an example of all four components that will also be used shortly to send a simple message (a method call) in the SDK:

   #define  SYSNOTE_NAME "org.freedesktop.Notifications"   #define  SYSNOTE_OPATH "/org/freedesktop/Notifications"   #define  SYSNOTE_IFACE "org.freedesktop.Notifications"   #define  SYSNOTE_NOTE "SystemNoteDialog" 

Even if switching to use the LibOSSO RPC functions (which encapsulate a lot of the D-Bus machinery), operations will still be performed with all of the D-Bus naming components.

Role of D-Bus in Maemo
D-Bus has been selected as de facto IPC mechanism in maemo, to carry messages between the various software components. The main reason for this is that a lot of software developed for the GNOME environment is already exposing its functionality through D-Bus. Using a generic interface, which is not bound to any specific service, makes it also easier to deal with different software license requirements.

The SDK unfortunately does not come with a lot of software that is exposed via D-Bus, but this document will be using one component of the application framework as demonstration (it works also in the SDK).

An item of particular interest is asking the notification framework component to display a Note dialog. The dialog is modal, which means that users cannot proceed in their graphical environment, unless they first acknowledge the dialog. Normally such GUI decisions should be avoided, but later in this document it will be discussed why and when this feature can be useful. N.B. The SystemNoteDialog member is an extension to the draft org.freedesktop.Notifications specification, and as such, is not documented in that draft.

The notification server is listening for method calls on the .freedesktop.Notifications well-known name. The object that implements the necessary interface is located at /org/freedesktop/Notifications object path. The method to display the note dialog is called SystemNoteDialog, and is defined in the org.freedesktop.Notifications D-Bus interface.

D-Bus comes with a handy tool to experiment with method calls and signals: dbus-send. The following snippet will attempt to use it to display the dialog:

[sbox-DIABLO_X86: ~] &gt; run-standalone.sh dbus-send --print-reply \ --type=method_call --dest=org.freedesktop.Notifications \ /org/freedesktop/Notifications org.freedesktop.Notifications Error org.freedesktop.DBus.Error.UnknownMethod: Method "Notifications" with signature "" on interface "org.freedesktop" doesn't exist

Parameters for dbus-send:


 * : (implicit since default) which bus to use for sending (the other option being system)
 * : ask the tool to wait for a reply to the method call, and print out the results (if any)
 * : instead of sending a signal (which is the default), make a method call
 * : the well-known name for the target service
 * : object path within the target process that implements the interface
 * : (incorrectly specified) interface name defining the method

When using dbus-send, extra care needs to be taken, when specifying the interface and member names. The tool expects both of them to be combined into one parameter (without spaces in between). Thus, the command line needs to be modified a bit before a new try:

[sbox-DIABLO_X86: ~] &gt; run-standalone.sh dbus-send --print-reply \ --type=method_call --dest=org.freedesktop.Notifications \ /org/freedesktop/Notifications org.freedesktop.Notifications.SystemNoteDialog Error org.freedesktop.DBus.Error.UnknownMethod: Method "SystemNoteDialog" with signature "" on interface "org.freedesktop.Notifications" doesn't exist

Seems that the RPC call is still missing something. Most RPC methods will expect a series of parameters (or arguments, as D-Bus calls them).

SystemNoteDialog expects these three parameters (in the following order):


 * string: The message to display
 * uint32: An unsigned integer giving the style of the dialog. Styles 0-4 mean different icons, and style 5 is a special animated "progress indicator" dialog.
 * string: Message to use for the "Ok" button that the user needs to press to dismiss the dialog. Using an empty string will cause the default text to be used (which is "Ok").

Arguments are specified by giving the argument type and its contents separated with a colon as follows:

[sbox-DIABLO_X86: ~] &gt; 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 -&gt; dest=:1.15 uint32 4

Since dbus-send was asked to print replies, the reply will come out as a single unsigned integer, with value of 4. This is the unique number for this notification, and could be used with the CloseNotification method of the Notifications interface to pre-emptively close the dialog. It might be especially useful, if the software can notice that some warning condition has ended, and there is no need to bother the user with the warning anymore.

Assuming that the above command is run while the application framework is already running, the end result should more or less look like this:



If the command is repeated multiple times, one will notice that the notification service is capable of displaying only one dialog at a time. This makes sense, as the dialog is modal anyway. It can also be noticed that the method calls are queued somewhere, and not lost (i.e. the notification service will display all of the requested dialogs). The service also acknowledges the RPC method call without delay (which is not always the obvious thing to do), giving a different return value each time (incrementing by one each time).

Programming Directly with Libdbus
The lowest level library to use for D-Bus programming is libdbus. Using this library directly is discouraged, mostly because it contains a lot of specific code to integrate into various main-loop designs that the higher level language bindings use.

The libdbus API reference documentation /node19.html contains a helpful note:

  /**  ''  * Uses the low-level libdbus which shouldn't be used directly.    * As the D-Bus API reference puts it "If you use this low-level API     * directly, you're signing up for some pain".    */ '' </tt>

At this point, this example will ignore the warnings, and use the library to implement a simple program that will replicate the dbus-send example that was seen before. In order to do this with the minimum amount of code, the code will not process (or expect) any responses to the method call. It will, however, demonstrate the bare minimum function calls that are needed to use to send messages on the bus.

The first step is to introduce the necessary header files. libdbus-example/dbus-example.c

  <font color="#000080"> #include  <font color="#FF0000">&lt;dbus/dbus.h&gt;  '' <font color="#9A1900">/* Pull in all of D-Bus headers. */   <font color="#000080"> #include   <font color="#FF0000">&lt;stdio.h&gt;      <font color="#9A1900">/* printf, fprintf, stderr */ ''  <font color="#000080"> #include  <font color="#FF0000">&lt;stdlib.h&gt;     <font color="#9A1900">/* EXIT_FAILURE, EXIT_SUCCESS */   <font color="#000080"> #include  <font color="#FF0000">&lt;assert.h&gt;     <font color="#9A1900">/* assert */   <font color="#9A1900">/* Symbolic defines for the D-Bus well-known name, interface, object  '' <font color="#9A1900">  path and method name that we're going to use. */ ''  <font color="#000080"> #define  SYSNOTE_NAME  <font color="#FF0000">"org.freedesktop.Notifications"  <font color="#000080"> #define  SYSNOTE_OPATH <font color="#FF0000">"/org/freedesktop/Notifications"  <font color="#000080"> #define  SYSNOTE_IFACE <font color="#FF0000">"org.freedesktop.Notifications"  <font color="#000080"> #define  SYSNOTE_NOTE <font color="#FF0000">"SystemNoteDialog" </tt>

Unlike the rest of the code in this material, dbus-example does not use GLib or other support libraries (other than libdbus). This explains why it uses printf and other functions that would normally be replaced with GLib equivalents.

Connecting to the session bus will (hopefully) yield a DBusConnection structure: libdbus-example/dbus-example.c

  <font color="#9A1900">/**   <font color="#9A1900"> * The main program that demonstrates a simple "fire &amp; forget" RPC  '' <font color="#9A1900"> * method invocation.   <font color="#9A1900"> */ '' <font color="#009900">int  <font color="#000000">main   <font color="#990000">(  <font color="#009900">int argc <font color="#990000">,  <font color="#009900">char  <font color="#990000"> ** argv <font color="#990000">)  <font color="#FF0000">{ '' <font color="#9A1900">/* Structure representing the connection to a bus. */ ''   DBusConnection <font color="#990000"> * bus <font color="#990000"> = NULL <font color="#990000"> ; '' <font color="#9A1900">/* The method call message. */ ''   DBusMessage <font color="#990000"> * msg <font color="#990000"> = NULL <font color="#990000"> ;  <font color="#9A1900">/* D-Bus will report problems and exceptions using the DBusError  '' <font color="#9A1900">    structure. We'll allocate one in stack (so that we don't need to   <font color="#9A1900">     free it explicitly. */     DBusError error <font color="#990000"> ;     <font color="#9A1900">/* Message to display. */      <font color="#0000FF">const   <font color="#009900">char  <font color="#990000"> * dispMsg <font color="#990000"> =  <font color="#FF0000">"Hello World!"  <font color="#990000"> ;     <font color="#9A1900">/* Text to use for the acknowledgement button. "" means default. */      <font color="#0000FF">const   <font color="#009900">char  <font color="#990000"> * buttonText <font color="#990000"> =  <font color="#FF0000">""  <font color="#990000"> ;     <font color="#9A1900">/* Type of icon to use in the dialog (1 = OSSO_GN_ERROR). We could    <font color="#9A1900">     have just used the symbolic version here as well, but that would    <font color="#9A1900">     have required pulling the LibOSSO-header files. And this example '' '' <font color="#9A1900">    must work without LibOSSO, so this is why a number is used. */ ''   <font color="#009900">int iconType <font color="#990000"> =  <font color="#993399">1  <font color="#990000"> ; '' <font color="#9A1900">/* Clean the error state. */ ''    <font color="#000000">dbus_error_init   <font color="#990000">(&amp; error <font color="#990000">);  <font color="#000000">printf  <font color="#990000">(  <font color="#FF0000">"Connecting to Session D-Bus  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">); bus <font color="#990000"> =  <font color="#000000">dbus_bus_get   <font color="#990000">( DBUS_BUS_SESSION <font color="#990000">,  <font color="#990000">&amp; error <font color="#990000">);  <font color="#000000">terminateOnError  <font color="#990000">(  <font color="#FF0000">"Failed to open Session bus  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">,  <font color="#990000">&amp; error <font color="#990000">);  <font color="#000000">assert  <font color="#990000">( bus <font color="#990000"> != NULL <font color="#990000">); </tt>

N.B. Libdbus will attempt to share existing connection structures when the same process is connecting to the same bus. This is done to avoid the somewhat costly connection set-up time. Sharing connections is beneficial, when the program is using libraries that would also open their own connections to the same buses.

In order to communicate errors, libdbus uses DBusError structures, whose contents are pretty simple. The dbus_error_init will be used to guarantee that the error structure contains a non-error state before connecting to the bus. If there is an error, it will be handled in terminateOnError: libdbus-example/dbus-example.c

  <font color="#9A1900">/**  '' <font color="#9A1900"> * Utility to terminate if given DBusError is set.   <font color="#9A1900"> * Will print out the message and error before terminating.   <font color="#9A1900"> * '' '' <font color="#9A1900"> * If error is not set, will do nothing.   <font color="#9A1900"> * ''  <font color="#9A1900"> * NOTE: In real applications you should spend a moment or two   <font color="#9A1900"> *      thinking about the exit-paths from your application and   <font color="#9A1900"> *      whether you need to close/unreference all resources that you  '' <font color="#9A1900"> *      have allocated. In this program, we rely on the kernel to do ''  <font color="#9A1900"> *      all necessary cleanup (closing sockets, releasing memory),  '' <font color="#9A1900"> *      but in real life you need to be more careful.   <font color="#9A1900"> * ''  <font color="#9A1900"> *      One possible solution model to this is implemented in  '' <font color="#9A1900"> *      "flashlight", a simple program that is presented later.   <font color="#9A1900"> */ ''  <font color="#0000FF">static  <font color="#009900">void   <font color="#000000">terminateOnError   <font color="#990000">(   <font color="#0000FF">const   <font color="#009900">char  <font color="#990000"> * msg <font color="#990000">,                                <font color="#0000FF">const  DBusError <font color="#990000"> * error <font color="#990000">)  <font color="#FF0000">{  <font color="#000000">assert  <font color="#990000">( msg <font color="#990000"> != NULL <font color="#990000">);  <font color="#000000">assert  <font color="#990000">( error <font color="#990000"> != NULL <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">(   <font color="#000000">dbus_error_is_set   <font color="#990000">( error <font color="#990000">))  <font color="#FF0000">{  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">, msg <font color="#990000">);  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">,  <font color="#FF0000">"DBusError.name: %s  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">, error <font color="#990000">-&gt; name <font color="#990000">);  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">,  <font color="#FF0000">"DBusError.message: %s  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">, error <font color="#990000">-&gt; message <font color="#990000">);  <font color="#9A1900">/* If the program wouldn't exit because of the error, freeing the  '' <font color="#9A1900">      DBusError needs to be done (with dbus_error_free(error)).   <font color="#9A1900">       NOTE: ''  <font color="#9A1900">        dbus_error_free(error) would only free the error if it was  '' <font color="#9A1900">        set, so it is safe to use even when you're unsure. */ ''      <font color="#000000">exit   <font color="#990000">( EXIT_FAILURE <font color="#990000">); <font color="#FF0000">} <font color="#FF0000">} </tt>

libdbus also contains some utility functions, so that everything does not have to be coded manually. One such utility is dbus_bus_name_has_owner that checks, whether there is at least some process that owns the given well-known name at that moment: libdbus-example/dbus-example.c

  <font color="#9A1900">/* Normally one would just do the RPC call immediately without  '' <font color="#9A1900">    checking for name existence first. However, sometimes it is useful ''  <font color="#9A1900">    to check whether a specific name even exists on a platform on  '' <font color="#9A1900">    which you are planning to use D-Bus.   <font color="#9A1900">     In our case it acts as a reminder to run this program using the '' '' <font color="#9A1900">    run-standalone.sh script when running in the SDK.   <font color="#9A1900">     The existence check is not necessary if the recipient is '' '' <font color="#9A1900">    startable/activateable by D-Bus. In that case, if the recipient ''  <font color="#9A1900">    is not already running, the D-Bus daemon will start the   <font color="#9A1900">    recipient (a process that has been registered for that   '' <font color="#9A1900">     well-known name) and then passes the message to it. This ''  <font color="#9A1900">    automatic starting mechanism will avoid the race condition   <font color="#9A1900">    discussed below and also makes sure that only one instance of  '' <font color="#9A1900">    the service is running at any given time. */ ''    <font color="#000000">printf   <font color="#990000">(  <font color="#FF0000">"Checking whether the target name exists (" SYSNOTE_NAME <font color="#FF0000">") <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">(!   <font color="#000000">dbus_bus_name_has_owner   <font color="#990000">( bus <font color="#990000">, SYSNOTE_NAME <font color="#990000">,  <font color="#990000">&amp; error <font color="#990000">))  <font color="#FF0000">{  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">,  <font color="#FF0000">"Name has no owner on the bus!  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#0000FF">return  EXIT_FAILURE <font color="#990000"> ; <font color="#FF0000">}  <font color="#000000">terminateOnError  <font color="#990000">(  <font color="#FF0000">"Failed to check for name ownership  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">,  <font color="#990000">&amp; error <font color="#990000">); '' <font color="#9A1900">/* Someone on the Session bus owns the name. So we can proceed in '' '' <font color="#9A1900">    relative safety. There is a chance of a race. If the name owner ''  <font color="#9A1900">    decides to drop out from the bus just after we check that it is  '' <font color="#9A1900">    owned, our RPC call (below) will fail anyway. */ '' </tt>

Creating a method call using libdbus is slightly more tedious than using the higher-level interfaces, but not very difficult. The process is separated into two steps: creating a message structure, and appending the arguments to the message: libdbus-example/dbus-example.c

 '' <font color="#9A1900">/* Construct a DBusMessage that represents a method call.   <font color="#9A1900">     Parameters will be added later. The internal type of the message '' '' <font color="#9A1900">    will be DBUS_MESSAGE_TYPE_METHOD_CALL. */ ''    <font color="#000000">printf   <font color="#990000">(  <font color="#FF0000">"Creating a message object  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">); msg <font color="#990000"> =  <font color="#000000">dbus_message_new_method_call   <font color="#990000">( SYSNOTE_NAME <font color="#990000">,   <font color="#9A1900">/* destination */                                        SYSNOTE_OPATH <font color="#990000">,   <font color="#9A1900">/* obj. path */                                        SYSNOTE_IFACE <font color="#990000">,   <font color="#9A1900">/* interface */                                        SYSNOTE_NOTE <font color="#990000">);   <font color="#9A1900">/* method str */   <font color="#0000FF">if  <font color="#990000">( msg <font color="#990000"> == NULL <font color="#990000">)  <font color="#FF0000">{  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">,  <font color="#FF0000">"Ran out of memory when creating a message  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#000000">exit  <font color="#990000">( EXIT_FAILURE <font color="#990000">); <font color="#FF0000">} '' <font color="#9A1900">/*... Listing cut for brevity ...*/ '' '' <font color="#9A1900">/* Add the arguments to the message. For the Note dialog, we need ''  <font color="#9A1900">    three arguments:   <font color="#9A1900">      arg0: (STRING) "message to display, in UTF-8"  '' <font color="#9A1900">      arg1: (UINT32) type of dialog to display. We will use 1.   <font color="#9A1900">                      (libosso.h/OSSO_GN_ERROR).   <font color="#9A1900">       arg2: (STRING) "text to use for the ack button". "" means '' '' <font color="#9A1900">                     default text (OK in our case).   <font color="#9A1900">     When listing the arguments, the type needs to be specified first ''  <font color="#9A1900">    (by using the libdbus constants) and then a pointer to the  '' <font color="#9A1900">    argument content needs to be given.   <font color="#9A1900">     NOTE: It is always a pointer to the argument value, not the value '' '' <font color="#9A1900">          itself!   <font color="#9A1900">     We terminate the list with DBUS_TYPE_INVALID. */ ''    <font color="#000000">printf   <font color="#990000">(  <font color="#FF0000">"Appending arguments to the message  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#0000FF">if  <font color="#990000">(!   <font color="#000000">dbus_message_append_args   <font color="#990000">( msg <font color="#990000">, DBUS_TYPE_STRING <font color="#990000">, <font color="#990000">&amp; dispMsg <font color="#990000">, DBUS_TYPE_UINT32 <font color="#990000">, <font color="#990000">&amp; iconType <font color="#990000">, DBUS_TYPE_STRING <font color="#990000">, <font color="#990000">&amp; buttonText <font color="#990000">, DBUS_TYPE_INVALID <font color="#990000">)) <font color="#FF0000">{  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">,  <font color="#FF0000">"Ran out of memory while constructing args  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#000000">exit  <font color="#990000">( EXIT_FAILURE <font color="#990000">); <font color="#FF0000">} </tt>

When arguments are appended to the message, their content is copied, and possibly converted into a format that will be sent over the connection to the daemon. This process is called marshaling, and is a common feature to most RPC systems. The method call will require two parameters (as before), the first being the text to display, and the second one being the style of the icon to use. Parameters passed to libdbus are always passed by address. This is different from the higher level libraries, and this will be discussed later.

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 DBUS_TYPE_INVALID, so that the function knows where the argument list ends (since the function prototype ends with an ellipsis, ...). libdbus-example/dbus-example.c

 '' <font color="#9A1900">/* Set the "no-reply-wanted" flag into the message. This also means ''  <font color="#9A1900">    that we cannot reliably know whether the message was delivered or   <font color="#9A1900">    not, but since we don't have reply message handling here, it  '' <font color="#9A1900">    doesn't matter. The "no-reply" is a potential flag for the remote '' '' <font color="#9A1900">    end so that they know that they don't need to respond to us.   <font color="#9A1900">     If the no-reply flag is set, the D-Bus daemon makes sure that the '' '' <font color="#9A1900">    possible reply is discarded and not sent to us. */ ''    <font color="#000000">dbus_message_set_no_reply   <font color="#990000">( msg <font color="#990000">, TRUE <font color="#990000">); </tt>

Setting the no-reply-flag effectively tells the bus daemon that even if there is a reply coming back for this RPC method, it is not wanted. In this case, the daemon will not send one.

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 will be sent at once to the daemon. This in turn cuts down the number of context switches necessary. In this case, this will be the only message that the program ever sends, so the send queue is instructed to be flushed immediately, and this will instruct the library to send all messages to the daemon without a delay: libdbus-example/dbus-example.c

  <font color="#000000">printf   <font color="#990000">(  <font color="#FF0000">"Adding message to client's send-queue  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#9A1900">/* We could also get a serial number (dbus_uint32_t) for the message  '' <font color="#9A1900">    so that we could correlate responses to sent messages later. In ''  <font color="#9A1900">    our case there won't be a response anyway, so we don't care about  '' <font color="#9A1900">    the serial, so we pass a NULL as the last parameter. */ ''    <font color="#0000FF">if   <font color="#990000">(!   <font color="#000000">dbus_connection_send   <font color="#990000">( bus <font color="#990000">, msg <font color="#990000">, NULL <font color="#990000">))  <font color="#FF0000">{  <font color="#000000">fprintf  <font color="#990000">( stderr <font color="#990000">,  <font color="#FF0000">"Ran out of memory while queueing message  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#000000">exit  <font color="#990000">( EXIT_FAILURE <font color="#990000">); <font color="#FF0000">}  <font color="#000000">printf  <font color="#990000">(  <font color="#FF0000">"Waiting for send-queue to be sent out  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#000000">dbus_connection_flush  <font color="#990000">( bus <font color="#990000">);  <font color="#000000">printf  <font color="#990000">(  <font color="#FF0000">"Queue is now empty  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">); </tt>

After the message is sent, the reserved resources should be freed. Here, the first one to be freed is the message, and then the connection structure. libdbus-example/dbus-example.c

  <font color="#000000">printf   <font color="#990000">(  <font color="#FF0000">"Cleaning up  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">); '' <font color="#9A1900">/* Free up the allocated message. Most D-Bus objects have internal ''  <font color="#9A1900">    reference count and sharing possibility, so _unref functions  '' <font color="#9A1900">    are quite common. */ ''    <font color="#000000">dbus_message_unref   <font color="#990000">( msg <font color="#990000">); msg <font color="#990000"> = NULL <font color="#990000"> ; '' <font color="#9A1900">/* Free-up the connection. libdbus attempts to share existing ''  <font color="#9A1900">    connections for the same client, so instead of closing down a  '' <font color="#9A1900">    connection object, it is unreferenced. The D-Bus library will ''  <font color="#9A1900">    keep an internal reference to each shared connection, to   <font color="#9A1900">    prevent accidental closing of shared connections before the  '' <font color="#9A1900">    library is finalized. */ ''    <font color="#000000">dbus_connection_unref   <font color="#990000">( bus <font color="#990000">); bus <font color="#990000"> = NULL <font color="#990000"> ;  <font color="#000000">printf  <font color="#990000">(  <font color="#FF0000">"Quitting (success)  <font color="#CC33CC">\n  <font color="#FF0000">"  <font color="#990000">);  <font color="#0000FF">return  EXIT_SUCCESS <font color="#990000"> ; <font color="#FF0000">} </tt>

After building the program, attempt to run it:

[sbox-DIABLO_X86: ~/libdbus-example] &gt; ./dbus-example Connecting to Session D-Bus process 6120: D-Bus library appears to be incorrectly set up; failed to read machine uuid: Failed to open "/var/lib/dbus/machine-id": No such file or directory See the manual page for dbus-uuidgen to correct this issue. D-Bus not built with -rdynamic so unable to print a backtrace Aborted (core dumped)

The D-Bus library needs environmental variables set correctly in order to locate the session daemon. The command was not prepended with run-standalone.sh, and this caused the library to internally abort the execution. Normally, dbus_bus_get would have returned a NULL pointer and set the error structure, but the version on the 4.1 SDK will assert internally in this condition, and programs cannot avoid the abort. After correcting this, try again:

[sbox-DIABLO_X86: ~/libdbus-example] &gt; run-standalone.sh ./dbus-example Connecting to Session D-Bus Checking whether the target name exists (org.freedesktop.Notifications) Creating a message object Appending arguments to the message Adding message to client's send-queue Waiting for send-queue to be sent out Queue is now empty Cleaning up Quitting (success) /dev/dsp: No such file or directory

The error message (about /dev/dsp) printed to the same terminal where AF was started is normal (in SDK). Displaying the Note dialog normally also causes an "Alert" sound to be played. The sound system has not been setup in the SDK, so the notification component complains about failing to open the sound device.

<font size="-1">The friendly error message, using low-level D-Bus

In order to get libdbus integrated into makefiles, pkg-config has to be used. One possible solution is presented below (see section GNU Make and Makefiles [/node5.html#sec:gnu_make_makefiles 4.2] in chapter GNU Build System, if necessary): libdbus-example/Makefile

  <font color="#9A1900"> # Define a list of pkg-config packages we want to use  pkg_packages <font color="#990000"> := dbus-glib- <font color="#993399">1 PKG_CFLAGS <font color="#990000"> :=  <font color="#009900">$( shell pkg-config -cflags <font color="#009900">$(pkg_packages)) PKG_LDFLAGS <font color="#990000"> := <font color="#009900">$( shell pkg-config -libs <font color="#009900">$(pkg_packages))  <font color="#9A1900"> # Additional flags for the compiler:   <font color="#9A1900"> #   -g : Add debugging symbols   <font color="#9A1900"> # -Wall : Enable most gcc warnings  ADD_CFLAGS <font color="#990000"> := -g -Wall  <font color="#9A1900"> # Combine user supplied, additional, and pkg-config flags  CFLAGS <font color="#990000"> :=  <font color="#009900">$(PKG_CFLAGS)  <font color="#009900">$(ADD_CFLAGS)  <font color="#009900">$(CFLAGS) LDFLAGS <font color="#990000"> := <font color="#009900">$(PKG_LDFLAGS)  <font color="#009900">$(LDFLAGS) </tt>

The above shows one possibility to integrate user-supplied variables into makefiles, so that they will still be passed along the toolchain. This allows the user to execute make with custom flags, overriding those that are introduced via other means. For example: "CFLAGS='-g0' make" would result in -g0 being interpreted after the -g that is in the Makefile, and this would lead to debugging symbols being disabled. Environmental variables can be taken into account in exactly the same way.

For more complicated programs, it is likely that multiple different CFLAGS settings are required for different object files or multiple different programs that are being built. In that case, the combining in each target rule would be performed separately. In this material, all the example programs are self-contained and rather simple, so the above mechanism will be used in all the example makefiles.