GAMBAS BOOK 3.19.1

In contrast to the two projects in chapter 24.9.6.2, where the signature of the signal was specified as “s”, in this chapter you will be presented with a signal with a complex signature.

Signal definition

The preparation of the signal to be transmitted is done in the class file SExample.class. You can define the name of the class file and the signal name - here SComplex - yourself:

[1] ' Gambas class file
[2]
[3] Inherits DBusObject
[4] Create Static
[5]
[6] ' (Pseudo-) Signature: "sia{si}" => String Integer Collection(Key-Type = String, Value-Type = Integer)
[7]
[8] Event org_gambas_SignalTXC_SExample_SComplex(GBVersion As String, Month As Integer, c As Collection)

As you can see, the signal 'SComplex' has exactly three arguments with three different data types and thus follows the signature “sia{si}”.

Signal sender

Figure 24.9.6.3.1: Signal sender

The following source code has a special feature with lines 8, 25, 71 and the area with lines 30 to 44. The transmitted signal is immediately intercepted by the server and the content is output in the console for control purposes. This special feature helped in testing the project.

Source code transmitter:

[1] ' Gambas class file
[2]
[3] Private $sDBusName As String
[4] Private $hDBusObject As SExample
[5] Private $sDBusObjectPath As String
[6] Private $sDBusInterface As String
[7]
[8] Private $hDBusSignal As DBusSignal
[9]
[10] Public Sub Form_Open()
[11]
[12]   FMain.Resizable = False
[13]
[14]   DBus.Unique = True
[15]
[16] ' For tests only: DBus.Debug = True
[17]
[18]   $sDBusName = DBus.Name
[19]   $hDBusObject = New SExample
[20]   $sDBusObjectPath = "/SExample"
[21]   $sDBusInterface = "org.gambas.SignalTXC.SExample"
[22]
[23]   DBus.Session.Register($hDBusObject, $sDBusObjectPath)
[24] ' Only for control
[25]   $hDBusSignal = New DBusSignal(DBus.Session, $sDBusInterface, True) As "ComplexSignal"
[26]
[27] End
[28]
[29] ' Only for control
[30] Public Sub ComplexSignal_Signal(Signal As String, Arguments As Variant[])
[31]
[32]   Dim c As Collection
[33]   Dim vValue As Variant
[34]
[35]   If Signal = "SComplex" Then
[36]      Print Signal; " : "; Arguments[0]
[37]      Print "Month : " & Arguments[1]
[38]      c = Arguments[2]
[39]      For Each vValue In c
[40]        Print c.Key; " : "; vValue
[41]      Next
[42]   Endif
[43]
[44] End
[45]
[46] Public Sub btnSend_Click()
[47]
[48]   Dim SGambasVersion, sSignalName As String
[49]   Dim iMonth As Integer
[50]   Dim cCollection As Collection
[51]   Dim aArguments As Variant[]
[52]
[53]   sSignalName = "org.gambas.SignalTXC.SExample.SComplex"
[54]   sGambasVersion = System.FullVersion
[55]   iMonth = Month(Now())
[56]   cCollection = ["First": 1, "Second": 2, "Third": 3]
[57]
[58]   aArguments = [sGambasVersion, iMonth, cCollection]
[59]
[60]   lblCaption.Foreground = Color.Red
[61]   DBus[$sDBusName].Raise($hDBusObject, sSignalName, aArguments)
[62] ' DBus.Raise($hDBusObject, sSignalName, [SGambasVersion, iMonth, cCollection]) ' Alternative
[63]   Wait 0.1
[64]   lblCaption.Foreground = Color.Black
[65]
[66] End
[67]
[68] Public Sub Form_Close()
[69]
[70]   If DBus.IsRegistered($hDBusObject) Then DBus.Session.Unregister($hDBusObject)
[71]   If $hDBusSignal Then $hDBusSignal.Enabled = False
[72]   FMain.Close()
[73]
[74] End

Comment:

• In line 23, the D-Bus object with the object path '/SExample' is exported to the Session D-Bus.
• In lines 54 to 56, the values of the three signal arguments are set and passed as elements to the array of arguments 'aArguments' in line 58.
• The sending of the signal is triggered in line 61 or alternatively in line 62.
• Since a D-Bus object with the D-Bus object path '/SExample' has been exported to the D-Bus, it is unregistered in line 70.
• In line 71, the additionally established signal observer is switched off before the programme is terminated.

