GAMBAS-BOOK 3.19.5

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:

• use of existing services on the D-Bus and.
• providing services on the D-Bus with Gambas programs.

Implementing these strategies will enable you to do the following for any d-bus enabled application:

• Invoke methods,
• offer methods in exported d-bus objects,
• read and set values of properties,
• intercepting signals,
• sending signals.

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:

• A Gambas program is automatically connected to the session D-bus when the gb.dbus component is loaded!
• As soon as you export at least one D-Bus object to the D-Bus via the Register(…) method, your application will be registered on the D-Bus under the name org.gambas.<applicationname>. For <application name> you can always use the Application.Name property.

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:

• Method,
• Reply,
• Error,
• Signal.

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:

• A path can be of any length.
• A path begins with the ASCII character '/' (ASCII decimal 47).
• A single '/'-character represents the root directory.
• Multiple '/'-characters% (in succession) are not allowed. * Each path element after a '/'-character%% contains only characters from “[A-Z][a-z][0-9]_” .
• No element may be an empty string.

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:

• service (D-bus name of the application) org.freedesktop.NetworkManager
• Object path (Path) /org/freedesktop/NetworkManager
• Interface org.freedesktop.DBus.Introspectable

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).