Класс RuntimeDispatcher

Диспетчер задач и интентов приложения. Подробнее…

#include <RuntimeManager/RuntimeDispatcher>

Диаграмма наследования для RuntimeManager::RuntimeDispatcher:

Публичные типы

using HandlerCb = std::function< void(const QJsonObject &reply)>	Функция обратного вызова для обработки ответа.
using CustomHandler = std::function< void(const QJsonObject &params, const HandlerCb &callback)>	Тип функции для обработки интента.
using ApplicationStartedCb = std::function<void()>	Функция обратного вызова при запуске.
using TaskStartedCb = std::function< void(const QString &taskId)>	Функция обратного вызова при старте фонового задания.

Публичные функции

QString applicationId () const	Получает ID приложения.
QString applicationInstanceId () const	Получает ID экземпляра приложения.
QString taskId () const	Возвращает ID фоновой задачи.
void registerIntent (const QString &intentName, const CustomHandler &customHandler)	Регистрирует обработчик интента.
void unregisterIntent (const QString &intentName)	Отменяет регистрацию обработчика интента.
void registerIntentOutputFiles (const QString &intentName, const QStringList &readFilePaths, const QStringList &writeFilePaths)	Позволяет интенту возвращать файловые объекты.
Q_INVOKABLE Error startService ()	Запускает службу обработки интентов.
Q_INVOKABLE Error stopService ()	Останавливает службу обработки интентов.
void onApplicationStarted (const ApplicationStartedCb &callback)	Регистрирует функцию обратного вызова при запуске.
void onTaskStarted (const QString &taskId, const TaskStartedCb &callback)	Регистрирует функцию обратного вызова для запуска задачи.
qintptr localServerSocket () const	Получает сокет-дескриптор задачи.

Статические публичные функции

static RuntimeDispatcher *

instance ()

Подробное описание

Диспетчер задач и интентов приложения.

RuntimeDispatcher представляет собой singleton-класс, позволяющий приложениям регистрироваться в качестве обработчиков конкретных операций или задач (обозначаемых в API как "интенты"). Эти действия могут запрашиваться другими приложениями и предоставляют способ обмена данными между приложениями.

Система определяет набор стандартных интентов, таких как "Start" и "OpenURI". Дополнительная информация о стандартных интентах доступна в разделе Стандартные интенты.

Приложения могут регистрировать произвольные интенты при условии, что их имя начинается с "X-".

Если приложение способно обрабатывать интенты, это должно быть объявлено в манифест-файле. Вот как это указывается в разделе [X-Application] .desktop-файла:

 Intents=<intent-name>[/<detail>]:<flags-separated by "|">;<intent-name>...
 # Пример:
 Intents=X-TextToSpeech;X-SpeechToText

Пример регистрации интента:

auto *dispatcher = RuntimeManager::RuntimeDispatcher::instance();
dispatcher->registerIntent(QStringLiteral("X-MyIntent"),
                           [&dispatcher](const QJsonObject &params,
                                         const RuntimeDispatcher::HandlerCb &reply) {
    // Добавляем логику обработки интента здесь
    QJsonObject response = { ... };
    reply(response);
});

Теперь, после выполнения всех важных действий по регистрации интентов, можно зарегистрировать DBus-сервисы.

Error error = handler->startService();
if (error)
    return EXIT_FAILURE;

Typedef-члены

ApplicationStartedCb

using RuntimeManager::RuntimeDispatcher::ApplicationStartedCb = std::function<void()>

Функция обратного вызова при запуске.

Эта функция должна содержать код, выполняемый при запуске приложения.

См. также onApplicationStarted

CustomHandler

using RuntimeManager::RuntimeDispatcher::CustomHandler = std::function<void(const QJsonObject &params, const HandlerCb &callback)>

Тип функции для обработки интента.

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

Параметры

params	Объект JSON с данными для обработки. Его семантика определяется конкретным вызываемым интентом
callback	Функция, вызываемая после завершения обработки интента

HandlerCb

using RuntimeManager::RuntimeDispatcher::HandlerCb = std::function<void(const QJsonObject &reply)>

Функция обратного вызова для обработки ответа.

Обработчик интента получает данную функцию обратного вызова как параметр и обязан вызвать её после завершения обработки интента. Если нет данных для отправки обратно, следует передать пустой QJsonObject.

TaskStartedCb

using RuntimeManager::RuntimeDispatcher::TaskStartedCb = std::function<void(const QString &taskId)>

Функция обратного вызова при старте фонового задания.

Эта функция должна содержать код, выполняемый фоновой задачей.

Параметры

taskId

ID выполняемой задачи

См. также onTaskStarted

Описание функций-членов

applicationId()

QString RuntimeManager::RuntimeDispatcher::applicationId () const

