API определен в заголовочном файле sysroot-*-kos/include/alm/execution_manager/i_process_control.h из состава KasperskyOS SDK.
API позволяет:
Сведения о функциях 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
Функция |
Сведения о функции |
|---|---|
|
Назначение Запускает процесс. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Останавливает процесс. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Запрашивает сведения о процессе. Параметры
Возвращаемые значения В случае успеха возвращает |
Пример использования:
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;
}
// ...
}
В начало