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 |
|---|---|
|
Purpose Requests information about a process. Parameters
Returned values If successful, the function returns |
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;
}
// ...
}
Page top