Déclaration des slots dans les adaptateurs D-Bus

Les slots dans les adaptateurs D-Bus sont déclarés comme des slots publics normaux, mais leurs paramètres doivent respecter certaines règles (voir Le système de types d'Qt D-Bus pour plus d'informations). Les slots dont les paramètres ne respectent pas ces règles ou qui ne sont pas publics ne seront pas accessibles via D-Bus.

Les slots peuvent comporter un paramètre de type const QDBusMessage &, qui doit figurer à la fin de la liste des paramètres d’entrée, avant tout paramètre de sortie. Ce paramètre, s’il est présent, sera initialisé avec une copie du message en cours de traitement, ce qui permet au destinataire d’obtenir des informations sur l’appelant, telles que le nom de sa connexion.

Il existe trois types de slots :

1. Asynchrones
2. Entrée uniquement
3. Entrée et sortie

Slots asynchrones

Les slots asynchrones sont ceux qui ne renvoient normalement aucune réponse à l'appelant. Pour cette raison, ils ne peuvent accepter aucun paramètre de sortie. Dans la plupart des cas, au moment où la première ligne du slot est exécutée, la fonction appelante a déjà repris son exécution.

Cependant, les slots ne doivent pas se fier à ce comportement. Des problèmes d’ordonnancement et de distribution des messages pourraient modifier l’ordre d’exécution du slot. Le code destiné à se synchroniser avec l’appelant doit fournir sa propre méthode de synchronisation.

Les slots asynchrones sont signalés par le mot-clé « Q_NOREPLY » dans la signature de la méthode, avant le type de retour « void » et le nom du slot. Le slot « quit() » de l’exemple D-Bus Complex Ping Pong en est un exemple.

Slots en entrée uniquement

Les slots en lecture seule sont des slots normaux qui acceptent des paramètres passés par valeur ou par référence à une constante. Cependant, contrairement aux slots asynchrones, l’appelant attend généralement que l’appelé ait terminé avant de reprendre son exécution. Par conséquent, les slots non asynchrones ne doivent pas bloquer l’exécution ou doivent explicitement indiquer dans leur documentation qu’ils sont susceptibles de le faire.

Les slots en lecture seule ne comportent aucune indication particulière dans leur signature, si ce n'est qu'ils n'acceptent que des paramètres passés par valeur ou par référence à une constante. En option, les slots peuvent accepter un paramètre « QDBusMessage » en dernier paramètre, qui peut être utilisé pour effectuer une analyse supplémentaire du message d'appel de méthode.

Slots d’entrée et de sortie

À l’instar des slots en entrée uniquement, les slots en entrée et en sortie sont ceux pour lesquels l’appelant attend une réponse. Contrairement aux slots en entrée uniquement, cette réponse contiendra toutefois des données. Les slots qui produisent des données peuvent contenir des références non constantes et peuvent également renvoyer une valeur. Toutefois, les paramètres de sortie doivent tous figurer à la fin de la liste d’arguments et ne doivent pas être entrecoupés d’arguments d’entrée. Un argument « QDBusMessage » peut éventuellement apparaître entre les arguments d’entrée et de sortie.

Réponses automatiques

Les réponses de méthode sont générées automatiquement à partir du contenu des paramètres de sortie (le cas échéant) par l’implémentation de ` Qt D-Bus `. Les slots n’ont pas à se soucier de construire des objets ` QDBusMessage ` corrects ni de les envoyer via la connexion.

Cependant, cette possibilité demeure. Si le slot se rend compte qu’il doit envoyer une réponse spéciale, voire une erreur, il peut le faire en utilisant ` QDBusMessage::createReply()` ou ` QDBusMessage::createErrorReply()` sur le paramètre ` QDBusMessage ` et l’envoyer avec ` QDBusConnection::send()`. L’implémentation de ` Qt D-Bus ` ne générera aucune réponse si le slot procède ainsi.

Réponses différées

Dans certaines circonstances, le slot appelé peut ne pas être en mesure de traiter la requête immédiatement. C’est souvent le cas lorsque la requête implique une opération d’E/S ou de réseau susceptible de se bloquer.

Si tel est le cas, le slot doit rendre le contrôle à la boucle principale de l’application pour éviter de figer l’interface utilisateur, puis reprendre le traitement ultérieurement. Pour ce faire, il doit utiliser le paramètre supplémentaire ` QDBusMessage ` à la fin de la liste des paramètres d’entrée et demander une réponse différée.

Pour ce faire, on écrit un slot qui stocke les données de la requête dans une structure persistante, en indiquant à l’appelant, via QDBusMessage::setDelayedReply(true), que la réponse sera envoyée ultérieurement.

struct RequestData
{
    QString request;
    QString processedData;
    QDBusMessage reply;
};

QString processRequest(const QString &request, const QDBusMessage &message)
{
    RequestData *data = new RequestData;
    data->request = request;
    message.setDelayedReply(true);
    data->reply = message.createReply();

    appendRequest(data);
    return QString();
}

Dans ce cas, la valeur de retour n’a pas d’importance ; nous renvoyons une valeur arbitraire pour satisfaire le compilateur.

Une fois la requête traitée et la réponse disponible, celle-ci doit être envoyée à l’aide de l’objet ` QDBusMessage ` obtenu précédemment. Dans notre exemple, le code de réponse pourrait se présenter comme suit :

void sendReply(RequestData *data)
{
    // data->processedData has been initialized with the request's reply
    QDBusMessage &reply = data->reply;

    // send the reply over D-Bus:
    reply << data->processedData;
    QDBusConnection::sessionBus().send(reply);

    // dispose of the transaction data
    delete data;
}

Comme le montre l’exemple, lorsqu’une réponse différée est mise en place, la ou les valeurs de retour du slot seront ignorées par ` Qt D-Bus`. Elles ne servent qu’à déterminer la signature du slot lors de la communication de la description de l’adaptateur aux applications distantes, ou dans le cas où le code du slot déciderait de ne pas utiliser de réponse différée.

La réponse différée elle-même est demandée à Qt D-Bus en appelant QDBusMessage::reply() sur le message d’origine. Il incombe alors au code appelé d’envoyer, le moment venu, une réponse à l’appelant.