D-Bus Tutorial

At work, we use D-Bus to communicate from one process to another. However, when looking for information on how exactly to use D-Bus, the documentation that I came across was rather useless. So, here’s a tutorial on how to use D-Bus using both the official Java bindings, and C++ bindings using dbus-cxx.

I recommend that you download the zip file containing all of the code used in this tutorial, as I do not give complete code samples in this tutorial for brevity, and because there is a lot of boilerplate code. The code samples are also fully commented in order to help you understand what is going on.

Part I: Getting what you need

For this, you’re going to need a few things. First, make sure that you have the dbus development headers installed. You can check this by using synaptic or whatever package manager you use.

Next, make sure that you have dbus-cxx. You should check it out from the dbus-cxx SVN site; it is on Launchpad, but that version is out of date. There are directions at the dbus-cxx website. The examples on the dbus-cxx website are fairly useful, so that’s a good place to go for more help. Unfortunately, they suffer from a lack of explanation, so this tutorial will attempt to remedy that.

For Java, make sure that you have the jar and the required files. This information can be found at the D-Bus website.

I recommend that you also install qdbus. qdbus allows you to send out events and method calls on the D-Bus. qdbus can be installed by installing libqt4-dbus.

Other useful utilities are dbus-monitor and dbus-send, which should be installed as part of the standard D-Bus installation.

Part II: Some Background

Let’s talk a little bit about what D-Bus is. In short, D-Bus is an IPC(Inter-Process Communication) and RPC(Remote Procedure Call) mechanism. This means that you use D-Bus to talk between processes. There are several other ways of communicating between processes, such as using a TCP connection between processes. On *nix based systems, you could also create a pipe to link two processes together. Shared memory is another option. Or, you could send signals from one program to another.

All of these options have drawbacks and advantages. D-Bus takes a slightly different route, where all messages are sent through a central bus system and then forwarded on to the proper recipients, similar to how an IP packet works.

Part III: Looking at what is on the D-Bus

This part uses qdbus to inspect what services are currently on the D-Bus. Let’s open up dbus-monitor in one terminal. Now, in another terminal run qdbus. Here’s the output that I got with qdbus:

:1.0
org.gnome.SessionManager
:1.10
:1.11
:1.12
org.gnome.seahorse
:1.13
:1.14
:1.15
org.pulseaudio.Server
:1.16
org.gnome.Panel
:1.17
:1.2
org.gnome.GConf
:1.20
org.gnome.ScreenSaver
:1.23
org.gnome.VolumeControlApplet
:1.24
org.gnome.PowerManager
:1.25
org.gnome.Nautilus
:1.26
:1.27
org.freedesktop.NetworkManagerUserSettings
:1.28
:1.29
:1.30
:1.31
:1.32
:1.33
:1.34
:1.35
:1.36
org.gtk.Private.GduVolumeMonitor
:1.37
org.gtk.Private.GPhoto2VolumeMonitor
:1.38
:1.39
:1.4
org.freedesktop.Notifications
:1.40
:1.41
:1.42
:1.43
org.blueman.Applet
:1.44
:1.45
:1.46
org.openobex
:1.47
:1.48
:1.5
org.gnome.keyring
:1.55
org.gtk.vfs.Metadata
:1.60
org.gnome.Terminal.Display_0_0
:1.61
:1.64
:1.65
:1.66
:1.67
:1.68
:1.69
:1.7
org.gnome.SettingsDaemon
:1.75
:1.79
:1.8
:1.80
:1.9
org.gtk.vfs.Daemon
org.freedesktop.DBus

Your output may differ. If you look at the terminal with dbus-monitor running in it, you’ll notice how there was a lot of output. Those are messages that are being sent over the bus. In fact, there’s too much to really go over now, so we’ll come back to that at a later point.

The output from qdbus is a little more sensible. The services are identified by their names, i.e. org.freedesktop.Notifications. These are the bus names(note that these names must be unique). Now, let’s look at a specific service, in this case org.freedesktop.Notifications.
Here’s the output that I get:

/
/org
/org/freedesktop
/org/freedesktop/Notifications

The output that you get here are the paths. Now, let’s investigate the path /org/freedesktop/Notifications.

$ qdbus org.freedesktop.Notifications /org/freedesktop/Notifications
method QString org.freedesktop.DBus.Introspectable.Introspect()
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface, QString propname)
method void org.freedesktop.DBus.Properties.Set(QString interface, QString propname, QDBusVariant value)
method void org.freedesktop.Notifications.CloseNotification(uint id)
method QStringList org.freedesktop.Notifications.GetCapabilities()
method QString org.freedesktop.Notifications.GetServerInformation(QString& return_vendor, QString& return_version, QString& return_spec_version)

As you can see, there are a few methods on here. NOTE: Not all of the methods here are shown. I am not sure why, but I believe that it is because qdbus cannot send to all of these methods.

