Интерфейс IStateProvider

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

Интерфейс IStateProvider

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

API позволяет получать сведения о процессе, запущенном с использованием функции StartEntity() из API IApplicationController (см. "Интерфейс IApplicationController"), включая информацию о причине его завершения.

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

Чтобы получить сведения о процессе, нужно вызвать функцию GetApplicationState(). Через входной параметр entityId эта функция принимает значение типа EntityId, которое идентифицирует запущенный процесс. Через выходной параметр appState эта функция возвращает сведения о процессе в виде структуры AppContext. Структура AppContext определена в заголовочном файле sysroot-*-kos/include/component/execution_manager/types.h из состава KasperskyOS SDK

struct AppContext
{
    // Состояние процесса.
    AppState                                     state{};
    // Причина остановки процесса.
    alm::execution_manager::ExecutableExitStatus exitStatus{};
    // Код возврата для процесса,
    // который остановился самостоятельно.
    alm::execution_manager::ExecutableExitCode   exitCode{};
    // Код возврата, который уточняет причину
    // неудачной попытки запуска процесса.
    alm::execution_manager::ExecutableExitReason exitReason{};
};

Перечисление state является компонентом структуры AppContext и описывает состояние процесса. Перечисление state определено в заголовочном файле sysroot-*-kos/include/component/execution_manager/types.h из состава KasperskyOS SDK.

enum class AppState : uint32_t
{
    None = 0,
    // Процесс запущен.
    Started,
    // Процесс перезапущен.
    Restarted,
    // Процесс остановлен с помощью функции StopEntity()
    // из API IApplicationController.
    Stopped,
    // Процесс остановлен с помощью функции ShutdownEntity()
    // из API IApplicationController.
    Completed,
    // Процесс аварийно остановлен
    // в результате необработанного исключения.
    Failed,
};

Перечисление exitStatus является компонентом структуры AppContext и описывает причину остановки процесса. Перечисление 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,
    // Процесс завершил работу самостоятельно,
    // в том числе после получения сигнала на остановку
    // при вызове функции ShutdownEntity() из API IApplicationController.
    ExitNormal        = TaskExitStatus::TaskExitNormal,
    // Процесс остановлен по внешнему запросу, в том числе вызовом 
    // функции StopEntity() из API IApplicationController.
    ExitTerminated    = TaskExitStatus::TaskExitTerminated,
};

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

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

Функции i_state_control

Функция	Сведения о функции
`GetApplicationState()`	Назначение Запрашивает сведения о процессе. Параметры [in] `entityId` – значение типа `EntityId`, которое идентифицирует запущенный процесс. [out] `appState` – ссылка на структуру `AppContext`, содержащую сведения о процессе. Возвращаемые значения В случае успеха возвращает `kos::Ok`, иначе возвращает код ошибки.

Функция

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

GetApplicationState()

Назначение

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

Параметры

[in] entityId – значение типа EntityId, которое идентифицирует запущенный процесс.
[out] appState – ссылка на структуру AppContext, содержащую сведения о процессе.

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

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

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

client.cpp

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

    execution_manager::AppContext appContext();

    if (rc = m_sc->GetApplicationState(entityId, appContext), rc != kos::Ok)
    {
        KOS_LOGERROR("GetApplicationState: failure with entity {}: {}", entityName, RC_GET_CODE(rc));
        return rc;
    }

    // ...
}

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

В начало