The client SignalRXC permanently observes the signal with the name 'SComplex' of the D-Bus object with the path '/SExample' of the application with the D-Bus name org.gambas.SignalTXC on the session D-Bus.

The source code for the client SignalRXC is given in full and then commented:

[1] ' Gambas class file
[2]
[3] Private $hDBusSignal As DBusSignal
[4] Private $sDBusInterface As String
[5]
[6] Public Sub Form_Open()
[7]
[8]   Dim sMessage As String
[9]
[10]   If Not DBus.Session.Applications.Exist("org.gambas.SignalTXC") Then
[11]      sMessage = ("There is no suitable data server on the session bus!")
[12]      sMessage &= "<center><font color='red'>"
[13]      sMessage &= ("The program is terminated.")
[14]      sMessage &= "</font></center>"
[15]      Message.Warning(sMessage)
[16]      Quit
[17]   Endif
[18]
[19]   FMain.Resizable = False
[20]   lblCaption.Text = ("WATCHING SPECIAL SIGNAL")
[21] ' For tests only: DBus.Debug = True
[22]
[23]   $sDBusInterface = "org.gambas.SignalTXC.SExample"
[24]
[25]   $hDBusSignal = New DBusSignal(DBus.Session, $sDBusInterface, True) As "ObservedSignal"
[26]
[27] End
[28]
[29] Public Sub ObservedSignal_Signal(Signal As String, Arguments As Variant[])
[30]
[31]   Dim c As Collection
[32]   Dim vValue As Variant
[33]
[34]   If Signal = "SComplex" Then
[35]      txaResult.Insert(gb.NewLine)
[36]      txaResult.Insert("Gambas-Version = " & Arguments[0] & gb.NewLine)
[37]      txaResult.Insert("Month : " & Arguments[1] & gb.NewLine)
[38]      c = Arguments[2]
[39]      For Each vValue In c
[40]        txaResult.Insert(c.Key & " : " & vValue & gb.NewLine)
[41]      Next
[42]      txaResult.Pos = txaResult.Length
[43]   Endif
[44]
[45] End
[46]
[47] Public Sub btnIntrospection_Click()
[48]
[49]   Dim hDBusApplication As DBusApplication
[50]   Dim hDBusType As DBusConnection
[51]   Dim hDBusProxy As DBusProxy
[52]
[53]   Dim sDBusName As String
[54]   Dim sDBusObjectPath As String
[55]   Dim sIntrospection As String
[56]
[57]   If DBus.Session.Applications.Exist("org.gambas.SignalTXC") Then
[58]      hDBusType = DBus.Session
[59]      sDBusName = "org.gambas.SignalTXC"
[60]      hDBusApplication = New DBusApplication(hDBusType, sDBusName)
[61]
[62]      sDBusObjectPath = "/SExample"
[63]
[64]      Try hDBusProxy = New DBusProxy(hDBusApplication, sDBusObjectPath)
[65]      If Error Then
[66]         Message.Error("ERROR!" & gb.NewLine & Error.Where & gb.NewLine & Error.Text)
[67]         Return
[68]      Endif
[69]      sIntrospection = hDBusProxy.Introspect()
[70]      txaResult.Insert(gb.NewLine & sIntrospection)
[71]      txaResult.Pos = txaResult.Length
[72]   Endif
[73]
[74] End
[75]
[76] Public Sub Form_Close()
[77]
[78]   If $hDBusSignal Then $hDBusSignal.Enabled = False
[79]   FMain.Close()
[80]
[81] End

Comment:

• In line 11, it is checked whether the (server) programme exists. However, this type of check only works if the property DBus.Unique has been set to True in the source code of the server. In chapter 24.9.2.1 you can read about the alternative for the standard case DBus.Unique = False.
• A new signal observer with the event name 'ObservedSignal' is created in line 25.
• In the event handling routine in lines 29 to 45, the signal arguments are read and displayed.
• Lines 47 to 74 are intended to show that for signals - in contrast to properties and methods - it is not possible in d-bus-capable Gambas programs to read out a descriptive XML document (introspection). Obviously, this has not been implemented for signals. Therefore it is important to document the signatures of the signals well in the source code. Otherwise it will be more difficult to evaluate the intercepted signals correctly!
• The signal observer is switched off in line 42 before the client program is terminated.

If the observed signal with the signature “sia{si}” is intercepted, its content is read out. A text area displays a string, a number and the three elements of a collection with suitable labels:

Figure 24.9.6.3.2: Signal receiver