Notice how the first method that is shown is called Introspect. All objects that are on the D-Bus must implement this method. When called, it returns an XML string defining what methods are on this object at this path. So, let’s try calling the Introspect method.

$ qdbus org.freedesktop.Notifications /org/freedesktop/Notifications Introspect
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
<interface name="org.freedesktop.DBus.Introspectable">
<method name="Introspect">
<arg name="data" direction="out" type="s"/>
</method>
</interface>
<interface name="org.freedesktop.DBus.Properties">
<method name="Get">
<arg name="interface" direction="in" type="s"/>
<arg name="propname" direction="in" type="s"/>
<arg name="value" direction="out" type="v"/>
</method>
<method name="Set">
<arg name="interface" direction="in" type="s"/>
<arg name="propname" direction="in" type="s"/>
<arg name="value" direction="in" type="v"/>
</method>
<method name="GetAll">
<arg name="interface" direction="in" type="s"/>
<arg name="props" direction="out" type="a{sv}"/>
</method>
</interface>
<interface name="org.freedesktop.Notifications">
<method name="GetServerInformation">
<arg name="return_name" type="s" direction="out"/>
<arg name="return_vendor" type="s" direction="out"/>
<arg name="return_version" type="s" direction="out"/>
<arg name="return_spec_version" type="s" direction="out"/>
</method>
<method name="GetCapabilities">
<arg name="return_caps" type="as" direction="out"/>
</method>
<method name="CloseNotification">
<arg name="id" type="u" direction="in"/>
</method>
<method name="Notify">
<arg name="app_name" type="s" direction="in"/>
<arg name="id" type="u" direction="in"/>
<arg name="icon" type="s" direction="in"/>
<arg name="summary" type="s" direction="in"/>
<arg name="body" type="s" direction="in"/>
<arg name="actions" type="as" direction="in"/>
<arg name="hints" type="a{sv}" direction="in"/>
<arg name="timeout" type="i" direction="in"/>
<arg name="return_id" type="u" direction="out"/>
</method>
</interface>
</node>

Notice how we now have a list of all methods that are on the D-Bus from the address org.freedesktop.Notifications and the path /org/freedesktop/Notifications. As you can see, there is also a new method called Notify. This method is what pops up the notification window in one corner of your screen. Depending on the version of the notification-daemon that you have installed, it may also allow you to click on it.

dbus-cxx and dbus-java both have tools that help you make adapters from these XML documents. However, it’s also possible to make interfaces on your own, so we will not bother with the tools, as I think that it will make more sense to you if you don’t start out with the tools.

So at this point, we now have a basic understanding of what is on the D-Bus, and how we can see what is on there. Let’s go and make some programs that talk to each other.

Part IV: A Basic Java program(Receiving)

Note: The sources can be found  here . This includes projects already set up for Eclipse.
To compile, simply make sure that you have libdbus-java-2.7.jar on your classpath, and when you run it make sure that you set -Djava.library.path=<path> to the location of unix-java.so if it is not set automatically.

Note: The dbus-cxx library version 0.7.0 does not have support for variants. The SVN version contains variants(sending only) as of SVN version 193.

Note: dbus-cxx 0.7.0 appears to hang when calling void methods. Thus, all methods we will call using dbus-cxx will return a value – this has been fixed in SVN, but there is no official release with this fixed as of this time.

Let’s start with receiving messages first. For Java, any method that you want to export onto the D-Bus must be defined in an interface which extends DBusInterface. Here’s a simple interface, which will echo out whatever string we give it and return an int.

package com.rm5248;

import org.freedesktop.dbus.DBusInterface;

public interface ReceiveInterface extends DBusInterface {

public int echoMessage(String str);

}

Our main class is just JavaReceive, which implements ReceiveInterface. The implementation of this method simply prints the string to System.out, and returns 0. Now, let’s put this object onto the D-Bus and call it. This is actually quite simple. In fact, this is all the code that is required:

try {
    DBusConnection conn = DBusConnection.getConnection(DBusConnection.SESSION);
    conn.requestBusName("com.rm5248");
    conn.exportObject("/", new JavaReceive());
} catch (DBusException e) {
    e.printStackTrace();
}

What does this code do? Well, the first part gets a new connection to the dbus on the session bus(there is another bus, the system bus, but for most purposes the session bus should be good). Once we have a connection, we request a name. This name could be really whatever we want, but generally I use the Java package style. We now export an object onto the D-Bus. The first parameter is the path of the object. In the case of the notifications that we looked at before, this would be /org/freedesktop/Notifications. For simplicity, we are simply setting it to /. The second parameter is a class which implements an interface which extends the DBusInterface.

Now, let’s look on the D-Bus to see what we have.

