The gb.dbus component consists of two parts: The core is written in C and is located in gb.dbus/src. Building on this, there is a part that is written in Gambas and is located in the path gb.dbus/src/gb.dbus. For example, the class DBusVariant is written in C and is located in the file c_dbusvariant.c, while the class DBusValue is programmed entirely in Gambas.
As far as Gambas and D-Bus are concerned, two strategies are generally followed:
Implementing these strategies will enable you to do the following for any d-bus enabled application:
D-Bus provides 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. The default in Gambas is the session bus.
There are (at least) two D-Bus daemons running on a Linux system.
$ env | grep DBUS_SESSION_BUS_ADDRESS DBUS_SESSION_BUS_ADDRESS=unix:abstract=/tmp/dbus-CTaH4kQuEM,guid=59a12bb14e4d0385a446dd2257f34ab5
However, 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.1.1: Registered programmes on the D-Bus
You will find the archive for the DBusView programme in the download area of chapter 24.9.2.
With the following commands you can read out a list of the applications that are registered on the system bus or on the session bus. 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.pulseaudio.Server org.freedesktop.DBus $ qdbus --system | grep ":" ... :1.44 :1.5 :1:21
Notice:
Communication on the system bus and the session bus is done by messages - similar to sending packets in TCP/IP networks. Unlike the TCP/IP protocol, however, D-Bus guarantees the transmission of the complete messages in one go. There are four types of D-Bus messages:
Messages are sent or received as method calls or signals. Each call to a method is always acknowledged with a message - not only in the case of an error or the successful return of a value.
In the Gambas class DBus (gb.dbus), the message types are declared via the four (integer) constants DBus.Method (1), DBus.Reply (2), DBus.Error (3) and DBus.Signal (4).
Since several applications - or their processes - can be connected to the system bus or the session bus, it is necessary to address each message uniquely. The address consists of the specification
24.9.0.1.4 D-Bus nameA service represents an active connection between a program and the system D-bus or the session D-bus. This connection is described by the readable D-Bus name. A “ReverseDomainName” is used for this description. D-Bus names have the syntax: “ReverseDomainName”.ApplicationName. Note that D-Bus names are case sensitive.
For D-Bus names in Gambas, the syntax is: org.gambas.xxx with xxx as the Gambas project name provided under the value of the Application.Name property and used for xxx. These D-Bus names, for example, are correct:
org.freedesktop.NetworkManager org.gambas.support org.Cinnamon.LookingGlass org.gtk.Private.RemoteVolumeMonitor
If more than one instance of an application is registered on the D-Bus, then the process ID is appended to the name of the service, so that there is then a unique D-Bus name for the connection.
At the same time, a unique ID is also generated for each connection of an application to the D-bus. This ID starts with a colon (:) followed by a sequence of digits, a dot and another sequence of digits. For example, a valid ID would be :1.63 .
Objects provide access to interfaces. They are identified by identifiers such as /org/freedesktop/NetworkManager or /org/gambas/P2DBUS, whose syntax is reminiscent of file paths. The following rules define a valid object path:
qdbus --session \ org.gambas.export_dbus \ /org/gambas/export_dbus \ org.gambas.export_dbus.Compute(7,13)
Note: A d-bus-enabled application may ignore an incorrectly declared object path!
A valid address, for example, is composed of these three items:
and is used as a valid address like this:
org.freedesktop.NetworkManager /org/freedesktop/NetworkManager org.freedesktop.DBus.Introspectable
An (active) interface has methods, properties and events as well as signals and is registered on the D-Bus. The description of an interface can be in an XML document to serve as a reference for developers and users (introspection).