GAMBAS BOOK 3.14

The class DBusSignal (gb.dbus) allows to receive any message of type Signal sent by an application registered on the D-Bus on the D-Bus. You can create the class. The class DBusSignal has only one property and one event.

The Boolean Enabled property of the DBusSignal class is True if the signal observer is switched on. The default value is True. You can also set and read the value.

The event Signal ( Signal As String, Arguments As Variant[ ] ) is triggered when the DBus signal object receives a D-Bus signal from a selected transmitter. The following applies to both parameters:

• Signal is the DBusSignal name, also called Member.
• Arguments is a variant array with all signal arguments.

To create a new DBus signal object:

Dim hDBusSignal As DBusSignal

hDBusSignal = New DBusSignal ( Connection As DBusConnection, Interface As String [ , Every As Boolean ] )  As "SignalEventName"

• Connection refers to the session bus or the system bus to which it is connected.
• Interface is the interface where the signal is generated and sent.
• Set the optional Every argument to TRUE if you want to intercept the signals sent by all applications on the D-Bus. Otherwise, you will only receive the signals that have been specifically sent to your application.

In the following example, the D-Bus signal with the signal name 'StateChanged' is intercepted, which is sent by the D-Bus object “/org/freedesktop/NetworkManager” on the System D-Bus when the status (on/off) of the network changes.

Public hDBusSignalNM As DBusSignal
Private $iNetworkState As Integer
Private $cDBus As DBusConnection
Private $sInterface As String
 
Public Sub Form_Open()
…
  $cDBus = DBus.System
  $sInterface = "org.freedesktop.NetworkManager"
  hDBusSignalNM = New DBusSignal($cDBus, $sInterface, True) As "ObservedNMSignal"
…
End

The signature of the signal is “i” - an integer value is transmitted. If the signal is intercepted with the signal name specified above, its value is read from the variant array of arguments and stored in a variable, for example:

Public Sub ObservedNMSignal_Signal(Signal As String, Arguments As Variant[])
  If Signal = "StateChanged" Then
     $iNetworkState = Arguments[0] ' The array has exactly one element!
  Endif
End

The signal observer is always turned off before the program window is closed:

Public Sub btnClose_Click()
  If hDBusSignalNM Then hDBusSignalNM.Enabled = False
  FMain.Close()
End

In revision #7146, the ability to send D-Bus signals has been added to the gb.dbus component.

That's how it works:

• All events defined in a D-Bus object become D-Bus signals.
• The name of the event must be the name of the interface, where all dots are replaced by underscores “_” followed by an underscore and the name of the signal.
• If the event is the standard interface, the signal name is sufficient.
• Do not forget to add the name of the interface when calling the Register() method!

To send a D-Bus signal on a specific D-Bus, use one of the two methods: DBus.Session.Raise(…) or DBus.System.Raise(…).

The DBus-Raise(…) method requires 3 arguments:

• 1. argument: DBus object
• 2. Argument: Signal name. This is the name of the event where all underscores“_” are replaced by a dot“.
• 3. argument: An optional array of signal arguments. If you only want to intercept the signal via the signal name and this is sufficient information for you, then you can dispense with the evaluation of the array of signal arguments.

You do not have to define a signal signature because it is not used directly. But it makes sense to do it anyway. This ensures that the (pseudo) signal signature and the signal arguments match! Good to know: The data types of the individual signal arguments in the above array are automatically converted into D-Bus data types.

Before you can send a D-Bus signal, you must define it in a separate class file.

Signal definition

A signal to be sent in the MyProject application is prepared in the class file MySignal.class, for example. You can define the name of the class file and the signal name - in the following example State - yourself:

' Gambas class file (MySignal.class)
 
Inherits DBusObject
Create Static
 
'' Signatur: "s"
'' This signal has exactly 1 argument 'Flag' of the data type string
Event org_gambas_MyProject_MySignal_State(Flag As String)
 
End

As you can see, the'State' signal has exactly one argument with the data type string and thus follows the signature “s”.

Send a signal

The source code for the file FMain.class of the project MyProject is completely specified. The most important passages are highlighted in colour:

' Gambas class file
 
Private hDBusObject As MySignal
Private hDBusSignal As DBusSignal
 
Public Sub Form_Open()
 
  hDBusObject = New MySignal
 
  FMain.Resizable = False
  FMain.Caption = ("Waiting for a D-Bus signal ...")
  DBus.Unique = True
 
  DBus.Session.Register(hDBusObject, "/MySignal")
  hDBusSignal = New DBusSignal(DBus.Session, Null, True)
 
  SendSignal("on")
 
End
 
Private Sub SendSignal(sState As String)
 
  Dim sSignalName As String
  Dim aArguments As New Variant[]
 
  sSignalName = "org.gambas.MyProject.MySignal.State"
  aArguments = [sState]
 
  DBus.Raise(hDBusObject, sSignalName, aArguments)
 
End
 
 
Public Sub Form_Close()
 
  SendSignal("off")
    If hDBusSignal Then hDBusSignal.Enabled = False
    If DBus.IsRegistered(hDBusObject) Then DBus.Session.Unregister(hDBusObject)
  FMain.Close()
 
End
<code>
 
The source code for the signal receiver is also presented so that you can successfully test the project:
 
<code gambas>
' Gambas class file
 
Private $hDBusSignal As DBusSignal
 
Public Sub Form_Open()
 
  FMain.Resizable = False
  FMain.Caption = ("Waiting for a D-Bus signal ...")
  $hDBusSignal = New DBusSignal(DBus.Session, Null, True) As "ObservedSignal"
  SetLEDColor(picStatus, "red")
  txaReport.Insert(gb.NewLine)
 
End
 
Public Sub ObservedSignal_Signal(Signal As String, Arguments As Variant[])
  If Lower(Signal) = "state" And If Arguments[0] = "on" Then
     txaReport.Insert("   " & ("The data server is online!") & gb.NewLine)
     SetLEDColor(picStatus, "green")
     SendSound("on.wav")
  Else If
     Lower(Signal) = "state" And If Arguments[0] = "off" Then
     txaReport.Insert("   " & ("The data server is down!") & gb.NewLine)
     SetLEDColor(picStatus, "red")
     SendSound("off.wav")
  Endif
End
 
'' Sends a sound<br>
'' Sound: Name of the sound file in the project folder 'sounds'.<br>
'' Play back audio files on a PulseAudio sound server - the player is 'paplay'
Public Sub SendSound(SoundFileName As String)
  If System.Exist("paplay") Then
     Shell "paplay " & Application.Path &/ "sounds" &/ SoundFileName
  Endif
End
 
Private Sub SetLEDColor(picBox As PictureBox, sLEDColor As String)
  picBox.Picture = Picture["LED/led_" & sLEDColor & ".svg"]
End
 
Public Sub Form_Close()
  If $hDBusSignal Then $hDBusSignal.Enabled = False
  FMain.Close()
End

When starting and closing the program window, the server always sends the D-Bus signal 'State', which signals its status via the signal argument with the values 'on' or 'off'. The client waiting for the signal can react appropriately to the transmitted status.

Figure 24.9.6.0.1: The server is offline

Figure 24.9.6.0.2: The server is online

Figure 24.9.6.0.3: The server is offline

Hint:

If you need more information about which meta data the intercepted signal has besides the actual content, successfully use the class DBusObserver.

In the projects for the DBusSignal class in the following three chapters you will learn how to intercept signals, evaluate their content and how to send signals.