User Tools

Site Tools


Sidebar

Network and communication

k24:k24.9:k24.9.6:start

24.9.6.0 DBusSignal

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

24.9.6.0.1 Property

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

24.9.6.0.2 Event

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

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

24.9.6.0.3 New DBusSignal(...)

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 system bus to connect to.
  • Interface is the interface in which the signal is generated and sent.
  • Set the optional argument Every to TRUE if you want to intercept the signals sent by all applications on the D-Bus. Otherwise, you will only get the signals sent specifically to your application.

24.9.6.0.4 Intercept D-Bus signal

The following example intercepts the D-Bus signal with the signal name 'StateChanged' 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 sent. If the signal is intercepted with the signal name given above, then read its value from the variant array of arguments and store it 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 switched off before the programme window is closed:

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

24.9.6.0.5 Send D-Bus signal

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

Here'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 with all dots replaced by underscores “_” - followed by an underscore and the name of the signal.
  • If the event is the default interface, then the signal name is sufficient.
  • Don't forget to add the name of the interface when you make the necessary call to 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 takes 3 arguments:

  • 1st argument: DBus object.
  • 2nd argument: signal name. This is the name of the event with all underscores “_” replaced by a dot “.”.
  • 3rd argument: An optional array of signal arguments. If you only want to intercept the signal via the signal name and that 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. However, it makes sense to do it anyway. This way you can ensure for yourself 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 to D-Bus data types.

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

Signal definition

The preparation of a signal to be sent in the MyProject application is done, for example, in the class file MySignal.class. You can define the name of the class file and the signal name - State in the following example - 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 signal 'State' has exactly one argument with the data type string and thus follows the signature “s”.

Send signal

The source code for the file FMain.class of the project MyProject is given completely. 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>
 
Damit Sie das Projekt erfolgreich erproben können, wird auch der Quelltext für den Signal-Empfänger präsentiert:
 
<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

The server always sends the D-Bus signal 'State' when starting and closing the programme window, which signals its status via the signal argument with the values 'on' or 'off'. The client waiting for the signal can react in an appropriate way 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

Tip:

If you need more information about what meta-data the intercepted signal has besides the actual content, use the DBusObserver class with success.

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

The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k24/k24.9/k24.9.6/start.txt · Last modified: 16.08.2022 (external edit)

Page Tools