What's new

KasperskyOS Community Edition 1.3

Print Support Send link Get as PDF

PackageManager component
- IPackageController interface
- IPackageManifest interface

PackageManager component

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

The PackageManager component usage scenario is described in the article titled PackageManager component usage scenario.

The package_manager_proxy.h interface

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

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

struct PackageManagerConfig
{
    // Name of the IPC channel for connecting to the PackageManager process.
    std::string const mainConnection = KOS_PKGMGR_CONN_MAIN;
    // Name of the endpoint that implements the IPackageController interface.
    std::string const pkgControlInterface = KOS_PKGMGR_IFACE_PKGC;
    // PackageManager process class name.
    std::string const pkgMgrServerName = KOS_PKGMGR_SERVER_NAME;
};

package_manager_proxy.h functions

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

Function

Information about the function

CreatePackageManager()

Purpose

Gets the pointer to the instance of the IPackageManager interface that is required for working with the PackageManager component.

Parameters

[in] cfg, PackageManagerConfig structure containing the configuration settings for the connection to the PackageManager process.
[out] iPkgMgr – pointer to the instance of the IPackageManager interface.

Returned values

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

Usage example:

client.cpp

#include <component/package_manager/kos_ipc/package_manager_proxy.h>

namespace pkgmgr = package_manager;

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

    pkgmgr::IPackageManagerPtr iPkgMgr;
    std::string mainConnection{"PkgMgrEntity"};
    std::string pkgControlInterface{"kl.package_manager.PackageManager.ipkgc"};
    pkgmgr::ipc::PackageManagerConfig cfg{mainConnection, pkgControlInterface};

    if (CreatePackageManager(cfg, iPkgMgr) != kos::rtl::Ok)
        return EXIT_FAILURE;
    
    // ...
}

IPackageManager interface

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

The IPackageManager interface lets you receive the pointer to the IPackageController interface. This interface is intended for installing KPA packages to a KasperskyOS-based solution, and gets information about these packages.

i_package_manager.h functions

Function	Information about the function
`GetPackageController()`	Purpose Gets the pointer to an instance of the `IPackageController` interface. Parameters [out] `pkgController` – pointer to the instance of the `IPackageController` interface. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.

Function

Information about the function

GetPackageController()

Purpose

Gets the pointer to an instance of the IPackageController interface.

Parameters

[out] pkgController – pointer to the instance of the IPackageController interface.

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

    pkgmgr::IPackageControllerPtr pkgc;
    if (iPkgMgr->GetPackageController(pkgc) != kos::rtl::Ok)
        return EXIT_FAILURE;
    // ...
}

In this section

IPackageController interface

IPackageManifest interface

Page top

IPackageController interface

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

The API lets you do the following:

Install a KPA package in a KasperskyOS-based solution and remove the KPA package.
Receive information about an installed KPA package: unique ID, data from the KPA package manifest, and the KPA package status (installed or removed).

Information about API functions is provided in the table below.

Installing a KPA package

To install a KPA package, call the InstallPackage() function. Using the pkgInfo input parameter, this function receives data to verify the certificates of an installed KPA package in the InstallPackageInfo structure. All fields of this structure are optional.

struct InstallPackageInfo {
    // Full name of the KPA package external signature file.
    std::filesystem::path signaturePath = "";
    // Full name of the KPA package index file.
    std::filesystem::path indexPath = "";
    // Indicates whether to verify certificates of the installed KPA package.
    bool signatureVerify = false
};

If the signatureVerify parameter is set to true (verify certificates of the installed KPA package) but the file names are not specified, the following default values will be used during installation of the KPA package: <package_name>.kcat for the KPA package external signature file and <package_name>.kidx for the KPA package index file.

Deleting a KPA package

To remove a KPA package, call the UninstallPackage() function.

Getting information about installed KPA packages

To get the unique IDs of installed KPA packages, call the ListInstalledPackages() function. Using the pkgUIDs output parameter, the function returns a list of unique IDs of installed packages.

To get data on the KPA package manifest, call the GetManifest() function. Using the manifest output parameter, the function returns the pointer of the instance of the IPackageManifest interface that can be used to access the KPA package manifest key values. For more details, refer to IPackageManifest interface.

Notifications about the statuses of KPA packages in a KasperskyOS-based solution

The PackageManager component implements a mechanism for notifications about the statuses of KPA packages in a KasperskyOS-based solution, thereby enabling you to track changes to their statuses. To receive notifications, you must create a notification queue by using the CreateEventQueue() function.

To extract notifications from this queue, you must use the GetEvents() function. Using the pkgEvents output parameter, the function returns the status of KPA packages (since the moment when the queue was created) in the PackageEvent structure.

struct PackageEvent
{
    enum class Type
    {
        // KPA package was installed.
        INSTALL,
        // KPA package was removed.
        UNINSTALL,
        // Notification queue overflowed.
        OVERFLOWED,
    };
    // KPA package status.
    Type type;
    // Unique ID of the KPA package.
    std::string uid;
};