:1.0
org.gnome.SessionManager
:1.10
:1.104
com.rm5248
:1.106
:1.11
:1.12
org.gnome.seahorse
:1.13
:1.14
:1.15
org.pulseaudio.Server
:1.16
org.gnome.Panel
:1.17
:1.2
org.gnome.GConf
:1.20
org.gnome.ScreenSaver
:1.23
org.gnome.VolumeControlApplet
:1.24
org.gnome.PowerManager
:1.25
org.gnome.Nautilus
:1.26
:1.27
org.freedesktop.NetworkManagerUserSettings
:1.28
:1.29
:1.30
:1.31
:1.32
:1.33
:1.34
:1.35
:1.36
org.gtk.Private.GduVolumeMonitor
:1.37
org.gtk.Private.GPhoto2VolumeMonitor
:1.38
:1.39
:1.4
org.freedesktop.Notifications
:1.40
:1.41
:1.42
:1.43
org.blueman.Applet
:1.44
:1.45
:1.46
org.openobex
:1.47
:1.48
:1.5
org.gnome.keyring
:1.55
org.gtk.vfs.Metadata
:1.60
org.gnome.Terminal.Display_0_0
:1.61
:1.64
:1.65
:1.66
:1.67
:1.68
:1.69
:1.7
org.gnome.SettingsDaemon
:1.8
:1.9
org.gtk.vfs.Daemon
:1.94
:1.95
:1.96
org.freedesktop.DBus

If you look, you’ll notice how we now have a new com.rm5248 entry. Let’s look at what qdbus says that entry contains:

$ qdbus com.rm5248 /
method int com.rm5248.ReceiveInterface.echoMessage(QString)
method QString org.freedesktop.DBus.Introspectable.Introspect()
method void org.freedesktop.DBus.Peer.Ping()

There is the standard Introspect method, as well as an echoMessage method that takes a QString(this is the same as a regular string, but qdbus changes all of the types to types that are in Qt).

Now, let’s call the echo method using qdbus.

$ qdbus com.rm5248 / com.rm5248.ReceiveInterface.echoMessage hello

If you look at the output for your Java program, notice how it has printed out the string ‘hello’! The ‘0’ that is printed underneath the qdbus call is the return of the method. Since we simply return 0, a 0 is printed.

Notice how we called the method. It’s full path is com.rm5248.ReceiveInterface.echoMessage. Note that this is the same as the Java package definition. It is not dependent on the bus name(com.rm5248). If we changed the bus name to foo.bar, we would call the method as such:

$ qdbus foo.bar / com.rm5248.ReceiveInterface.echoMessage hello

Now let’s add a new method to the interface. This new method will take in a string, two ints, and return the addition. Here’s the signature as defined in the interface:

public int echoAndAdd(String str, int a, int b);

Now if we look at it using qdbus, this is what it looks like:

method int com.rm5248.ReceiveInterface.echoAndAdd(QString, int, int)

We call it the same way we called the echoMessage method, just with more parameters.

$ qdbus com.rm5248 / com.rm5248.ReceiveInterface.echoAndAdd Adding 5 9
14

Notice that the Java program outputs “Adding”, and then returns the addition of 5 and 9(which is 14 and the return value). If you want to output a string with spaces, simply put the string inside of double quotes and qdbus will send it out. You can see these methods and the return information using dbus-monitor, however note that for some reason it exits whenever a new Java program connects, so you will have to restart it once you connect. Here is the output for a method call and return:

method call sender=:1.118 -> dest=com.rm5248 serial=10 path=/; interface=com.rm5248.ReceiveInterface; member=echoAndAdd
string "Adding two numbers"
int32 36
int32 42
method return sender=:1.111 -> dest=:1.118 reply_serial=10
int32 78

qdbus will call the introspection information to call the right method, but this part of the output is the actual method call and return.

Now that we have made some methods for Java and called them with qdbus, let’s now make a C++ program that uses dbus-cxx to do the same thing that we just did in Java.

Part V: A Basic C++ Program(Receiving)

Now that we have made some methods to be called in Java, let’s make some methods to be called in C++. We’ll name the methods the same so that it’s easy to see the similarities between the two languages. To start out, let’s make our method. As in Java, we will take in a string, echo it, and then return 0. The implementation is essentially the same as Java, but let’s go over it anyway. Here’s the implementation, using printf as opposed to cout(because I like printf better).

int echoMessage(string str) {
    printf("%s\n", str.c_str() );
    return 0;
}

Simple, right? It’s essentially the same as the Java version. Now that we have this method, let’s go connect to the D-Bus, and export this method out. While the code is slightly more involved, it’s mostly boilerplate so there’s not much of an issue.

DBus::init();
DBus::Dispatcher::pointer dispatcher = DBus::Dispatcher::create();
DBus::Connection::pointer connection = dispatcher->create_connection( DBus::BUS_SESSION );

