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.

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