What's new

KasperskyOS Community Edition 1.3

Print Support Send link Get as PDF

ExecutionManager component

ExecutionManager component

The API is defined in the header files located in the directory sysroot-*-kos/include/component/execution_manager/ from the KasperskyOS SDK.

The ExecutionManager component usage scenario is described in the article titled Starting a processes using the ExecutionManager system program.

execution_manager_proxy.h interface

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

The interface contains the CreateExecutionManager() function for getting the pointer to the instance of the IExecutionManager interface that is required for working with the ExecutionManager component. Using the cfg input parameter, this function accepts configuration parameters in the ExecutionManagerConfig structure. All fields of this structure are optional.

struct ExecutionManagerConfig
{
    // Name of the IPC channel for connecting to the ExecutionManager process.
    char const* const mainConnection            = KOS_EXECMGR_CONN_MAIN;
    // Name of the endpoint that implements the IApplicationController interface.
    char const* const appControlInterface       = KOS_EXECMGR_IFACE_AC;
    // Name of the endpoint that implements the IStateProvider interface.
    char const* const appStateInterface         = KOS_EXECMGR_IFACE_AS;
    // Name of the endpoint that implements the ISystemController interface.
    char const* const systemControlInterface    = KOS_EXECMGR_IFACE_SC;
    // Name of the endpoint that implements the IProcessControl interface.
    char const* const processControlInterface   = KOS_EXECMGR_IFACE_PC;
    // ExecutionManager process class name.
    char const* const execmgrServerName         = KOS_EXECMGR_SERVER_NAME;
};

execution_manager_proxy.h functions

Function	Information about the function
`CreateExecutionManager()`	Purpose Gets the pointer to the instance of the `IExecutionManager` interface that is required for working with the ExecutionManager component. Parameters [in] `cfg` – `ExecutionManagerConfig` structure containing the configuration settings for the connection to the `ExecutionManager` process. [out] `emp` – pointer to the instance of the `IExecutionManager` interface. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.

Function

Information about the function

CreateExecutionManager()

Purpose

Gets the pointer to the instance of the IExecutionManager interface that is required for working with the ExecutionManager component.

Parameters

[in] cfg – ExecutionManagerConfig structure containing the configuration settings for the connection to the ExecutionManager process.
[out] emp – pointer to the instance of the IExecutionManager interface.

Returned values

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

Usage example:

client.cpp

#include <component/execution_manager/kos_ipc/execution_manager_proxy.h>

int main(int argc, const char *argv[])
{
    // ...
    execution_manager::ipc::ExecutionManagerConfig emCfg
    {
        // Name of the IPC channel for connecting to the ExecutionManager process.
        // It must match the MAIN_CONN_NAME value in the
        // CMakeLists.txt file for building the ExecutionManager component.
        .mainConnection             = "ExecMgrEntity",
// ExecutionManager process class name.
        .execmgrServerName          = "kl.ExecMgrEntity"
    };
    execution_manager::IExecutionManagerPtr emPtr;

    kos::Result res = CreateExecutionManager(emCfg, emPtr);
    if (res != kos::Ok)
    {
        std::cerr << fmt::format("[{}] Failed to create execution manager. res=0x{:x}\n", selfName, res);
        return EXIT_FAILURE;
    }
    // ...
}

IExecutionManager interface

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

The IExecutionManager interface lets you access pointers to the following interfaces:

IProcessControl – interface that lets you start a process from an executable file installed by the PackageManager component from the KPA package in a KasperskyOS-based solution, and lets you receive information about the process (including information about its completion) and stop this process.
IApplicationController – interface that lets you start a process from any executable file whose location in the file system is known, and lets you stop this process.
IStateProvider – interface for receiving information about a process that was started using the IApplicationController interface.
ISystemController – interface for managing the system.

Usage example:

client.cpp

int main(int argc, const char *argv[])
{
    // ...
    alm::execution_manager::IProcessControlPtr pc;
    res = emPtr->GetProcessController(pc);
    if (res != kos::Ok)
    {
        std::cerr << fmt::format("[{}] Failed to create process controller. res=0x{:x}\n", selfName, res);
        return EXIT_FAILURE;
    }

    execmgr::IApplicationControllerPtr ac;
    if (ptr->GetApplicationController(ac) != kos::Ok)
    {
        std::cerr << "Cannot get application controller" << std::endl;
        return EXIT_FAILURE;
    }

    execmgr::ISystemControllerPtr sc;
    if (ptr->GetSystemController(sc) != kos::Ok)
    {
        std::cerr << "Cannot get system controller" << std::endl;
        return EXIT_FAILURE;
    }

    // ...
}

In this section

IProcessControl interface

IApplicationController interface

IStateProvider interface

ISystemController interface

Page top

IProcessControl interface

The API is defined in the header file sysroot-*-kos/include/alm/execution_manager/i_process_control.h from the KasperskyOS SDK.

The API lets you do the following:

