IApplicationController interface

KasperskyOS Community Edition 1.3

Support Send link Get as PDF

KasperskyOS API > ExecutionManager component > IApplicationController interface

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

   // ...
}

Article ID: em_iapplicationcontroller, Last review: Feb 20, 2025

Page top