IStateProvider interface

KasperskyOS Community Edition 1.3

Support Send link Get as PDF

KasperskyOS API > ExecutionManager component > IStateProvider interface

IStateProvider interface

This API is defined in the header file sysroot-*-kos/include/component/execution_manager/i_state_control.h from the KasperskyOS SDK.

The API lets you receive information about a process that was started by using the StartEntity() function from the IApplicationController API (see IApplicationController interface), including information about the reason for its termination.

Information about API functions is provided in the table below.

To get information about the process, call the GetApplicationState() function. The entityId input parameter is used by this function to receive the EntityId-type value that identifies the running process. Using the appState output parameter, this function returns information about a process in the AppContext structure. AppContext structure is defined in the header file sysroot-*-kos/include/component/execution_manager/types.h from the KasperskyOS SDK.

struct AppContext
{
    // State of the process.
    AppState                                     state{};
    // Reason for stopping a process.
    alm::execution_manager::ExecutableExitStatus exitStatus{};
    // Return code for a process
    // that stopped on its own.
    alm::execution_manager::ExecutableExitCode   exitCode{};
    // Return code that specifies the reason for
    // an unsuccessful attempt to start a process.
    alm::execution_manager::ExecutableExitReason exitReason{};
};

The state enumeration is a component of the AppContext structure and describes the state of a process. State enumeration is defined in the header file sysroot-*-kos/include/component/execution_manager/types.h from the KasperskyOS SDK.

enum class AppState : uint32_t
{
    None = 0,
    // Process started.
    Started,
    // Process restarted.
    Restarted,
    // Process was stopped by using the StopEntity() function
    // from the IApplicationController API.
    Stopped,
    // Process was stopped by using the ShutdownEntity() function
    // from the IApplicationController API.
    Completed,
    // Process stopped unexpectedly
    // as a result of an unhandled exception.
    Failed,
};

The exitStatus enumeration is a component of the AppContext structure and describes the reason for stopping a process. The ExecutableExitStatus enumeration is defined in the header file sysroot-*-kos/include/alm/execution_manager/execution_manager_types.h from the KasperskyOS SDK.

enum class [[nodiscard]] ExecutableExitStatus : std::underlying_type_t<TaskExitStatus>
{
    // Process has not yet been started by the ExecutionManager component.
    ExitUninitialized = TaskExitStatus::TaskExitUninitialized,
    // Process stopped unexpectedly as a result of an unhandled exception.
    ExitUnexpected    = TaskExitStatus::TaskExitUnexpected,
    // Process terminated on its own,
    // including after receiving a stop signal
    // via a call of the ShutdownEntity() function from the IApplicationController API.
    ExitNormal        = TaskExitStatus::TaskExitNormal,
    // Process stopped by external request, including via a call of 
    // the StopEntity() function from the IApplicationController API.
    ExitTerminated    = TaskExitStatus::TaskExitTerminated,
};

The numeric exitCode parameter is a component of the AppContext structure and contains the return code for a process that stopped on its own, including after receiving a stop signal. The values for this return code are defined by the developer of the KasperskyOS-based solution.

The numeric exitReason parameter is a component of the AppContext structure and contains the return code that specifies the reason for an unsuccessful attempt to start the process, or rcOk if the process started successfully. Parameter is defined in the header file sysroot-*-kos/include/rtl_cpp/retcode.h from the KasperskyOS SDK. This file contains return codes that are common for the APIs of all solution components and their constituent parts (see Return codes).

i_state_control functions

Function	Information about the function
`GetApplicationState()`	Purpose Requests information about a process. Parameters [in] `entityId` – value of the `EntityId` type that identifies the running process. [out] `appState` – link to the `AppContext` structure containing information about the process. Returned values If successful, the function returns `kos::Ok`, otherwise it returns an error code.

Function

Information about the function

GetApplicationState()

Purpose

Requests information about a process.

Parameters

[in] entityId – value of the EntityId type that identifies the running process.
[out] appState – link to the AppContext structure containing information about the process.

Returned values

If successful, the function returns kos::Ok, otherwise it returns an error code.

Usage example:

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

    // ...
}

Article ID: em_istateprovider, Last review: Feb 20, 2025

Page top