int ret = connection->request_name( "com.rm5248", DBUS_NAME_FLAG_REPLACE_EXISTING );
if (DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER != ret) return 1;

DBus::Object::pointer object = connection->create_object("/");

Because this is a little more involved though, I’ll go over this more. First, we need to init dbus-cxx. Once we do that, we need to make a dispatcher. The dispatcher is what actually sends us messages. It is very important that your dispatcher does not go out of scope, or it will be deconstructed and you will not receive any more messages from the D-Bus. Next, we get a connection to the session bus. After we have our connection to the bus, we can request a name. In this case, we are requesting the same name as our Java program, com.rm5248. We then must create a path to export methods on. This is exactly the same as what we did before in the Java program. Here’s a graphic that shows exactly how the two correspond:

Now that we have our connection, we have to connect our method to the connection so that we can call it. To do this, dbus-cxx uses templates and sigc++ to call the correct methods. The template is the most important part of this process. Basically, the first argument of the template is the return value of the method, and the remaining arguments are parameters to the method(7 total). So in this case, the template argument to our method, which returns an int and takes in a string, is <int, string>. Here’s the relevant code:

object->create_method<int,string>("com.rm5248.ReceiveInterface", "echoMessage", sigc::ptr_fun(echoMessage) );

Notice how we don’t pass the method address to the create_method method. We use sigc++ to get a function pointer which is used by dbus-cxx to call it. If we want to call a member function of an object, use sigc::mem_fun(object, object_method). The parameters to create_method are fairly straightforward, the first string is the interface name, the second string is the name of the method as it will show up on the D-Bus, and the pointer is the method that will be called. Before we can check to make sure that this works on the D-Bus, there is one last thing that we must do. We must make an infinite loop at the end of our main so that we don’t exit. While Java DBus will automatically keep the program waiting, dbus-cxx does not. I do this by simply including unistd.h and doing a sleep(300) inside of the loop. Because methods are called in their own threads(in both Java-dbus and dbus-cxx), there is no issue of deadlock.

If we look at the output from qdbus, we will notice that is (almost) exactly the same as the Java version.

$ qdbus com.rm5248 /
method QString org.freedesktop.DBus.Introspectable.Introspect()
method int com.rm5248.ReceiveInterface.echoMessage(QString)

Here’s the Java version for reference:

$ qdbus com.rm5248 /
method int com.rm5248.ReceiveInterface.echoMessage(QString)
method QString org.freedesktop.DBus.Introspectable.Introspect()
method void org.freedesktop.DBus.Peer.Ping()

There are fewer methods than the Java version, however we still have the same echoMessage method. If we then call this method, we see output in our C++ program, as well as a return value of 0, exactly as we have seen in the Java program. The output looks exactly the same as from the Java version:

Java version:

$ qdbus com.rm5248 / com.rm5248.ReceiveInterface.echoMessage hello
0

C++ version:

$ qdbus com.rm5248 / com.rm5248.ReceiveInterface.echoMessage hello
0

Now that we have the echoMessage method working, let’s go and add in the second method. So to do that, we have to do two things:

  • define the method
  • put that method onto the D-Bus

The method definition is going to look nearly the same as the Java version, so here’s the important code to export the method:

object->create_method<int, string, int, int>("com.rm5248.ReceiveInterface", "echoAndAdd", sigc::ptr_fun(echoAndAdd) );

Now let’s call the method using qdbus. For reference, here’s what the Java output was:

$ qdbus com.rm5248 / com.rm5248.ReceiveInterface.echoAndAdd Adding 5 9
14

And here’s the result of the C++ call:

$ qdbus com.rm5248 / com.rm5248.ReceiveInterface.echoAndAdd Adding 5 9
14

Alright, we’re able to receive messages using both C++ and Java. Now let’s call methods from one to the other.

Part VI: Calling C++ methods from Java

In order to call methods from Java to C++, Java must know the interface for those methods. Fortunately, we already have an interface made up: ReceiveInterface. In order to call these methods, we must get a remote object to whatever is providing these methods. To do that is very simple. All we have to do is to use our DBusConnection and get a remote object. In fact, here is all of the code required to get a remote object(try/catch omitted for brevity):

DBusConnection conn = DBusConnection.getConnection(DBusConnection.SESSION);
ReceiveInterface recvInterface = (ReceiveInterface)conn.getRemoteObject("com.rm5248", "/", ReceiveInterface.class);

Like the receiving portion, we first get a DBusConnection. Once we have the connection, we get a remote object from the connection. To do that, we specify the unique D-Bus address, the path, and the interface. In this case, this interface will resolve to com.rm5248.ReceiveInterface, which is exactly what qdbus shows as output. Note that when doing Java to Java communication the third parameter may not be needed, but it is always a good idea to add it just in case.

Now that we have our remote object, we can call methods on it just as if it were a local variable in our program:

