KasperskyOS Community Edition 1.3
English
KasperskyOS API  >  ExecutionManager component  >  IProcessControl interface

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.

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; } // ... }
Article ID: em_iprocesscontrol, Last review: Feb 20, 2025
Page top