User Tools

Site Tools


Sidebar

Network and communication

k24:k24.9:k24.9.2:start

24.9.2 DBus

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

24.9.2.1 Properties

The class DBus has the following six properties:

PropertyData typeDescription
DebugBooleanIs True when debugging messages are output after DBus.debug = True or sets the boolean value.
NameStringThe name of the D-Bus application is set or returned. By default, the D-Bus name has the following syntax: org.gambas. <xxx>, where <xxx> is the value of the Application.name property. Note: The D-Bus name is automatically normalized and adapted to the D-Bus specification.
NullObjectA special object is returned that represents the D-Bus value NULL.
Session DBusConnectionIndicates the connection between an application and the session bus of type DBusConnection.
SystemDBusConnectionIndicates the connection between an application and the system bus of type DBusConnection.
UniqueBooleanIs True if an application is registered on the D-Bus with a unique ID or sets the Unique property. Please note the following information.

Table 24.9.2.1.1: Properties of Class DBus

Notes on the DBus.Unique property:

If you set the DBus.Unique property to True, the name of the application is

sDBusApplicationName  = org.gambas.projektname

For the alternative case DBus.Unique = False (this is the default value), however, this becomes

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

Since it is not necessarily known what the current value 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

24.9.2.2 Methods

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

MethodDescription
IsRegistered ( Object As DBusObject )The boolean function returns True if the object passed as parameter is registered on the D-Bus.
Register ( Object As DBusObject, Path As String [, Interfaces As String[] ] )Exports a DBus object to the D-Bus. The following applies to the parameters: Object is the D-Bus object to be exported, Path is the D-Bus path for the D-Bus object and Interface (optional) allows the names of additional interfaces implemented for the D-Bus object used to be specified. Details can be found in the documentation under DBusConnection.Register().
Unregister ( Object As DBusObject )Deregisters the DBus object passed in the parameter from the D-Bus and is the equivalent of DBus.Session.Unregister().
Raise ( Object As DBusObject, Signal As String [ , Arguments As Variant[] ))Triggers a D-Bus signal. For the parameters: Object is the object that transmits the signal, Signal is the name of the transmitted signal and Argument represents the (optional) arguments of the signal in a variant array.

Table 24.9.2.2.1: Methods of Class DBus

Hints:

  • 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 to other d-bus-compatible applications as a service. If you only want to use the services offered on the D-Bus in your Gambas application, you do not have to register your Gambas application on the D-Bus.
  • The 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 you modify the application name:

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

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

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.

Registration 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 has no underscore inside and whose type can be converted to a D-Bus data type.

As soon as you export at least one object, your application will be installed on the D-Bus under the name org.gambas. Application Name > registered. You can always use the Application.name property for <Application name>.

All methods and properties whose name begins 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:

  • Through an interface named org.gambas. application name>. Class Name>, only the 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.

24.9.2.3 Constants

The following four constants of the class DBus 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).

24.9.2.4 Example - DBus[

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

Dim hDBusApplication As DBusApplication
hDBusApplication = DBus [ Application As String ]
  • If the Application argument starts with “system://%”, then the application is searched on the system bus.
  • If the Application argument starts with “session://%”, then the application is searched on the session bus.

The default value for the prefix of the Application argument 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

Download

This website uses cookies. By using the website, you agree with storing the cookies on your computer. More information in the privacy policy.
k24/k24.9/k24.9.2/start.txt · Last modified: 02.07.2018 (external edit)

Page Tools