IPackageController interface

KasperskyOS Community Edition 1.3

Support Send link Get as PDF

KasperskyOS API > PackageManager component > IPackageController interface

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;

    // ...
}

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

Page top