GAMBAS BOOK 3.19.1

The DBus (gb.dbus) class manages an application's connection to the session bus or the system bus and inherits from the _DBus virtual class.

The DBus class has the following six properties:

Table 24.9.2.1.1 : Properties of the DBus class

Notes on the DBus.Unique property:

In case you set the DBus.Unique property to True.

sDBusApplicationName  = org.gambas.projektname

However, for the alternative case DBus.Unique = False (which is the default value), it becomes.

sDBusApplicationName  = org.gambas.projektname-PID  ' PID = Process Identification Number

Since it is not necessarily known what the current value of DBus.Unique is for a D-Bus server to be used, for example, you can use the following function in the source code for a D-Bus client to determine the correct name of the server on the D-Bus:

Private Function GetDBusApplicationName(GBAppName As String) As String
 
  Dim aList As String[]
  Dim sElement  As String
 
  aList = DBus.Session.Applications.Sort(gb.Natural)
 
  For Each sElement In aList
    If sElement Begins "org.gambas." & GBApp.Name Then
 
       Return sElement
 
    Endif
  Next
 
End

The DBus class has four methods, which are specified and described in the following table:

Table 24.9.2.2.1 : Methods of the DBus class.

Notes:

• A Gambas program is automatically connected to the session D-bus when the component gb.dbus is loaded! This has nothing to do with the registration described above. You only need to register if you want to export your own objects to the D-Bus in order to make the methods and properties programmed in the D-Bus objects available as a service to other d-bus-enabled applications. If you only want to use the services offered on the D-Bus in your Gambas application, then you do not need to register your Gambas application on the D-Bus.
• The two methods Register(…) and Unregister(…) only refer to D-Bus objects in Gambas programs!

To determine whether a particular application is currently registered on the D-Bus, you can use the following source code when customising the application name:

If DBus.Session.Applications.Exist($sDBusName) Then

If necessary, you can unregister the objects exported by your Gambas program from the D-Bus again:

Public Sub Form_Close()

  If DBus.IsRegistered($hDBusObject) Then DBus.Session.Unregister($hDBusObject)
  FMain.Close()

End

The answer to the question 'What is exported to the D-Bus?' depends on whether you use the optional argument Interfaces As String[] in the register method or not.

Register without interfaces:

• Public methods whose name does not begin with an underscore. Their optional arguments and the return type of the method can be converted to a D-Bus data type.

• Public properties whose name does not have an underscore inside and whose type can be converted into a D-Bus data type.

As soon as you export at least one object, 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.

All methods and properties whose name starts with an interface name specified in the interface argument - where the dots are replaced by underscores and followed by an additional underscore - are exported under this interface.

Registration with at least one interface:

• By an interface named org.gambas.<application-name>.<class-name>, only its methods and properties of the specified class are exported.
• You can also specify multiple interfaces if you use the optional argument Interfaces As String[] in the Register(…) method! The array contains the names of the interfaces.

In chapters 24.9.8.1 and 24.9.8.2 you will find two (server) projects that export objects to the D-Bus.

The following four constants of the DBus class each represent a message type that can take one of the following integer values:

• DBus.Method (1),
• DBus.Reply (2),
• DBus.Error (3),
• DBus.Signal (4).

An object representing an application connected to the D-Bus is returned with DBus[…], because the class DBus is static and behaves like a (read-only) array:

Dim hDBusApplication As DBusApplication
hDBusApplication = DBus [ Application As String ]

• If the argument Application starts with “system://”, then the application is searched for on the system bus.
• If the Application argument starts with “session://”, then the application is searched for on the session bus.

The default value for the Application argument prefix is “session://”.

Examples:

Dim hDBusApplication As DBusApplication

Dim hConnection As DBusConnection
hConnection = DBus.System
hDBusApplication = DBus["system://org.freedesktop.ConsoleKit"]

Dim hDBusApplication As DBusApplication

hDBusApplication = DBus["session://org.Cinnamon.LookingGlass"] oder
hDBusApplication = DBus["org.Cinnamon.LookingGlass"] Standard-Parameter 'session:\\' intern gesetzt