int returnValue = recvInterface.echoMessage("Hello C++ from Java!");
System.out.println(returnValue);

Now, run the C++ program that we made in Part VI(receive), and then run your Java program. If everything is good, your C++ program should print out “Hello C++ from Java!” and your Java program should print out “0”.

Awesome! We can now communicate from Java to C++. Let’s now go the other direction.

Part VII: Calling Java methods from C++

Again, the C++ is slightly more involved, but about half of it is boilerplate code. So, let’s start out with the first half, which makes the D-Bus connection and gets a remote object.

DBus::init();
DBus::Dispatcher::pointer dispatcher = DBus::Dispatcher::create();
DBus::Connection::pointer connection = dispatcher->create_connection( DBus::BUS_SESSION );

DBus::ObjectProxy::pointer object = connection->create_object_proxy("com.rm5248", "/");

When we get the remote object, we must specify both the unique D-Bus address and the path of the object. Now that we have the object, let’s go and put some methods onto it. The way we make methods on it is very similar to how we created methods on ourselves earlier. Both use templates to figure out what method to call. So, here’s our first method definition:

DBus::MethodProxy&lt;int, string&gt;&amp; echoMessage = *(object->create_method<int, string>("com.rm5248.ReceiveInterface", "echoMessage"));

We use the templates to define the signature of the method. In this case, the signature is a method that returns an int and takes a string. The two parameters to the create_method are the interface of the method, and the name of the method. Now that we have that method defined, let’s go ahead and define the other method:

DBus::MethodProxy<int, string, int, int>& echoAndAdd = *(object->create_method<int, string, int, int>
("com.rm5248.ReceiveInterface", "echoAndAdd"));

Now that we have these two method proxies, we can call the methods as though they were local methods. Here’s the code to do that, and print the results out:

int firstResult = echoMessage("Hello Java from C++!");
printf("%d\n", firstResult);

int secondResult = echoAndAdd("Testing the addition", 42, 19);
printf("%d\n", secondResult);

To test this, let’s fire up JavaReceive, which we made in Part III. Once that has started up, run the program that we just made(send). This is the output that you should get in Java:

Hello Java from C++!
Testing the addition

And here is the output that you should get in C++:

0
61

Excellent! We can now communicate Java->C++, and C++->Java. Note that Java->Java and C++->C++ are not explicitly stated; This is because we have already built these parts! If you run receive and then send, notice how you get the same output as we just got in this part. As well, if you run JavaReceive and then JavaSend, the two programs communicate perfectly.

Part VIII: Type differences between dbus-java and dbus-cxx

Since we have the basic communication ideas down between both Java and C++, it’s now time to talk about the differences. Let’s go take a look at the Notification XML that we looked at back in Part III. Here’s the relevant part that we’re going to talk about:

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
<interface name="org.freedesktop.Notifications">
<method name="Notify">
<arg name="app_name" type="s" direction="in"/>
<arg name="id" type="u" direction="in"/>
<arg name="icon" type="s" direction="in"/>
<arg name="summary" type="s" direction="in"/>
<arg name="body" type="s" direction="in"/>
<arg name="actions" type="as" direction="in"/>
<arg name="hints" type="a{sv}" direction="in"/>
<arg name="timeout" type="i" direction="in"/>
<arg name="return_id" type="u" direction="out"/>
</method>
</interface>
</node>

How would we call this from Java? Well, that’s a bit of a tricky question. Without cheating and using the provided tool to make a Java interface, there are a few things that we need to know. Those are:

  • What is the interface?
  • What are the types of the parameters?

This information is given to us in the XML. In fact, it’s clearly stated. The interface is org.freedekstop.Notifications, and the type of the parameters is given in terms of D-Bus types. So, here’s a comparison between dbus-java, dbus-cxx, and the D-Bus introspection XML.

Java dbus-cxx D-Bus type
String std::string s
List std::vector a
Map<A,B> std::vector<pair> a{s,v}
Byte unsigned char y
int int i
UInt32 unsigned int u
Variant Variant v

Using this information, we can now make a Java interface.

package org.freedekstop;

import java.util.List;
import java.util.Map;

import org.freedesktop.dbus.DBusInterface;
import org.freedesktop.dbus.UInt32;
import org.freedesktop.dbus.Variant;

public interface Notifications extends DBusInterface{
public UInt32 Notify(String app_name, UInt32 id, String icon, String summary, String body, List<String> actions, Map<String,Variant<Byte>>; hints, int timeout);
}

You’ll see how we have created the right number of parameters with the correct type in the method signature. Our interface is also in the package org.freedesktop. When we use this Notifications interface, we have to use it as such:

DBusConnection conn = DBusConnection.getConnection(DBusConnection.SESSION);
Notifications notifiy = (Notifications)conn.getRemoteObject("org.freedesktop.Notifications", "/org/freedesktop/Notifications", Notifications.class);
//the actual calling of the method would be here.

