GAMBAS BOOK 3.19.1

This introduction to D-Bus subsumes parts from various literature sources to provide initial answers to the questions “What is D-Bus?” and “What can D-Bus do?”.

D-Bus or Desktop-Bus is a framework of Inter-Process-Communication (IPC) and part of the freedesktop project (https://www.freedesktop.org/wiki/). IPC allows processes to exchange data in the form of messages. These messages are sent and received on a message channel. This channel is called D-Bus. D-Bus offers at least two buses for communication between processes. One is the global system bus and another is the session bus, to which each desktop of a logged-in user within his desktop session is automatically connected when one of his applications registers on the D-Bus bus.

After a computer with a Linux operating system is switched on, programmes that connect to the system bus and register there are also started. If a user has registered on the desktop, then other programmes start and register on the session bus. What all programmes registered on the D-bus have in common is that they either offer a certain message service or use offered message services. A programme that can register on the system bus or on the session bus should be marked as dbus-enabled.

Example:
If you click on the network symbol in the task bar in Mint 18.3, a small menu window opens in which you can switch the LAN or WLAN off or on. After switching off, the service with the ID :1.21 - behind which is the D-Bus service org.gnome.networkmanager_applet - sends the signal 'NewIcon', among other things. The service org.gnome.freedesktop.Notifications receives it and evaluates the signal. The first reaction is to change the network icon in the taskbar. Then the service sends a message called 'Notify' to the D-Bus. The content of the message is a notification and is displayed in a window on the desktop:

Figure 24.9.0.1: Message on the desktop

Now you may be wondering

• where the information from the last section came from,
• what other messages the above service can send, and
• whether you, as a Gambas programmer, can use offered services on the D-Bus or offer your own services on the D-Bus with d-bus capable Gambas programs?

1. answer
The answer is simple: To monitor the data traffic on the system bus or on the session bus, you can use the console program 'dbus-monitor' like the author and others.

With the following commands you can read out a list of the applications registered on the system bus and on the session bus in a console. The list contains the D-bus names and the unique connection IDs assigned to them, which are always preceded by a colon. The programme qdbus is used:

$ qdbus --session | grep -v ":"
  org.gnome.SessionManager
  org.gtk.Private.UDisks2VolumeMonitor
  ...
  org.PulseAudio1
  org.freedesktop.DBus

$ qdbus --system | grep ":"
...
:1.44
:1.5
:1.21

You can also use the Gambas programme 'DBusView' and get this overview of all programmes currently registered on the D-Bus:

Figure 24.9.0.2: Registered programmes on the D-Bus

2. answer
You need to know that each programme registered on the D-Bus provides a description of the service offered in an XML file. There are several ways to view the contents of the XML file. If you already know the D-Bus name of the application - for example via the program 'DBusView' - then one way is to call the method 'Introspect' of the standard interface 'org.freedesktop.DBus.Introspectable'. This call is called Introspection. Since introspection is of central importance when working with the services on the D-bus, it is described in a separate chapter 24.9.0.2. To find out about all the programmes and their services on the system bus or on the session bus, the programme 'd-feet' is the first choice, the use of which is described in detail in chapter 24.9.0.2.3.

3. response
Yes - the component gb.dbus provides you with several classes to use services on the D-bus or to provide services or intercept or send signals with your own d-bus capable Gambas programs.

In the following chapters these classes are described with their properties, methods and events. In addition, numerous projects are presented to give you ideas for your own d-bus-capable programmes.

Overview of the chapters

• Chapter 24.9.0.1 Gambas and DBus: The focus is on D-Bus, D-Bus message, D-Bus name, D-Bus address, D-Bus object and D-Bus interface.

• Chapter 24.9.0.2 D-Bus Introspection: The ability of a program to examine the properties of an exported D-Bus object at runtime is called introspection. With the component gb.dbus, Gambas has the ability to analyse a service, its objects, interfaces and their methods and properties, but also declared signals on the D-Bus, and to map them in a suitable form. Many programmes are presented with which specific aspects can be analysed.
• Chapter 24.9.0.3 D-Bus signature: You need signatures to map the D-Bus data with their D-Bus data types to Gambas data and their data types and vice versa. Two comprehensive examples with complex signatures show the necessary data conversion.
• Chapter 24.9.1 Class DBusObject: The (static) class is the parent class for all objects that you can export to the D-Bus.
• Chapter 24.9.2 Class DBus: The class DBus manages the connection of an application to the session bus or the system bus. You can use the methods to register or unregister a D-Bus object on the D-Bus, or to check whether a D-Bus-enabled application is registered on the D-Bus. Using the Raise(…) method, you can send a D-Bus signal. To check if a specific D-Bus object of your Gambas application is already registered on the D-Bus, use the IsRegistered(..) method.
• Chapter 24.9.3 Class DBusApplication: The class DBusApplication (gb.dbus) represents an application that is registered on the D-Bus and uses the class DBusConnection.
• Chapter 24.9.4 Class DBusConnection: The class represents a connection of a d-bus-enabled application to the system D-bus or to the session D-bus. It is primarily used to determine the applications registered on the system D-bus.
• Chapter 24.9.5 Class DBusObserver: In this chapter you will learn how to intercept a message on the D-Bus and display its contents. Two projects demonstrate the use of the class.
• Chapter 24.9.6 Class DBusSignal: If you only want to intercept signals and display their contents, this class provides a special observer. Three projects complete the theory.
• Chapter 24.9.7 Class DBusProxy: This class shows how to define and use a D-Bus proxy.
• Chapter 24.9.8 Class DBusVariant and DBusValues: With the help of the two classes you can define methods and signals and thus offer services on the D-Bus and send signals with a Gambas programme. The projects are always set up as server-client projects.

The following list of links will take you to interesting websites that deal with the topic of D-Bus in a special way:

• https://techbase.kde.org/Development/Tutorials/D-Bus/Introduction_(en)
• https://www.freedesktop.org/wiki/Software/dbus/
• http://www.linuxjournal.com/article/10455?page=0,0
• https://blog.mafr.de/2006/12/19/using-dbus-introspection/
• https://pythonhosted.org/txdbus/dbus_overview.html
• http://gambaswiki.org/wiki/comp/gb.dbus
• http://gambaswiki.org/wiki/doc/dbus