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 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 avoir un paramètre de type const QDBusMessage &, qui doit apparaître à 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 à l'appelant d'obtenir des informations sur l'appelant, comme son nom de connexion.

Les slots peuvent être de trois types :

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

Créneaux asynchrones

Les slots asynchrones sont ceux qui ne renvoient normalement aucune réponse à l'appelant. Pour cette raison, ils ne peuvent pas prendre de paramètres de sortie. Dans la plupart des cas, lorsque la première ligne du slot est exécutée, la fonction appelante a déjà repris son travail.

Cependant, les slots ne doivent pas se fier à ce comportement. Des problèmes d'ordonnancement et de répartition des messages peuvent modifier l'ordre d'exécution du slot. Le code qui a l'intention de se synchroniser avec l'appelant doit fournir sa propre méthode de synchronisation.

Les slots asynchrones sont marqué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() dans l'exemple D-Bus Complex Ping Pong en est un exemple.

Slots à entrée unique

Les slots en entrée seule sont des slots normaux qui prennent des paramètres transmis par valeur ou par référence constante. Cependant, contrairement aux slots asynchrones, l'appelant attend généralement la fin de l'appelant avant de reprendre l'opération. Par conséquent, les slots non asynchrones ne doivent pas se bloquer ou doivent explicitement indiquer qu'ils se bloqueront dans leur documentation.

Les slots d'entrée uniquement n'ont pas de marquage spécial dans leur signature, si ce n'est qu'ils ne prennent que des paramètres passés par valeur ou par référence constante. En option, les slots peuvent prendre un paramètre QDBusMessage comme dernier paramètre, qui peut être utilisé pour effectuer une analyse supplémentaire du message d'appel de la méthode.

Créneaux d'entrée et de sortie

Comme les slots d'entrée seule, les slots d'entrée et de sortie sont ceux pour lesquels l'appelant attend une réponse. Contrairement aux slots d'entrée uniquement, cette réponse contiendra 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 les arguments d'entrée ne peuvent pas être intercalés. En option, un argument QDBusMessage peut apparaître entre les arguments d'entrée et de sortie.

Réponses automatiques

Les réponses aux méthodes sont générées automatiquement avec le contenu des paramètres de sortie (s'il y en a) par l'implémentation de Qt D-Bus. Les slots n'ont pas à se préoccuper de construire des objets QDBusMessage appropriés et de les envoyer via la connexion.

Cependant, la possibilité de le faire demeure. Si le slot constate qu'il doit envoyer une réponse spéciale ou même 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 le fait.

Réponses retardées

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

Dans ce cas, le slot doit renvoyer le contrôle à la boucle principale de l'application pour éviter de geler l'interface utilisateur, et reprendre le processus plus tard. 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, nous écrivons un slot qui stocke les données de la requête dans une structure persistante, en indiquant à l'appelant à l'aide de QDBusMessage::setDelayedReply(true) que la réponse sera envoyée plus tard.

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.

Lorsque la requête est traitée et qu'une réponse est disponible, elle doit être envoyée en utilisant l'objet QDBusMessage qui a été obtenu. Dans notre exemple, le code de réponse pourrait être le suivant :

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 on peut le voir dans l'exemple, lorsqu'une réponse différée est en place, la ou les valeurs de retour du slot sont ignorées par Qt D-Bus. Elles ne sont utilisées que pour déterminer la signature du slot lors de la communication de la description de l'adaptateur à des applications distantes, ou dans le cas où le code du slot décide 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 original. Il incombe alors au code appelé d'envoyer une réponse à l'appelant.