This is equivalent to:

$ qdbus org.freedesktop.Notifications /org/freedesktop/Notifications org.freedesktop.Notifications.Notify <parameters>

Now that we have our interface, let’s get a remote object and call the Notify method on it. We’re not going to go over what all of the parameters to this method do, because this is not a tutorial on how to use the notification-daemon. Anyway, here’s the code which calls the method, after we have gotten the remote object:

Map<String,Variant<Byte>> hints = new HashMap<String, Variant<Byte>>();
hints.put("urgency", new Variant<Byte>((byte)2));
notify.Notify("", new UInt32(0), "", "This is a test", "Again, this is only a test", new LinkedList<String>(), hints, -1);

Once we run this program, we now get a notification in one corner of our screen. Depending on how your computer is set up, this will probably look different. This is what it looks like on my computer:

Now if we wanted to, we could implement the other methods on this interface. We’re not going to do that. However, we will talk briefly about the dbus-cxx version of this. Unfortunately, dbus-cxx can handle only 7 parameters to a method, while this method takes 8. As well, the method takes in a Variant, which dbus-cxx does not currently have support for. However, here is what the method signature would look like, if we could implement it:

<int, int, std::string, int, std::string, std::string, std::string, std::vector< std::string >, std::vector< std::pair > std::string, Variant<unsigned char> > > , int >

Hopefully you can see how you use templates to make a method now.

To make sure that you understand exactly what the naming conventions and how you define what methods to call from using Java, C++ and qdbus, here’s a graphic that spells it out:

Part IX: Receiving Signals(C++)

First, what is a signal? Basically, a signal is a method call that doesn’t return. A signal is also sent out to all programs which have stated that they would like to receive that signal. If you do not ask to receive a signal, you will not get it. It’s similar to a publish/subscribe paradigm. Now, while the rest of this tutorial has been showing you how to do something in Java first, it’s actually much easier to receive and send signals in C++. The way we do it is actually very similar to how we defined methods to be called before. We first do our standard init, and then after that we ask to receive a signal and give the method we want called when that signal is sent out. First, let’s quickly define our signal handling method. This signal handling method will take in an int, a string, and another int. Note that signal handlers [i]cannot[/i] return anything, so the return type is void. Here’s our signal handler. All the signal handler does is make sure the two ints are valid indecies into the string, and then print out the characters at those positions. Once it does that, it prints out the entire string.

void getSignal(int a, string str, int b){
    char* cstr = (char*)str.c_str();

    if( a < strlen(cstr) ){
        printf( "%c\n", cstr[a]);
    }

    if( b < strlen(cstr) ){
        printf( "%c\n", cstr[a] );
    }

    printf("Entire string passed in: %s\n", cstr);
}

As you can see, there’s no real difference between defining a method to receive a signal and defining a method to be called. Now, let’s connect that signal up.

//dbus initialization omitted for brevity
DBus::signal_proxy<void, int, string, int >::pointer signal = connection-&gt;
create_signal_proxy<void, int, string, int >
("/", "com.rm5248.SignalInterface", "GenericSignal");

signal->connect( sigc::ptr_fun(getSignal) );

Again, this is very similar to how we defined a method to be called, including the template arguments. However, we use a DBus::signal_proxy to catch the signal instead of a DBus::Object. A note about this code: you need to make a new DBus::signal_proxy for each signal that you want to catch. When we made a DBus::Object, you only had to make one object in order to export multiple methods.

Now that we have our signal proxy set up, let’s compile and run this. We will now use dbus-send to send a signal, because qdbus does not have support for sending signals. The syntax is similar to qdbus though, so it shouldn’t look too odd:

$ dbus-send / com.rm5248.SignalInterface.GenericSignal int32:3 string:"This is a long message with many characters in it" int32:8

Note that when using dbus-send, you must explicitly state what the types of the parameters that you are sending out are. Also note how we are sending out the signal. We are sending it to a specific destination, If you have dbus-monitor open, you should now see this message:

signal sender=:1.225 -> dest=(null destination) serial=2 path=/; interface=com.rm5248.SignalInterface; member=GenericSignal
int32 3
string "This is a long message with many characters in it"
int32 8

As you can see, ‘signal’ is the first word here, as opposed to earlier when it was ‘method_call’ or ‘method_return’. Now, if we look at the output for recv_sig, notice that we now have some new output:

$ ./recv_sig
s
a
Entire string passed in: This is a long message with many characters in it

Excellent! We have now received our first signal. Now let’s go and send out signals so we can receive them.

Part X: Sending Signals(C++)

Sending out signals is amazingly easy with dbus-cxx. Once you init your connection, just make a DBus::signal with the correct template methods, and the path you want to get the interface for.

