DBus et Gambas
Introduction
Le système
DBus est (presque) entièrement pris en charge en Gambas 3, par le composant
gb.dbus.
Qu’est-ce que DBus ? c’est un "système de bus de messages", c.à d. un petit programme qui peut transmettre différentes sortes de messages entre les applications. C’est comme le vieux système KDE 3 DCOP.
Pour de plus amples informations, voir
http://dbus.freedesktop.org.
Il y a normalement deux types de bus qui tournent sur votre machine : le " bus système ",
qui est global et unique, et le " bus session ", qui est lancé pour chaque utilisateur connecté.
gb.dbus vous permet :
-
d’appeler toute méthode ou propriété exportée par toute application connectée au bus.
-
d’intercepter tout signal émis par une interface quelconque.
-
d’exporter tout objet Gambas vers DBus.
Notez que le composant gb.dbus a une partie écrite en C et une partie écrite en Gambas. La partie écrite en C fournit des classes cachées (dont le nom commence par "_") que la partie écrite en Gambas utilise pour fournir l'interface composant complet (et facilement !).
Utilisation des objets exportés par les autres applications
Méthodes d’appel ou propriétés
Pour appeler une méthode, utilisez la syntaxe suivante :
DBus[Application][ObjectPath].Method(Arguments)
Pour obtenir la valeur d’une propriété, faites :
DBus[Application][ObjectPath].Property
Et pour définir la valeur d’une propriété, faites :
DBus[Application][ObjectPath].Property = Value
est la chaîne qui identifie l’application sur le bus.
Elle peut commencer par
"système://" ou
"session://" pour définir quel bus vous voulez vous connecter.
Par défaut vous vous connectez au bus session.
Exemples
DBus["org.kde.kmail"]["/kmail/kmail_mainwindow_1"].geometry = [0, 24, 1024, 768]
Interception de signaux
L’ interception de signaux repose sur deux classes :
DBusObserver, et
DBusSignal.
DBusObserver est une classe de bas niveau que vous ne devriez pas employer en dehors de besoins très spécifiques.
Utilisez à la place la classe DBusSignal qui s’appuie sur la classe DBusObserver.
Pour surveiller un signal, créez simplement un nouvel objet DBusSignal de cette manière :
hSignal = New DBusSignal(Bus, Interface, Every) As "MySignal"
-
Bus est le bus auquel vous vous connectez.
-
Interface est le nom de l’interface qui émet le signal.
-
Every est un drapeau booléen optionnel qui vous autorise à intercepter les signaux envoyés à toutes les applications, pas seulement aux vôtres.
Exemples
MySignal = New DBusSignal(DBus.System, "org.freedesktop.Hal.Manager") As "DBusSignal"
...
Public Sub DBusSignal_Signal([../../comp/gb.signal/signal] As [../../comp/gb/string], Arguments As [../../lang/type/variant][])
If Signal = "DeviceAdded" Then
...
EndIf
End
Export d'un objet Gambas dans d'autres applications
Enregistrement de l’objet
Pour exporter un objet Gambas vers le
DBus, cet objet doit hériter de la classe
DBusObject.
Vous devez ensuite l’enregistrer sur le bus avec le
DBus.Session.Register ou la Méthode DBus.Register.
Utilisez la première méthode pour enregistrer votre objet sur le bus
Session, la deuxième pour l'enregistrer sur le bus
System.
Examples
Dim hObject As MyClass ' MyClass inherits DBusObject
DBus.Session.Register(hObject, "/object/path")
L’objet Gambas est attaché à un "chemin d'objet", car tous les objets exposés à DBus par votre application sont comme un système de fichier hiérarchique.
Dès lors qu'au moins un objet est enregistré, votre application sera visible sur le bus.
Le nom de votre application sur le bus est défini par la propriété
DBus.Name. Par défaut, il est défini comme
org.gambas.
où
est la valeur de
Application.Name.
Qu’est-ce qui est exporté ?
-
Les méthodes publiques dont le nom ne contient pas d'underscore (tiret bas), et dont les arguments et le type de retour peuvent être convertis en un type de donnée DBus.
-
Le propriétés publiques dont le nom ne contient pas d’underscore, et dont le type peut être converti en un type de donnée DBus.
Dès que vous enregistrez au moins un objet, votre application apparaît sur le bus avec le nom
"org.gambas.<nom d’application>".
Toutes ces méthodes et propriétés sont exportées avec un nom d’interface appelé
"org.gambas.<nom d’application>.<nom de classe>".
Vous pouvez tester ceci avec l’exemple d’explorateur DBus, ou le programme Qt4 qdbusviewer.
Implémentation d'une interface spécifique
Un objet peut implémenter des interfaces
DBus spécifiques en utilisant le troisième argument optionnel de la méthode Register .
Ce troisième argument est un tableau de chaînes de noms d'interface.
Si cet argument n'est pas spécifié, alors, comme précédemment, toutes les méthodes
et les propriétés publiques sont placées sous l'interface
org.gambas..
.
Mais si cet argument est spécifié, toutes les méthodes et les propriétés publiques dont les noms commencent par le nom de l'interface sont placées sous cette interface.
Le nom de l'interface est normalisé dans le nom de la méthode, en remplaçant les points par des underscores,
et en ajoutant un autre underscore entre le nom de l'interface et le nom de la méthode.
Exemples
' "Open" method of the org.mpris.MediaPlayer2 interface
Public Sub org_mpris_MediaPlayer2_Open()
...
End
' "Play" method of the org.mpris.MediaPlayer2.Player interface
Public Sub org_mpris_MediaPlayer2_Player_Play()
...
End
' "Enabled" property of the org.mpris.MediaPlayer2 interface
Property org_mpris_MediaPlayer2_Enabled As Boolean
...
DBus.Session.Register(MyMediaPlayer, "/org/mpris/MediaPlayer2",["org.mpris.MediaPlayer2","org.mrpris.MediaPlayer2.Player"])
Émission de signaux
Depuis 3.9
Vous pouvez émettre des signaux DBus seulement à partir de la version 3.9.
Pour permettre à un objet d'émettre des signaux, vous devez d'abord les déclarer comme des évènements Gambas.
Le nom de lévènement doit être le nom normalisé de l'interface, suivi d'un underscore et le nom normalisé du signal.
Le signal est émis vers le bus D-Bus en utilisant la méthode
DBusApplication.Raise.
Par exemple dans le composant
gb.dbus.trayicon, la classe DBusStatusIcon interne est un DBusObject implémentant l'interface
org.kde.StatusNotifierItem qui peut émettre le signal "NewIcon", parmi d'autres.
Il est implémenté de cette manière :
Inherits DBusObject
...
Event org_kde_StatusNotifierItem_NewIcon
...
Le signal "NewIcon" doit être émis quand l'image de l'icône status change. Il est émis dans la fonction qui implémente
la propriété
Picture.
Private Sub Picture_Write(Value As Picture)
...
DBus[GetServiceName()].Raise($hObject, "org.kde.StatusNotifierItem.NewIcon")
End
Datatype mapping
Voici un résumé de la manière dont les types de données de Gambas sont traduits en type de données DBus, et vice versa.
|
Type de donnée Gambas
|
Type de donnée DBus
|
|---|
|
Boolean
|
b
|
|
Byte
|
y
|
|
Short
|
n
q
|
|
Integer
|
i
u
|
|
Long
|
x
t
|
|
Single
|
d
|
|
Float
|
d
|
|
Date
|
d
|
|
Pointer
|
x
|
|
String
|
s
|
|
Variant
|
v
|
|
DBusObject
|
o
|
|
Boolean[]
|
ab
|
|
Byte[]
|
ay
|
|
Short[]
|
an
aq
|
|
Integer[]
|
ai
au
|
|
Long[]
|
ax
at
|
|
Single[]
|
ad
|
|
Float[]
|
ad
|
|
Date[]
|
ad
|
|
Pointer[]
|
ax
|
|
String[]
|
as
|
|
Variant[]
|
av
(TTT)*
aT*
|
|
DBusObject[]
|
ao
|
|
Collection
|
a{sv}
|
*T représente n'importe quel type de données DBus.