Documentation de Gambas - /doc/dbus

/doc/dbus

# DBus and Gambas

- Introduction

- Utilisation des objets exportes par les autres applications

  - Méthodes d’appel ou propriétés.

  - Interception de signaux

- Exporter un objet Gambas

  - Enregistrer l’objet

  - Qu’est-ce qui est exporté?

  - Implémentation d'une interface spécifique

  - Émission de signaux

## Introduction

Le système DBus est (presque) entièrement pris en charge en Gambas 3, par le composant gb.dbus.

Qu’est-ce que c’est 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 plus ample information, 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 est partiellement écrit en C et partiellement en Gambas. La partie écrite en C fournit des classes cachées (dont le nom commence par `"_"`) pour que la partie écrite en Gambas puisse mettre à disposition le composant interface complet (et facile à employer!).

## Utilisation des objets exportes 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

Application est la chaîne qui identifie l’application sur le bus. Elle peut commencer par `"système:/"` ou `"session:**"` pour fixer à quel bus vous voulez vous connecter.

Par défaut vous vous connectez au bus session.

DBus/wiki/"/kmail/kmail_mainwindow_1".geometry = /wiki/0, 24, 1024, 768

### Interception de signaux

L’ interception de signaux repose sur deux classes : DBusObserver, et DBusSignal.

DBusObserver est une classe 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 les votres !.

MySignal = New DBusSignal(DBus.Systém, "org.freedesktop.Hal.Manager") As "DBusSignal"

...

Public Sub DBusSignal_Signal(Signal As String, Arguments As Variant)

If Signal = "DeviceAdded" Then ... EndIf

End

## Exporter un objet Gambas

### Enregistrer 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 l'enregistre sur le bus System.

Dim hObject As MyClass ' MyClass inherits DBusObject

DBus.Register(hObject, "/object/path")

L’objet Gambas est attaché à un "chemin object", car tous les objets exposés a 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 Public dont le nom ne contient pas d’underscore (tiret bas de casse), et dont les arguments et type retournés peuvent être convertis en un type de donnée DBus.

- Le propriétés Public dont le nom ne contient pas d’underscore, et dont les type peuvent être convertis 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 qdbusviewer Qt4.

### 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'interfaces.

Si cet argument n'est pas spécifié, alors, comme précédemment, toutes les méthodes public et les propriétés sont placées sous l'interface `org.gambas..` .

Mais si cet argument est spécifié, toutes les méthodes public et les propriétés dont les noms commencent par le nom de l'interface sont placées sous cette interface.

Le nom de l'interface est normalisé dans la méthode name, 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.

' méthode "Open" de l'interface org.mpris.MediaPlayer2 Public Sub org_mpris_MediaPlayer2_Open() ... End

' méthode "Play" de l'interface org.mpris.MediaPlayer2.Player Public Sub org_mpris_MediaPlayer2_Player_Play() ... End

' propriété "Enabled" de l'interface org.mpris.MediaPlayer2 propriété org_mpris_MediaPlayer2_Enabled As Boolean

...

DBus.Session.Register(MyMediaPlayer, "/org/mpris/MediaPlayer2",mpris.mediaplayer2","org.mrpris.mediaplayer2.player" ?)

### Émission de signaux

Vous ne pouvez pas émettre de signaux DBus. Ça n’est pas encore implémenté!