Start a process from an executable file installed by the PackageManager component from the KPA package in a KasperskyOS-based solution.
Get information about process, including information about its termination.
Stop a process.

Information about API functions is provided in the table below.

Starting a process

To start the process, call the StartProcess() function. Using the opts input parameter, this function accepts process startup parameters in the StartOptions structure. All fields of this structure are optional for initialization.

struct StartOptions
{
    // Handle that identifies the parent process.
    IpcHandle       parent{NK_INVALID_HANDLE, 0, NK_INVALID_HANDLE};
    // List of custom handles
    // that will be transferred to the process when it is started.
    UserHandleItems userHandles;
    // Command-line arguments.
    Strings         extraArgs;
    // Environment variables.
    Strings         extraEnvs;};

During initialization of the StartOptions structure, the parent handle transport container is populated with the default values, which indicate the absence of a parent process. You can create a process hierarchy by passing the handle of a parent process in this parameter to a started child process.

The userHandles vector is a component of the StartOptions structure and contains a list of custom handles that will be transferred to the process when it is started. Items of this list are pairs that are defined in the UserHandleItem structure. These pairs consist of a handle and its name. After a process is started, the handles transferred to this process can be found by using the KosTaskLookupResource() function based on the names of these handles.

struct UserHandleItem
{
    // Handle name.
    std::string id;
    // Handle.
    IpcHandle   handle;
};

The input parameters pkgId and runConfigId of the StartProcess() function are defined in the KPA package manifest. Their values may be received by using functions from the IPackageManifest interface of the PackageManager component.

Stopping a process

To stop the process, call the StopProcess() function. Using the stopPolicy input parameter, this function receives the process stop policy from the StopPolicy enumeration.

enum class StopPolicy : uint32_t
{
    // Send a stop signal to the process.
    Normal = 0,
    // Immediately stop the process.
    Forced,
};

Receiving information about a process

To request information about a process, call the GetProcessState() function. Using the state output parameter, this function returns information about a process in the ProcessContext structure.

struct ProcessContext
{
    // State of the process.
    ProcessState         state{};
    // System status of process termination.
    ExecutableExitStatus exitStatus{};
    // Common code for process termination.
    ExecutableExitCode   exitCode{};
    // Specific code for process termination.
    ExecutableExitReason exitReason{};
};

The state enumeration is a component of the ProcessContext structure and describes the state of a process.

enum class ProcessState : uint32_t
{
    // Service constant.
    None = 0,
    // Process created.
    Created,
    // Process initialized.
    Prepared,
    // Process started.
    Running,
    // Process stopped unexpectedly.
    Failed,
    // Process stopped, but data on the process is available
    // to the GetProcessState() function.
    Finished,
    // Process terminated and does not exist in the system.
    NotExisting,
};

The exitStatus enumeration is a component of the ProcessContext 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 StopProcess() function with the Normal value in the process stop policy.
    ExitNormal        = TaskExitStatus::TaskExitNormal,
    // Process stopped by external request, including via a call of the
    // StopProcess() function with the Forced value in the process stop policy.
    ExitTerminated    = TaskExitStatus::TaskExitTerminated,
};

The numeric exitCode parameter is a component of the ProcessContext 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 ProcessContext structure and contains the return code that specifies the reason for an unsuccessful attempt to start the process, or rcOk if the startup was successful. 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_process_control.h functions