DBus::signal<void, int, string, int>::pointer signal_send = connection->
create_signal<void, int, string, int>("/", "com.rm5248.SignalInterface", "GenericSignal");

signal_send->emit( 5, "Sending out signals is fun!", 17);

How to emit the signal is also very similar to how you call a method. Simply call the method as though it were a local method, and the signal will be sent out.

Part XI: Receiving Signals(Java)

Receiving signals in Java is more complicated than in C++. There are two things that we must do. First, we must make an interface that extends DBusInterface, as though we were implementing methods to be called by the D-Bus. If we want to export methods, we can define them in here, but for the purposes of this section we wont. Now, inside of this method we must make a class which extends DBusSignal. Since we are going to make the same signal that we made in C++, we need to make sure that a few things are the same. First, the interface must be defined, as com.rm5248.SignalInterface. Next, our DBusSignal must be defined in this class, as a GenericSignal. There are a few things to know about how to define the signal. First, it must be public. The constructor must also be public. When you are creating the signal, any parameters that you give it to construct the signal with must be given to the super constructor. If you do not do this, you will be unable to receive or send the proper signals. Here’s the proper implementation of a signal:

package com.rm5248;

import org.freedesktop.dbus.DBusInterface;
import org.freedesktop.dbus.DBusSignal;
import org.freedesktop.dbus.exceptions.DBusException;

public interface SignalInterface extends DBusInterface {
    public class GenericSignal extends DBusSignal{
        public final int a;
        public final String str;
        public final int b;

        public GenericSignal(String path, int a, String str, int b) throws DBusException {
            super(path, a, str, b);
            this.a = a;
            this.str = str;
            this.b = b;
        }

        }
}

Now that we have our signal, we can connect to the D-Bus and request our bus name. We then install our signal handler, in this case implemented as an anonymous inner class:

//connect to dbus, request bus name
conn.addSigHandler(SignalInterface.GenericSignal.class, new DBusSigHandler<SignalInterface.GenericSignal>(){
    @Override
    public void handle(SignalInterface.GenericSignal sig) {
        //implementation omitted for brevity; does the same as C++
    }
});

The two parameters are as follows: The first one is the interface of the signal that we are looking for. On the D-Bus, SignalInterface.GenericSignal.class will resolve to com.rm5248.SignalInterface, with a member of GenericSignal. The next parameter is the signal handler. Signal handlers must implement the handle() function. The parameter to this function is determined by the generic type of the class.

Now if we run this program and send signals out from either our C++ program or using dbus-send, notice how we now get a signal in both programs at the same time. If we run both the Java receive and the C++ receive as provided, we will get an error because they are both trying to use the address com.rm5248. Since these addresses must be unique, simply change one of the programs to request a different bus.

Part XII: Sending Signals(Java)

Now that we have defined our interface, we can now send out a signal. Sending out a signal is also very easy. All we have to do is create a new signal, and then tell the connection that we want to send it out. This is the entire program needed to send out a signal(try/catch omitted for brevity):

DBusConnection conn = DBusConnection.getConnection(DBusConnection.SESSION);
SignalInterface.GenericSignal sig = new SignalInterface.GenericSignal("/", 6, "Hello there my friends, this is a test of the emergency broadcast system", 22);
conn.sendSignal(sig);

Again, if we run both the Java signal receiver and the C++ signal receiver(with different D-Bus addresses), we will get the same signal sent to both of us.

Conclusion

D-Bus is a very powerful IPC mechanism. There are a number of options which it gives you that you can use to connect different processes together.

As a final note, you may download all of the files used in this tutorial here.

