Интерфейс IProcessControl

KasperskyOS API > Компонент ExecutionManager > Интерфейс IProcessControl

Интерфейс IProcessControl

API определен в заголовочном файле sysroot-*-kos/include/alm/execution_manager/i_process_control.h из состава KasperskyOS SDK.

API позволяет:

запускать процесс из исполняемого файла, установленного компонентом PackageManager из KPA-пакета в решение на базе KasperskyOS;
получать сведения о процессе (включая информацию о его завершении);
останавливать процесс.

Сведения о функциях API приведены в таблице ниже.

Запуск процесса

Чтобы запустить процесс, нужно вызвать функцию StartProcess(). Через входной параметр opts эта функция принимает параметры для запуска процесса в виде структуры StartOptions. Все поля этой структуры являются опциональными для инициализации.

struct StartOptions
{
    // Дескриптор, который идентифицирует родительский процесс.
    IpcHandle       parent{NK_INVALID_HANDLE, 0, NK_INVALID_HANDLE};
    // Список пользовательских дескрипторов,
    // которые будут переданы процессу при его запуске.
    UserHandleItems userHandles;
    // Аргументы командной строки.
    Strings         extraArgs;
    // Переменные окружения.
    Strings         extraEnvs;};

При инициализации структуры StartOptions транспортный контейнер дескриптора parent заполняется значениями по умолчанию, которые означают отсутствие родительского процесса. Передавая в этом параметре запускаемому дочернему процессу дескриптор родительского процесса, можно создавать иерархию процессов.

Вектор userHandles является компонентом структуры StartOptions и содержит список пользовательских дескрипторов, которые будут переданы процессу при его запуске. Элементами списка являются пары, задаваемые в структуре UserHandleItem и состоящие из дескриптора и его имени. После запуска процесса переданные ему дескрипторы могут быть найдены с помощью функции KosTaskLookupResource() по их именам.

struct UserHandleItem
{
    // Имя дескриптора.
    std::string id;
    // Дескриптор.
    IpcHandle   handle;
};

Входные параметры pkgId и runConfigId функции StartProcess() определены в манифесте KPA-пакета. Их значения могут быть получены с использованием функций из интерфейса IPackageManifest компонента PackageManager.

Остановка процесса

Чтобы остановить процесс, нужно вызвать функцию StopProcess(). Через входной параметр stopPolicy эта функция принимает политику остановки процесса из перечисления StopPolicy.

enum class StopPolicy : uint32_t
{
    // Отправить процессу сигнал на остановку.
    Normal = 0,
    // Немедленно остановить процесс.
    Forced,
};

Получение сведений о процессе

Чтобы запросить сведения о процессе, нужно вызвать функцию GetProcessState(). Через выходной параметр state эта функция возвращает сведения о процессе в виде структуры ProcessContext.

struct ProcessContext
{
    // Состояние процесса.
    ProcessState         state{};
    // Системный статус завершения процесса.
    ExecutableExitStatus exitStatus{};
    // Общий код завершения процесса.
    ExecutableExitCode   exitCode{};
    // Уточняющий код завершения процесса.
    ExecutableExitReason exitReason{};
};

Перечисление state является компонентом структуры ProcessContext и описывает состояние процесса.

enum class ProcessState : uint32_t
{
    // Служебная константа.
    None = 0,
    // Процесс создан.
    Created,
    // Процесс инициализирован.
    Prepared,
    // Процесс запущен.
    Running,
    // Процесс аварийно остановлен.
    Failed,
    // Процесс остановлен, но данные о процессе доступны
    // для функции GetProcessState().
    Finished,
    // Процесс завершен и не существует в системе.
    NotExisting,
};

Перечисление exitStatus является компонентом структуры ProcessContext и описывает причину остановки процесса. Перечисление ExecutableExitStatus определено в заголовочном файле sysroot-*-kos/include/alm/execution_manager/execution_manager_types.h из состава KasperskyOS SDK.

enum class [[nodiscard]] ExecutableExitStatus : std::underlying_type_t<TaskExitStatus>
{
    // Процесс ещё не запущен компонентом ExecutionManager.
    ExitUninitialized = TaskExitStatus::TaskExitUninitialized,
    // Процесс аварийно остановлен в результате необработанного исключения.
    ExitUnexpected    = TaskExitStatus::TaskExitUnexpected,
    // Процесс завершил работу самостоятельно, в том числе
    // после получения сигнала на свою остановку при вызове
    // функции StopProcess() со значением Normal в политике остановки процесса.
    ExitNormal        = TaskExitStatus::TaskExitNormal,
    // Процесс остановлен по внешнему запросу, в том числе вызовом функции
    // StopProcess() со значением Forced в политике остановки процесса.
    ExitTerminated    = TaskExitStatus::TaskExitTerminated,
};