Function	Information about the function
`StartProcess()`	Purpose Starts a process. Parameters [in] `pkgId` – ID of the KPA package. [in] `runConfigId` – ID of the startup configuration. [in] `opts` – `StartOptions` structure containing the process startup parameters. [out] `accessToken` – link to the handle that identifies the started process. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`StopProcess()`	Purpose Stops a process. Parameters [in] `accessToken` – handle that identifies the started process. [in] `stopPolicy` – process stop policy. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetProcessState()`	Purpose Requests information about a process. Parameters [in] `accessToken` – handle that identifies the started process. [out] `state` – link to the `ProcessContext` structure containing information about the process. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.

Function

Information about the function

StartProcess()

Purpose

Starts a process.

Parameters

[in] pkgId – ID of the KPA package.
[in] runConfigId – ID of the startup configuration.
[in] opts – StartOptions structure containing the process startup parameters.
[out] accessToken – link to the handle that identifies the started process.

Returned values

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

StopProcess()

Purpose

Stops a process.

Parameters

[in] accessToken – handle that identifies the started process.
[in] stopPolicy – process stop policy.

Returned values

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

GetProcessState()

Purpose

Requests information about a process.

Parameters

[in] accessToken – handle that identifies the started process.
[out] state – link to the ProcessContext structure containing information about the process.

Returned values

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

Usage example:

client.cpp

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

    alm::execution_manager::IProcessControl::StartOptions startOptions{};
    alm::execution_manager::IpcHandle procToken{};
    
    // ID of the KPA package.
    const std::string   packageId{"application.Application"};
    // Startup configuration ID.
    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;
    }

    // ...
}

Page top

IApplicationController interface

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

The API lets you start a process from an executable file and stop this process.

Information about API functions is provided in the table below.

To start the process, call the StartEntity() function. Using the info input parameter, this function accepts process startup parameters in the StartEntityInfo structure. All fields of this structure are optional for initialization. Using the resInfo output parameter, this function returns the link to the StartEntityResultInfo structure containing the process startup results.

To stop a process, call the ShutdownEntity() or StopEntity() function. The entId input parameter is used by these functions to receive the handle that identifies the started process.

struct IApplicationController
{
    struct StartEntityInfo
    {
        // Process name.Unless otherwise specified, the process class name will be used.
        // If the process class name is not specified, the executable file name will be used.
        std::string              entityName;
        // Process class. Unless otherwise specified, the process name will be used.
        // If the process name is not specified, the executable file name will be used.
        std::string              eiid
        // Command-line arguments.
        std::vector<std::string> args
        // Environment variables.
        std::vector<std::string> envs;
        // Policy for restarting a process when it crashes. Available values:
        // EntityRestartPolicy::DoNotRestart – do not restart.
        // EntityRestartPolicy::AlwaysRestart – always restart.
        EntityRestartPolicy      restartPolicy { EntityRestartPolicy::DoNotRestart };
    };

    struct StartEntityResultInfo
    {
        // Security class assigned to the process.
        std::string eiid;
        // Handle that identifies the started process.
        EntityId    entId;
        // Security ID of the started process.
        Uid         sid;
        // Name of the started process.
        std::string taskName;
    };
};

i_application_control.h functions

Function	Information about the function
`StartEntity()`	Purpose Starts a process. Parameters [in] `runPath` – path to the executable file to be started. [in] `info` – structure containing the `StartEntityInfo` process startup parameters. [out] `resInfo` – structure containing the `StartEntityResultInfo` process startup results. [out] `containerPath` – path to the isolated data storage of a process. Returned values If successful, the function returns `kos::Ok`, otherwise it returns an error code.
`ShutdownEntity()`	Purpose Sends a termination signal to a process. Parameters [in] `entId` – handle that identifies the running process. Returned values If successful, the function returns `kos::Ok`, otherwise it returns an error code.
`StopEntity()`	Purpose Immediately stops the execution of a process. Parameters [in] `entId` – handle that identifies the running process. Returned values If successful, the function returns `kos::Ok`, otherwise it returns an error code.

Function

Information about the function

StartEntity()

Purpose

Starts a process.

Parameters

[in] runPath – path to the executable file to be started.
[in] info – structure containing the StartEntityInfo process startup parameters.
[out] resInfo – structure containing the StartEntityResultInfo process startup results.
[out] containerPath – path to the isolated data storage of a process.

Returned values

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

ShutdownEntity()

Purpose

Sends a termination signal to a process.

Parameters

[in] entId – handle that identifies the running process.

Returned values

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

StopEntity()

Purpose

Immediately stops the execution of a process.

Parameters

[in] entId – handle that identifies the running 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[])
{
    // ...
    const fs::path appPath{"/application"};

    execmgr::IApplicationController::StartEntityResultInfo result;
    execmgr::IApplicationController::StartEntityInfo info;

    info.entityName = std::string{"application.Application"};
    info.eiid = std::string{"application.Application"};
    info.args = std::vector<std::string>{"1", "ARG1", "ARG2" , "ARG3"};
    info.envs = std::vector<std::string>{"ENV1=10", "ENV2=envStr"};

    std::cout << "Starting application from elf\n";

    if (ac->StartEntity(appPath, info, result) != kos::Ok)
    {
        std::cerr << "Cannot start application from " << appPath << std::endl;
        return EXIT_FAILURE;
    }

    std::cout << "Application started with process sid " << result.sid << "\n";

    auto AppId = result.entId;

    if (ac->StopEntity(AppId) != kos::Ok)
    {
        std::cerr << "Cannot stop process " << appPath << std::endl;
        return EXIT_FAILURE;
    }

   // ...
}

Page top

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

    // ...
}

Page top

ISystemController interface

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

The API lets you terminate the system.

Information about API functions is provided in the table below.

i_system_control.h functions

Function	Information about the function
`StopAllEntities()`	Purpose Stops all running processes, then terminates the ExecutionManager process, then sends a device shutdown request to the kernel. Parameters N/A Returned values If successful, the function returns `kos::Ok`, otherwise it returns an error code.

Function

Information about the function

StopAllEntities()

Purpose

Stops all running processes, then terminates the ExecutionManager process, then sends a device shutdown request to the kernel.

Parameters

N/A

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[])
{
 // ...

 if (sc->StopAllEntities() != kos::Ok)
 {
 std::cerr << "Cannot stop all processes\n";
 return EXIT_FAILURE;
 }
    
 // ...
}

Page top

Contents

ExecutionManager component

IProcessControl interface

IApplicationController interface

IStateProvider interface

ISystemController interface