20 thoughts on “D-Bus Tutorial

  1. Thank you very much for this tutorial, you saved me a lot of time getting into D-Bus. The provided example files are easy to understand and great to dive into the D-Bus ocean.

    Some people might have problems to install dbus-cxx (so did I on ubuntu). I tried to get it from SVN as recommended and got the latest stable version. While installing, the strangest errors popped up and after solving one, the next appeared.

    Finally I found a simple step by step instruction from Andrew Montag that helped me a lot and i recommend it to everyone who tries to install the latest dbus-cxx:
    http://sourceforge.net/mailarchive/message.php?msg_id=30077717

    – Andreas

  2. Thank you very much for this perfect tutorial! It is very easy to understand and useful for me.
    I have been looking for such documentation for a long time.

  3. Very nice and detailed sample usages that clearly and simply explain how D-Bus works.

    Based on your samples I also found the corresponding commands using dbus-send which comes with D-Bus.

    For a method call:
    dbus-send –print-reply –dest=’com.rm5248′ / com.rm5248.ReceiveInterface.echoMessage string:’Hello’

    For a signal:
    dbus-send –session –type=signal / com.rm5248.SignalInterface.GenericSignal int32:6 string:’Hello There, this is my first test’ int32:22

    Nice job

  4. Cool tutorial. I had a problem with running my app:
    org.freedesktop.dbus.exceptions.NotConnected: Disconnected
    The reason was the hashmap mustn’t be empty.
    So I’ve added an “urgency” item and it’s working.
    Thank you for your work. Don’t know when this tutorial was written, but now in 2014 it’s still valuable – even though I’m writing in Scala.

  5. excellent tutorial, those examples just work….the only thing I had to do is linking libraries from /usr/share/java and to choose a correct java version on Ubuntu 12.04 x64…Just wondering what is needed to make it the recieve example a productive piece of code…!?

  6. Here an update to run it on Debian (LMDE) with Eclipse Luna
    – Instead of downloading dbus-java-2.7.tar.gz from http://freedesktop.org/wiki/Software/DBusBindings/, I installed dbus-java-bin via Synaptic.
    – Then I imported your examples as existing projects into my eclipse workspace.
    – I had to change the libraries:
    in Eclipse, right-click the project, Properties, Java Build Path, Libraries tab, remove ‘libdbus-java-2.7.jar’ and ‘JRE System Library [JavaSE-1.6]’ and Add External JARs… ‘/usr/share/java/dbus.jar’, and Add Library… ‘JRE System Library’ (workspace default).
    – Then it would run
    Thanks!

  7. Hi, i cant solve this problem:
    Exception in thread “main” java.lang.UnsatisfiedLinkError: no unix-java in java.library.path
    at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1865)
    at java.lang.Runtime.loadLibrary0(Runtime.java:870)
    at java.lang.System.loadLibrary(System.java:1119)
    at cx.ath.matthew.unix.UnixSocket.(UnixSocket.java:33)
    at org.freedesktop.dbus.Transport.connect(Unknown Source)
    at org.freedesktop.dbus.Transport.(Unknown Source)
    at org.freedesktop.dbus.DBusConnection.(Unknown Source)
    at org.freedesktop.dbus.DBusConnection.getConnection(Unknown Source)

    any idea?

    Thank you

  8. Firstly, thanks for your share.
    Could you give me more messages about “For Java, make sure that you have the jar and the required files. ” What is the jar and the required files? Because I met some error when I run the examples.

    Thanks again!

    • The required files are the libmatthew jar files that are needed to run the examples. These jar files must be on the classpath.

      If I remember correctly, those jar files are:
      dbus.jar
      unix.jar(from libmatthew)
      hexdump.jar(from libmatthew)

      If you’re on Debian, you should be able to install these using:
      apt-get install dbus-java

      The jar files will be in /usr/share/java

  9. I was unable to get SVN revision 213 to compile. Rolling back to rev. 207 removed the offending code, but it might be worth taking look to make sure what you committed was what you intended.

    arg.cpp: In member function ‘std::string Arg::stubsignature()’:
    arg.cpp:84:34: error: no matching function for call to ‘signature(DBus::Type)’
    return DBus::signature( type() );
    ^
    82: std::string Arg::stubsignature()
    83: {
    84: return DBus::signature( type() );
    85: }
    86:
    87: DBus::Type Arg::type()
    88: {
    89: if ( not signature.is_singleton() ) return DBus::TYPE_INVALID;
    90: //if ( not signature.begin().is_basic() ) return DBus::TYPE_INVALID;
    91: return signature.begin().type();
    92: }

      • I’m using gcc 4.8.2 on Ubuntu 14.04 (arm-linux.gnueabihf toolchain). I’ve also tried compiling on my development machine, which has gcc 4.8.4 on Ubuntu 14.04 and Intel i386-linux-gnu toolchain. Both have the same complaint.
        Even after building rev. 207, I still can’t get either dbus-cxx-introspect or dbus-cxx-xml2cpp to do anything useful. The former hangs and the latter produces no output.
        Thanks!

        • I will take a look at it at some point, but it may be a few weeks before I have the time.

          If you are willing and able to look at the code and figure out what is wrong, send a patch to the dbus-cxx mailing list and I can apply it.

          (It compiles cleanly for me on Debian 8, so I don’t have any ideas why it wouldn’t work on 14.04)

          • I can probably afford to spend a small amount of time on it. If you can tell me the file name and line number of the function that matches the signature “signature(DBus::Type)”, I’ll start from there.
            Thanks!

          • I just took a quick look at it, that error is only in the tools. Earlier versions should work.

            Otherwise, try this patch, and we can move the discussion there or to the mailing list, since this is getting too deep for wordpress to handle.

  10. Sorry to keep bugging you here. Perhaps you didn’t see my comments on github. And I’ve been waiting since September for access to the mailing list, so this is my only choice. Is there any documentation on using dbus-cxx to send user-defined data (i.e. a struct).
    Thanks,

Leave a Reply to binky Cancel reply

Your email address will not be published. Required fields are marked *