To delete the notification queue, call the DestroyEventQueue() function.

i_package_control.h functions

Function	Information about the function
`InstallPackage()`	Purpose Installs a KPA package. Parameters [in] `pkgName` – name of the KPA package to be installed. [out] `pkgUID` – unique ID of the installed KPA package. [in] `pkgInfo` – `InstallPackageInfo` structure that contains data for verifying certificates of an installed KPA package. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`UninstallPackage()`	Purpose Removes a KPA package. Parameters [in] `pkgUID` – unique ID of the KPA package to be removed. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`ListInstalledPackages()`	Purpose Gets the unique IDs of installed KPA packages. Parameters [out] `pkgUIDs` – array of unique IDs of installed KPA packages. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetManifest()`	Purpose Gets the pointer to the instance of the `IPackageManifest` interface required for receiving data on the KPA package manifest. Parameters [in] `pkgUID` – unique ID of the KPA package whose manifest data is required. [out] `manifest` – pointer to the instance of the `IPackageManifest` interface. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetItemDigest()`	Purpose Gets the checksum of the KPA package component file from the PackageManager component database. Parameters [in] `itemPath` – full name of the KPA package component file whose checksum is required. [out] `digest` – checksum of the KPA package component file. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetArtifactBlob()`	Purpose Gets the contents of a KPA package component. Parameters [in] `pkgUID` – unique ID of the KPA package containing the requested component. [in] `artifactType` – type of KPA package component. For more details, refer to List of "components" objects. [in] `artifactName` – name of the KPA package component. [out] `blob` – array of bytes representing the contents of the KPA package component. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`CreateEventQueue()`	Purpose Creates a queue for notifications about the statuses of KPA packages. Parameters [out] `queueHandle` – link to the handle of the notification queue. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`DestroyEventQueue()`	Purpose Deletes the queue for notifications about the statuses of KPA packages. Parameters [in] `queueHandle` – handle of the notification queue. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetEvents()`	Purpose Gets the statuses of KPA packages from the notification queue. Parameters [in] `queueHandle` – handle of the notification queue. [out] `pkgEvents` – `PackageEvent` structure containing the statuses of KPA packages. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.

Usage example:

client.cpp

#include <component/package_manager/kos_ipc/package_manager_proxy.h>