Получает ID приложения.

Идентификатор приложения одинаков для всех процессов приложения (включая различные экземпляры и фоновые задачи) и постоянен при всех запусках приложения. Обычно он формируется в формате "<organization-name>.<application-name>", однако разработчикам не рекомендуется полагаться на конкретный формат.

Возвращает ID приложения, из которого осуществляется вызов.

applicationInstanceId()

QString RuntimeManager::RuntimeDispatcher::applicationInstanceId () const

Получает ID экземпляра приложения.

Идентификатор экземпляра приложения определяет конкретный экземпляр приложения. Он не постоянен при разных запусках приложения.

Возвращает ID экземпляра приложения, из которого происходит вызов, либо пустая строка при вызове из фонового задания.

localServerSocket()

qintptr RuntimeManager::RuntimeDispatcher::localServerSocket () const

Получает сокет-дескриптор задачи.

Этот метод может быть вызван только из фоновой задачи и возвращает файловый дескриптор, который может использоваться для взаимодействия с приложением (если приложение запросило его через Task::withIpcSocket()). Хотя разработчики могут свободно использовать этот сокет через QLocalSocket или другие API, рекомендуется применять его для создания объекта TaskMessaging:

using namespace RuntimeManager;
auto *dispatcher = RuntimeDispatcher::instance();
TaskMessaging ipc(dispatcher->localServerSocket());
 
// Использование объекта TaskMessaging
QObject::connect(&ipc, &TaskMessaging::messageReceived,
                 [](const QJsonMessage &message) {
qDebug() << "Полученное сообщение от приложения:" << message;
}

onApplicationStarted()

void RuntimeManager::RuntimeDispatcher::onApplicationStarted (const ApplicationStartedCb & callback)

Регистрирует функцию обратного вызова при запуске.

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

Параметры

callback

Код, выполняемый при запуске приложения

Примечание. Обратный вызов может быть выполнен сразу же, даже до возврата значения методом.

См. также onTaskStarted

onTaskStarted()

void RuntimeManager::RuntimeDispatcher::onTaskStarted (const QString & taskId, const TaskStartedCb & callback )

Регистрирует функцию обратного вызова для запуска задачи.

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

Параметры

taskId	ID задачи. Для каждой задачи может быть задан свой обратный вызов
callback	Код, выполняемый при запуске задачи

Примечание. Обратный вызов может быть выполнен сразу же, даже до возврата значения методом.

См. также onApplicationStarted

registerIntent()

void RuntimeManager::RuntimeDispatcher::registerIntent (const QString & intentName, const CustomHandler & customHandler )

Регистрирует обработчик интента.

Параметры

intentName	Имя интента
customHandler	Функция для выполнения при вызове интента

registerIntentOutputFiles()

void RuntimeManager::RuntimeDispatcher::registerIntentOutputFiles (const QString & intentName, const QStringList & readFilePaths, const QStringList & writeFilePaths )

Позволяет интенту возвращать файловые объекты.

Этот метод позволяет приложениям отправлять файлы в ответах на интенты: он регистрирует два набора правил. readFilePaths и writeFilePaths, чтобы идентифицировать, какие элементы в JSON-ответе являются путями к файлам, которые должны быть предоставлены вызывающей стороне для чтения и для записи соответственно.

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

Параметры

intentName	Имя интента
readFilePaths	Список JSON-путей, идентифицирующих файлы, которые должны быть предоставлены в режиме только для чтения
writeFilePaths	Список JSON-путей, идентифицирующих файлы, которые должны быть предоставлены в режиме чтения-записи

Примечание. Поддерживаемые JSON-пути представляют собой небольшое подмножество описанных в JSONPath RFC 9535 (https://datatracker.ietf.org/doc/html/rfc9535): "key", "key.subkey", "array[index]", "key.", "array[]" и простые комбинации этих конструкций.

startService()

Error RuntimeManager::RuntimeDispatcher::startService ()

Запускает службу обработки интентов.

Завершает инициализацию RuntimeDispatcher и подготавливает это приложение к приёму запросов интентов.

stopService()

Error RuntimeManager::RuntimeDispatcher::stopService ()

Останавливает службу обработки интентов.

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

taskId()

QString RuntimeManager::RuntimeDispatcher::taskId () const

Возвращает ID фоновой задачи.

Идентификатор задачи (task ID) — это ID фоновой задачи, постоянный при разных запусках (примечание: только один экземпляр фоновой задачи может выполняться в любой момент времени).

Возвращает ID задачи или пустую строку, если вызов произведён не из задачи.

unregisterIntent()

void RuntimeManager::RuntimeDispatcher::unregisterIntent (const QString & intentName)

Отменяет регистрацию обработчика интента.

Параметры

intentName

Имя интента для отмены регистрации