Числовой параметр exitCode является компонентом структуры ProcessContext и содержит код возврата для процесса, который остановился самостоятельно, в том числе после получения сигнала на свою остановку. Значения для этого кода возврата определяются разработчиком решения на базе KasperskyOS.

Числовой параметр exitReason является компонентом структуры ProcessContext и содержит код возврата, который уточняет причину неудачной попытки запуска процесса, либо rcOk в случае успешного запуска. Параметр определен в заголовочном файле sysroot-*-kos/include/rtl_cpp/retcode.h из состава KasperskyOS SDK. В этом файле содержатся коды возврата, которые являются общими для API любых компонентов решения и их составных частей (см. "Коды возврата").

Функции i_process_control.h

Функция	Сведения о функции
`StartProcess()`	Назначение Запускает процесс. Параметры [in] `pkgId` – идентификатор KPA-пакета. [in] `runConfigId` – идентификатор конфигурации запуска. [in] `opts` – структура `StartOptions` с параметрами запуска процесса. [out] `accessToken` – ссылка на дескриптор, который идентифицирует запущенный процесс. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`StopProcess()`	Назначение Останавливает процесс. Параметры [in] `accessToken` – дескриптор, который идентифицирует запущенный процесс. [in] `stopPolicy` – политика остановки процесса. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetProcessState()`	Назначение Запрашивает сведения о процессе. Параметры [in] `accessToken` – дескриптор, который идентифицирует запущенный процесс. [out] `state` – ссылка на структуру `ProcessContext`, содержащую сведения о процессе. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.

Функция

Сведения о функции

StartProcess()

Назначение

Запускает процесс.

Параметры

[in] pkgId – идентификатор KPA-пакета.
[in] runConfigId – идентификатор конфигурации запуска.
[in] opts – структура StartOptions с параметрами запуска процесса.
[out] accessToken – ссылка на дескриптор, который идентифицирует запущенный процесс.

Возвращаемые значения

В случае успеха возвращает kos::rtl::Ok, иначе возвращает код ошибки.

StopProcess()

Назначение

Останавливает процесс.

Параметры

[in] accessToken – дескриптор, который идентифицирует запущенный процесс.
[in] stopPolicy – политика остановки процесса.

Возвращаемые значения

В случае успеха возвращает kos::rtl::Ok, иначе возвращает код ошибки.

GetProcessState()

Назначение

Запрашивает сведения о процессе.

Параметры

[in] accessToken – дескриптор, который идентифицирует запущенный процесс.
[out] state – ссылка на структуру ProcessContext, содержащую сведения о процессе.

Возвращаемые значения

В случае успеха возвращает kos::rtl::Ok, иначе возвращает код ошибки.

Пример использования:

client.cpp

int main(int argc, const char *argv[])
{
    // ...

    alm::execution_manager::IProcessControl::StartOptions startOptions{};
    alm::execution_manager::IpcHandle procToken{};
    
    // Идентификатор KPA-пакета.
    const std::string   packageId{"application.Application"};
    // Идентификатор конфигурации запуска.
    const std::string   runConfigId{"app"};

    kos::rtl::Result res = pc->StartProcess(packageId, runConfigId, startOptions, procToken);
    if (res != kos::rtl::Ok)
    {
        std::cerr << fmt::format("[{}] Failed to start process. res=0x{:x}\n", selfName, res);
        return EXIT_FAILURE;
    }

    alm::execution_manager::ProcessContext procContext{};

    res = pc->GetProcessState(procToken, procContext);
    if (res != kos::rtl::Ok)
    {
        std::cerr << fmt::format("[{}] Failed to get process state. res=0x{:x}\n", selfName, res);
        return EXIT_FAILURE;
    }
    
    if (procContext.state == alm::execution_manager::ProcessState::Running)
    {
        std::cerr << fmt::format("[{}] Process state is Running.\n", selfName);
    }

    res = pc->StopProcess(procToken, alm::execution_manager::StopPolicy::Forced);
    if (res != kos::rtl::Ok)
    {
        std::cerr << fmt::format("[{}] Failed to stop process. res=0x{:x}\n", selfName, res);
        return EXIT_FAILURE;
    }

    // ...
}

Идентификатор статьи: em_iprocesscontrol, Последнее изменение: 27 янв. 2025 г.

В начало