Объявление слотов в адаптерах D-Bus

Слоты в адаптерах D-Bus объявляются так же, как обычные публичные слоты, но их параметры должны соответствовать определённым правилам (см. Система типов Qt D-Bus для получения дополнительной информации). Слоты, параметры которых не соответствуют этим правилам или которые не являются публичными, не будут доступны через D-Bus.

Слоты могут иметь один параметр типа const QDBusMessage &, который должен стоять в конце списка входных параметров, перед любыми выходными параметрами. Этот параметр, если он присутствует, будет инициализирован копией текущего обрабатываемого сообщения, что позволяет вызываемому коду получить информацию о вызывающем коде, такую как имя его подключения.

Слоты могут быть трёх типов:

1. Асинхронные
2. Только входные
3. Входные и выходные

Асинхронные слоты

Асинхронные слоты — это те, которые обычно не возвращают никакого ответа вызывающему коду. По этой причине они не могут принимать выходные параметры. В большинстве случаев, к моменту выполнения первой строки слота, функция-вызывающая уже возобновила свою работу.

Однако слоты не должны полагаться на это поведение. Вопросы планирования и обработки сообщений могут изменить порядок выполнения слота. Код, предназначенный для синхронизации с вызывающей стороной, должен обеспечить собственный метод синхронизации.

Асинхронные слоты отмечаются ключевым словом Q_NOREPLY в сигнатуре метода, перед типом возврата void и именем слота. Слоты quit() в примере D-Bus Complex Ping Pong являются примером этого.

Слоты только для входных данных

Слоты только для входных данных — это обычные слоты, которые принимают параметры, передаваемые по значению или по постоянной ссылке. Однако, в отличие от асинхронных слотов, вызывающая сторона обычно ожидает завершения вызываемой стороны перед возобновлением работы. Поэтому слоты, не являющиеся асинхронными, не должны блокировать или должны указывать в документации, что могут это делать.

Слоты только для входных данных не имеют специальных пометок в своей сигнатуре, за исключением того, что они принимают только параметры, передаваемые по значению или по постоянной ссылке. Необязательно, слоты могут принимать параметр QDBusMessage в качестве последнего параметра, который может быть использован для выполнения дополнительного анализа сообщения вызова метода.

Слоты входные и выходные

Как и слоты только для входных данных, слоты входные и выходные — это те, для которых вызывающая сторона ожидает ответа. В отличие от только входных, однако, этот ответ будет содержать данные. Слоты, выдавающие данные, могут содержать ссылки, не являющиеся константными, и могут возвращать значение. Однако выходные параметры должны располагаться в конце списка аргументов и не могут иметь входные аргументы, перемешанные с ними. Необязательно, аргумент QDBusMessage может появляться между входными и выходными аргументами.

Автоматические ответы

Ответы на методы генерируются автоматически с содержимым выходных параметров (если они есть) реализацией Qt D-Bus. Слоты не должны беспокоиться о создании правильных объектов QDBusMessage и отправке их по подключению.

Однако, возможность этого остаётся. Если слот обнаружит, что ему нужно отправить специальный ответ или даже ошибку, он может сделать это, используя QDBusMessage::createReply() или QDBusMessage::createErrorReply() для параметра QDBusMessage и отправить его с помощью QDBusConnection::send(). Реализация Qt D-Bus не будет генерировать ответ, если слот сделал это.

Предупреждение: Когда вызывающая сторона размещает вызов метода и ожидает ответа, она будет ждать только ограниченное время. Слоты, которые планируют занимать много времени для завершения, должны четко указывать этот факт в документации, чтобы вызывающая сторона могла правильно установить более высокие таймауты.

Задержанные ответы

В некоторых обстоятельствах вызываемый слот может не иметь возможности немедленно обработать запрос. Это часто случается, когда запрос включает операцию ввода-вывода или сетевую операцию, которая может блокировать.

В этом случае слот должен вернуть управление в основной цикл приложения, чтобы избежать зависания пользовательского интерфейса, и возобновить процесс позже. Для этого он должен использовать дополнительный параметр QDBusMessage в конце списка входных параметров и запросить задержанный ответ.

Мы делаем это, написав слот, который сохраняет данные запроса в постоянной структуре, указывая вызывающей стороне с помощью QDBusMessage::setDelayedReply(true), что ответ будет отправлен позже.

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();
    QDBusConnection::sessionBus().send(data->reply);

    appendRequest(data);
    return QString();
}

Использование QDBusConnection::sessionBus().send(data->reply) необходимо для явного информирования вызывающей стороны о том, что ответ будет задержан. В этом случае возвращаемое значение не имеет значения; мы возвращаем произвольное значение, чтобы удовлетворить компилятор.

Когда запрос обработан и ответ доступен, он должен быть отправлен с помощью объекта QDBusMessage, который был получен. В нашем примере код ответа мог бы быть следующим:

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;
}

Как видно из примера, когда задержанный ответ установлен, возвращаемое значение(я) слота игнорируются Qt D-Bus. Они используются только для определения сигнатуры слота при передаче описания адаптера удалённым приложениям или в случае, если код в слоте решает не использовать задержанный ответ.

Сам задержанный ответ запрашивается у Qt D-Bus путем вызова QDBusMessage::reply() на исходном сообщении. Затем ответственность за последующую отправку ответа вызывающей стороне ложится на вызываемый код.

Предупреждение: Когда вызывающая сторона размещает вызов метода и ожидает ответа, она будет ждать только ограниченное время. Слоты, которые планируют занимать много времени для завершения, должны четко указывать этот факт в документации, чтобы вызывающая сторона могла правильно установить более высокие таймауты.

См. также Использование адаптеров Qt D-Bus, Объявление сигналов в адаптерах D-Bus, Система типов Qt D-Bus, QDBusConnection и QDBusMessage.