ExecutionManager component
The API is defined in the header files located in the directory sysroot-*-kos/include/component/execution_manager/ from the SDK.
The ExecutionManager component usage scenario is described in the article titled "Starting a process using the KasperskyOS API".
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
The interface contains the factory method CreateExecutionManager() for getting the pointer to the instance of the IExecutionManager interface that is required for working with the ExecutionManager component.
Usage example:
client.cpp
#include <component/execution_manager/kos_ipc/execution_manager_proxy.h>
...
namespace execmgr = execution_manager;
int main(int argc, const char *argv[])
{
// ...
execmgr::IExecutionManagerPtr ptr;
// 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 ExecutionManager.
char mainConnection[] = "ExecMgrEntity";
execmgr::ipc::ExecutionManagerConfig cfg{mainConnection};
if (CreateExecutionManager(cfg, ptr) != eka::sOk)
{
std::cerr << "Cannot create execution manager" << std::endl;
return EXIT_FAILURE;
}
// ...
}
IExecutionManager interface
The API is defined in the header file sysroot-*-kos/include/component/execution_manager/i_execution_manager.h
The IExecutionManager interface lets you access pointers to the following interfaces:
IApplicationController– interface for starting and stopping processes.ISystemController– interface for managing the system.
Usage example:
client.cpp
int main(int argc, const char *argv[])
{
// ...
execmgr::IApplicationControllerPtr ac;
if (ptr->GetApplicationController(ac) != eka::sOk)
{
std::cerr << "Cannot get application controller" << std::endl;
return EXIT_FAILURE;
}
execmgr::ISystemControllerPtr sc;
if (ptr->GetSystemController(sc) != eka::sOk)
{
std::cerr << "Cannot get system controller" << std::endl;
return EXIT_FAILURE;
}
// ...
}
IApplicationController interface
The API is defined in the header file sysroot-*-kos/include/component/execution_manager/i_application_control.h
The IApplicationController interface provides the following methods that let you change the state of a process:
StartEntity(const std::filesystem::path& runPath,const StartEntityInfo& info,StartEntityResultInfo& resInfo) – method for starting a process.RestartEntity(EntityId endId)– method for restarting a previously started process.ShutdownEntity(EntityId entId)– method for sending a termination signal to a process.StopEntity(EntityId entId)– method for immediately stopping execution of a process.
The StartEntity() method receives the path to the executable file that should be run and the structure containing the run parameters for the StartEntityInfo process, and returns the structure containing the StartEntityResultInfo process run results. All fields of the StartEntityInfo structure are optional for initialization.
All other methods receive the EntityId structure that identifies the started process.
struct IApplicationController
{
// All fields of the StartEntityInfo structure are optional for initialization.
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;
std::vector<std::string> args; // Command-line arguments.
std::vector<std::string> envs; // Environment variables.
// 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
{
std::string eiid; // Security class assigned to the process.
EntityId entId; // Structure that identifies the started process.
Uid sid; // Security ID of the started process.
std::string taskName; // Name of the started process.
};
};
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) != eka::sOk)
{
std::cerr << "Can not 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) != eka::sOk)
{
std::cerr << "Cannot stop process " << appPath << std::endl;
return EXIT_FAILURE;
}
// ...
}
ISystemController interface
The API is defined in the header file sysroot-*-kos/include/component/execution_manager/i_system_control.h
The ISystemController interface provides the following method for system management:
StopAllEntities()method stops all running processes, then terminates the ExecutionManager process, then sends a device shutdown request to the kernel.
Usage example:
client.cpp
int main(int argc, const char *argv[])
{
// ...
if (sc->StopAllEntities() != eka::sOk)
{
std::cerr << "Cannot stop all processes\n";
return EXIT_FAILURE;
}
// ...
}