namespace pkgmgr = package_manager;

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

    // Create a queue for notifications about the statuses of KPA packages.
    Handle eventQueue;
    if (pkgc->CreateEventQueue(eventQueue) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Install the KPA package named test1.
    std::string uid1;
    const std::string pkgName1{"test1"};
    const package_manager::InstallPackageInfo pkgInfo1{"", "", true};

    if (pkgc->InstallPackage(pkgName1, uid1, pkgInfo1) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Install the KPA package named test2.
    std::string uid2;
    const std::string pkgName2{"test2"};
    const package_manager::InstallPackageInfo pkgInfo2{"/test2.kcat", "/test2.kidx", true};
    if (pkgc->InstallPackage(pkgName2, uid2, pkgInfo2) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Get the pointer to the instance of the IPackageManifest interface
    // for the KPA package named test1.
    pkgmgr::IPackageManifestPtr manifest;
    if (pkgc->GetManifest(uid1, manifest) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Get the unique IDs of installed KPA packages.
    std::vector<std::string> pkgUIDs
    if (pkgc->ListInstalledPackages(pkgUIDs) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Remove the KPA package named test1.
    if (pkgc->UninstallPackage(uid1) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Remove the KPA package named test2.
    if (pkgc->UninstallPackage(uid2) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Get the statuses of KPA packages from the notification queue.
    std::vector<package_manager::PackageEvent> pkgEvents;
    if (pkgc->GetEvents(eventQueue, pkgEvents) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Delete the notification queue.
    if (pkgc->DestroyEventQueue(eventQueue) != kos::rtl::Ok)
        return EXIT_FAILURE;

    if (KnHandleClose(eventQueue) != rcOk)
        return EXIT_FAILURE;

    // ...
}

Page top

IPackageManifest interface

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

The API lets you get the KPA package manifest key values. For more details about the available keys of the KPA package manifest, see "KPA package manifest"

Information about API functions is provided in the table below.

Getting program ID

To get the ID of a program that was installed from a KPA package, call the GetPackageID() function.

Getting information about KPA package components

To get information about KPA package components, call the GetApplicationsInfo() function. Using the applications output parameter, the function returns information about KPA package components as a vector of ApplicationInfo structures.

struct ApplicationInfo
{
    // Name of the KPA package component.
    std::string name;
    // Path of the directory relative to the path /<package name>/res
    // in which the KPA package component is installed.
    std::string path;
    // Unused parameter.
    std::string iconPath;
    // Unused parameter.
    std::string containerPath;
    // Unused parameter.
    std::string etcPath;
    // Checksum of the KPA package component file.
    std::string digest;
    // Object in JSON format.
    ManifestType extensions;
    // Type of KPA package component.
    std::string type;
};

An extensions structure element describes an object in JSON format. ManifestType is an alias of the nlohmann:json type.

Getting program startup configurations

To get information about the startup configurations of a program installed from a KPA package, call the GetRunConfigurationsInfo() function. Using the runConfigurations output parameter, the function returns information about program startup configurations as a vector of RunConfigurationInfo structures.

struct RunConfigurationInfo
{
    // Startup configuration ID that is unique within the specific KPA package.
    std::string id;
    // Startup configuration name.
    std::string name;
    // Program security class.
    std::string eiid
    // Path to the KPA package component file.
    std::string path;
    // List of arguments in the form of a string array.
    std::vector<std::string> args{}
    // List of environment variables.
    std::vector<std::string> envs{}
    // Indicates whether the startup configuration is the primary one during program startup:
    // true means that it is primary, and false means that it is not primary.
    bool primary{false};
    // Indicates whether this configuration is started automatically:
    // true means that it is started automatically, and false means that it is not.
    bool autorun{false};
};

Receiving information about a program

To get information about a program installed from a KPA package, call the GetPackageInfo() function. Using the packageInfo output parameter, the function returns information about startup configurations in the PackageInfo structure.

struct PackageInfo
{
    // Unique ID of the program.
    std::string id;
    // Program name.
    std::string name;
    // Program version.
    std::string version;
    // Unused parameter.
    std::string title;
    // Unused parameter.
    std::string summary;
    // Program description.
    std::string description;
    // Program build number.
    std::string buildNumber;
    // Logical value indicating whether the program is a system program:
    // true means that it is, while false means that it is not.
    bool systemApplication;
    // Object of an arbitrary format.
    ManifestType extensions;
};

Getting information about the isolated storage of a program

To get information about the isolated storage of a program, call the GetPrivateStorageInfo() function. Using the packageInfo output parameter, the function returns information about startup configurations in the PrivateStorage structure.

struct PrivateStorage
{
    // Program data storage size in MB.
    size_t size;
    // Program data storage file system type.
    std::string fsType;
};

Getting information about objects of an arbitrary format

To get information about objects of an arbitrary format that were added by the KPA package developer (the extensions key from the KPA package manifest), call the Get() function.

i_package_manifest.h functions

Function	Information about the function
`GetPackageID()`	Purpose Gets the unique ID of a program installed from a KPA package. Parameters [out] `id` – unique ID of the program. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetApplicationsInfo()`	Purpose Gets information about KPA package components. Parameters [out] `applications` – vector of `ApplicationInfo` structures containing information about KPA package components. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetRunConfigurationsInfo()`	Purpose Gets information about the startup configurations of a program installed from a KPA package. Parameters [out] `runConfigurations` – vector of `RunConfigurationInfo` structures containing information about startup configurations. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetPackageInfo()`	Purpose Gets information about a program installed from a KPA package. Parameters [out] `packageInfo` – `PackageInfo` structure containing information about the program. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`GetPrivateStorageInfo()`	Purpose Gets information about the isolated storage of a program. Parameters [out] `packageInfo` – `PrivateStorage` structure containing information about the isolated storage of a program. Returned values If successful, the function returns `kos::rtl::Ok`, otherwise it returns an error code.
`Get()`	Purpose Gets information about objects of an arbitrary format that were added to the manifest by the KPA package developer. Parameters N/A Returned values Returns the pointer of an object with the type `pkgmgr::IPackageManifest::ManifestType`.

Usage example:

client.cpp

#include <component/package_manager/kos_ipc/package_manager_proxy.h>

namespace pkgmgr = package_manager;

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

    // Get the pointer to the instance of the IPackageManifest interface
    // for the KPA package containing the unique ID uid1.
    pkgmgr::IPackageManifestPtr manifest;
    if (pkgc->GetManifest(uid1, manifest) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Get unique ID of the program.
    std::string packageID;
    if (manifest->GetPackageID(packageID) != kos::rtl::Ok)
        return EXIT_FAILURE;

    std::cout << packageID << '\n';

    // Get information about KPA package components.
    std::vector<package_manager::IPackageManifest::ApplicationInfo> infos;
    manifest->GetApplicationsInfo(infos);

    for (auto &info: infos)
    {
        std::cout << info.name << " " << info.path << "\n";
    }

    // Get information about objects of an arbitrary format.
    pkgmgr::IPackageManifest::ManifestType jsonManifest = manifest->Get();

    std::cout << jsonManifest["package"]["description"] << '\n';

    // Get information about the startup configurations of a program installed from a KPA package.
    std::vector<package_manager::IPackageManifest::RunConfigurationInfo> runConfigurationInfos;
    manifest->GetRunConfigurationsInfo(runConfigurationInfos);

    for (auto &runConfigurationInfo : runConfigurationInfos)
    {
        std::cout << "RunConfiguration.id = " << runConfigurationInfo.id << ", autorun = " << runConfigurationInfo.autorun << "\n";
    }
   
    // ...
}

Page top

Contents

PackageManager component

IPackageController interface

IPackageManifest interface