Location: Start / Introduction Language: en

This is a tutorial for Ruby D-Bus, a library to access D-Bus facilities of your system. This chapter has the following sections:

  1. What is D-Bus?
  2. Definitions
    1. Client
    2. Service
    3. Object path
    4. Interface
    5. Method
    6. Signal
    7. Message
    8. Signature

What is D-Bus?

D-Bus is an RPC protocol. A common setup can have multiple D-Bus daemons running that route procedure calls and signals in the form of messages. Each of these daemons supports a bus. A bus that is often used by modern desktop environments, and is available per session, is called the session bus. Another bus that can be available, but in a system-wide manner, is called the system bus. It is used for example by the Hardware Abstraction Layer daemon. Note that theoretically the D-Bus RPC protocol can be used without a system or session bus. I never came across any actual use of this though.

At the desktop level, D-Bus allows some components to interact. Typically if you are writing an application or a personal script that wants to interact with your web browser, your music player, or that simply wants to pop-up a desktop notification, D-Bus comes into play.

At the system level, the Hardware Abstraction Layer is a privileged daemon that notifies other software of hardware activities. Typically, if you want to be notified if a CD-ROM has been loaded in, of if you want to explore hardware, the system daemon comes into play.

The D-Bus RPC system is as we will see object oriented.

Buses provide access to services provided in turn by running or ready to run processes. Let me introduce some D-Bus terminology before we discuss the API of Ruby D-Bus.

Definitions

Client

A D-Bus client is a process that connects to a D-Bus. They issue method calls and register to the bus for signals and events.

Service

A connected client can export some of its objects and let other clients call some of its methods. Such clients typically register a special name like org.freedesktop.Notifications, the service name.

There is slightly different type of service. They are provided by processes that can be launched by a D-Bus daemon on demand. Once they are started by D-Bus they register a service name and behave like another client.

Note that the buses themselves provide the org.freedesktop.DBus service, and provide some features through it.

Object path

An object path is the D-Bus way to specify an object instance address. A service can provide different object instances to the outside world, so that external processes can call methods on each of them. An object path is an address of an instance in a very similar way that the path is an address of a file on a file system. For example: /org/freedesktop/Notification is an object path of an object provided by the org.freedesktop.Notification service

Beware: service names and object paths can, but do not have to be related! You’ll probably encounter a lot of cases though, where the object path is a slashed version of the dotted service name.

Interface

Classically in an object model, classes can implement interfaces. That is, some method definitions grouped in an interface. This is exactly what a D-Bus interface is as well. In D-Bus interfaces have names. These names must be specified on method calls.

The org.freedesktop.Notification service provides an object instance called /org/freedesktop/Notification. This instance object implements an interface called org.freedesktop.Notifications. It also provides two special D-Bus specific interfaces: org.freedesktop.DBus.Introspect and org.freedesktop.DBus.Properties. Again, object paths, service names, and interface names can be related but do not have to be.

Basically the org.freedesktop.DBus.Introspect has an Introspect method, that returns XML data describing the /org/freedesktop/Notification object interfaces. This is used heavily internally by Ruby D-Bus.

Method

A method is, well, a method in the classical meaning. It’s a function that is called in the context of an object instance. Methods have typed parameters and return typed return values.

Signal

Signals are simplified method calls that do not have a return value. They do have typed parameters though.

Message

Method calls, method returns, signals, errors: all are encoded as D-Bus messages sent over a bus. They are made of a packet header with source and destination address, a type (method call, method reply, signal) and the body containing the parameters (for signals and method calls) or the return values (for a method return message).

Signature

Because D-Bus is typed and dynamic, each message comes with a signature that describes the types of the data that is contained within the message. The signature is a string with an extremely basic language that only describes a data type. You will need to have some knowledge of what a signature looks like if you are setting up a service. If you are just programming a D-Bus client, you can live without knowing about them.