Содержание

Компонент PackageManager
- Интерфейс IPackageController
- Интерфейс IPackageManifest

Компонент PackageManager

API определен в заголовочных файлах, расположенных в директории sysroot-*-kos/include/component/package_manager/ из состава KasperskyOS SDK.

Сценарий использования компонента PackageManager описан в статье "Сценарий использования компонента PackageManager".

Интерфейс package_manager_proxy.h

API определен в заголовочном файле sysroot-*-kos/include/component/package_manager/kos_ipc/package_manager_proxy.h из состава KasperskyOS SDK.

Интерфейс содержит функцию CreatePackageManager() для получения указателя на экземпляр интерфейса IPackageManager, необходимого для работы с компонентом PackageManager. Через входной параметр cfg эта функция принимает параметры конфигурации в виде структуры PackageManagerConfig. Все поля этой структуры опциональны для заполнения.

struct PackageManagerConfig
{
    // Имя IPC-канала для соединения с процессом PackageManager.
    std::string const mainConnection = KOS_PKGMGR_CONN_MAIN;
    // Имя службы, реализующей интерфейс IPackageController.
    std::string const pkgControlInterface = KOS_PKGMGR_IFACE_PKGC;
    // Имя класса процесса PackageManager.
    std::string const pkgMgrServerName = KOS_PKGMGR_SERVER_NAME;
};

Функции package_manager_proxy.h

Функция	Сведения о функции
`CreatePackageManager()`	Назначение Получение указателя на экземпляр интерфейса `IPackageManager`, необходимого для работы с компонентом PackageManager. Параметры [in] `cfg` – структура `PackageManagerConfig` с параметрами конфигурации для соединения с процессом `PackageManager`. [out] `iPkgMgr` – указатель на экземпляр интерфейса `IPackageManager`. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.

Функция

Сведения о функции

CreatePackageManager()

Назначение

Получение указателя на экземпляр интерфейса IPackageManager, необходимого для работы с компонентом PackageManager.

Параметры

[in] cfg – структура PackageManagerConfig с параметрами конфигурации для соединения с процессом PackageManager.
[out] iPkgMgr – указатель на экземпляр интерфейса IPackageManager.

Возвращаемые значения

В случае успеха возвращает kos::rtl::Ok, иначе возвращает код ошибки.

Пример использования:

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

API определен в заголовочном файле sysroot-*-kos/include/component/package_manager/i_package_manager.h из состава KasperskyOS SDK.

Интерфейс IPackageManager позволяет получить указатель на интерфейс IPackageController. Этот интерфейс предназначен для установки KPA-пакетов в решение на базе KasperskyOS, а также получения сведений о них.

Функции i_package_manager.h

Функция	Сведения о функции
`GetPackageController()`	Назначение Получение указателя на экземпляр интерфейса `IPackageController`. Параметры [out] `pkgController` – указатель на экземпляр интерфейса `IPackageController`. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.

Функция

Сведения о функции

GetPackageController()

Назначение

Получение указателя на экземпляр интерфейса IPackageController.

Параметры

[out] pkgController – указатель на экземпляр интерфейса IPackageController.

Возвращаемые значения

В случае успеха возвращает kos::rtl::Ok, иначе возвращает код ошибки.

Пример использования:

client.cpp

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

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

В этом разделе

Интерфейс IPackageController

Интерфейс IPackageManifest

В начало

Интерфейс IPackageController

API определен в заголовочном файле sysroot-*-kos/include/component/package_manager/i_package_control.h из состава KasperskyOS SDK.

API позволяет:

устанавливать KPA-пакет в решение на базе KasperskyOS и удалять KPA-пакет;
получать сведения об установленном KPA-пакете: уникальный идентификатор, данные из манифеста KPA-пакета, статус KPA-пакета (установлен или удален).

Сведения о функциях API приведены в таблице ниже.

Установка KPA-пакета

Чтобы установить KPA-пакет, нужно вызвать функцию InstallPackage(). Через входной параметр pkgInfo эта функция принимает данные для проверки сертификатов устанавливаемого KPA-пакета в виде структуры InstallPackageInfo. Все поля этой структуры являются опциональными для заполнения.

struct InstallPackageInfo {
    // Полное имя файла внешней подписи KPA-пакета.
    std::filesystem::path signaturePath = "";
    // Полное имя файла индексного файла KPA-пакета.
    std::filesystem::path indexPath = "";
    // Проверять ли сертификаты устанавливаемого KPA-пакета.
    bool signatureVerify = false;
};

Если параметр signatureVerify установлен в значение true (проверять сертификаты устанавливаемого KPA-пакета), а имена файлов не указаны, то при установке KPA-пакета будут использованы значения по умолчанию: <имя_пакета>.kcat для файла внешней подписи KPA-пакета и <имя_пакета>.kidx для индексного файла KPA-пакета.

Удаление KPA-пакета

Чтобы удалить KPA-пакет, нужно вызвать функцию UninstallPackage().

Получение сведений об установленных KPA-пакетах

Чтобы получить уникальные идентификаторы установленных KPA-пакетов, нужно вызвать функцию ListInstalledPackages(). Через выходной параметр pkgUIDs функция возвращает список уникальных идентификаторов установленных пакетов.

Чтобы получить данные о манифесте KPA-пакета, нужно вызвать функцию GetManifest(). Через выходной параметр manifest функция возвращает указатель на экземпляр интерфейса IPackageManifest, используя который можно получить доступ к значениям ключей манифеста KPA-пакета. Подробнее см. "Интерфейс IPackageManifest".

Уведомления о статусах KPA-пакетов в решении на базе KasperskyOS

Компонент PackageManager реализует механизм уведомлений о статусах KPA-пакетов в решении на базе KasperskyOS, позволяя отслеживать изменения в их состоянии. Для получения уведомлений нужно создать очередь уведомлений используя функцию CreateEventQueue().

Чтобы извлекать уведомления из этой очереди, нужно использовать функцию GetEvents(). Через выходной параметр pkgEvents функция возвращает статус KPA-пакетов (с момента создания очереди) в виде структуры PackageEvent.

struct PackageEvent
{
    enum class Type
    {
        // KPA-пакет установлен.
        INSTALL,
        // KPA-пакет удален.
        UNINSTALL,
        // Очередь уведомлений переполнена.
        OVERFLOWED,
    };
    // Статус KPA-пакета.
    Type type;
    // Уникальный идентификатор KPA-пакета.
    std::string uid;
};

Чтобы удалить очередь уведомлений, нужно вызвать функцию DestroyEventQueue().

Функции i_package_control.h

Функция	Сведения о функции
`InstallPackage()`	Назначение Устанавливает KPA-пакет. Параметры [in] `pkgName` – имя KPA-пакета, который требуется установить. [out] `pkgUID` – уникальный идентификатор установленного KPA-пакета. [in] `pkgInfo` – структура `InstallPackageInfo`, которая содержит данные для проверки сертификатов устанавливаемого KPA-пакета. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`UninstallPackage()`	Назначение Удаляет KPA-пакет. Параметры [in] `pkgUID` – уникальный идентификатор KPA-пакета, который требуется удалить. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`ListInstalledPackages()`	Назначение Получает уникальные идентификаторы установленных KPA-пакетов. Параметры [out] `pkgUIDs` – массив уникальных идентификаторов установленных KPA-пакетов. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetManifest()`	Назначение Получает указатель на экземпляр интерфейса `IPackageManifest`, необходимого для получения данных о манифесте KPA-пакета. Параметры [in] `pkgUID` – уникальный идентификатор KPA-пакета, о манифесте которого требуется получить данные. [out] `manifest` – указатель на экземпляр интерфейса `IPackageManifest`. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetItemDigest()`	Назначение Получает хеш-сумму файла компонента KPA-пакета из базы данных компонента PackageManager. Параметры [in] `itemPath` – полное имя файла компонента KPA-пакета, хеш-сумму которого требуется получить. [out] `digest` – хеш-сумма файла компонента KPA-пакета. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetArtifactBlob()`	Назначение Получает содержимое компонента KPA-пакета. Параметры [in] `pkgUID` – уникальный идентификатор KPA-пакета, частью которого является запрашиваемый компонент. [in] `artifactType` – тип компонента KPA-пакета. Подробнее см. "Список объектов components" [in] `artifactName` – имя компонента KPA-пакета. [out] `blob` – массив байтов, представляющий содержимое компонента KPA-пакета. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`CreateEventQueue()`	Назначение Создает очередь уведомлений о статусах KPA-пакетов. Параметры [out] `queueHandle` – ссылка на дескриптор очереди уведомлений. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`DestroyEventQueue()`	Назначение Удаляет очередь уведомлений о статусах KPA-пакетов. Параметры [in] `queueHandle` – дескриптор очереди уведомлений. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetEvents()`	Назначение Получает из очереди уведомлений статусы KPA-пакетов. Параметры [in] `queueHandle` – дескриптор очереди уведомлений. [out] `pkgEvents` – структура `PackageEvent` со статусами KPA-пакетов. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.

Пример использования:

client.cpp

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

namespace pkgmgr = package_manager;

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

    // Создать очередь уведомлений о статусах KPA-пакетов.
    Handle eventQueue;
    if (pkgc->CreateEventQueue(eventQueue) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Установить KPA-пакет с именем 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;

    // Установить KPA-пакет с именем 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;

    // Получить указатель на экземпляр интерфейса IPackageManifest
    // для KPA-пакета с именем test1.
    pkgmgr::IPackageManifestPtr manifest;
    if (pkgc->GetManifest(uid1, manifest) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Получить уникальные идентификаторы установленных KPA-пакетов.
    std::vector<std::string> pkgUIDs;
    if (pkgc->ListInstalledPackages(pkgUIDs) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Удалить KPA-пакет с именем test1.
    if (pkgc->UninstallPackage(uid1) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Удалить KPA-пакет с именем test2.
    if (pkgc->UninstallPackage(uid2) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Получить из очереди уведомлений статусы KPA-пакетов.
    std::vector<package_manager::PackageEvent> pkgEvents;
    if (pkgc->GetEvents(eventQueue, pkgEvents) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Удалить очередь уведомлений.
    if (pkgc->DestroyEventQueue(eventQueue) != kos::rtl::Ok)
        return EXIT_FAILURE;

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

    // ...
}

В начало

Интерфейс IPackageManifest

API определен в заголовочном файле sysroot-*-kos/include/component/package_manager/i_package_manifest.h из состава KasperskyOS SDK.

API позволяет получать значения ключей манифеста KPA-пакета. Подробнее о доступных ключах манифеста KPA-пакета см. "Манифест KPA-пакета"

Сведения о функциях API приведены в таблице ниже.

Получение идентификатора программы

Чтобы получить идентификатор программы, установленной из KPA-пакета, нужно вызвать функцию GetPackageID().

Получение сведений о компонентах KPA-пакета

Чтобы получить сведения о компонентах KPA-пакета, нужно вызвать функцию GetApplicationsInfo(). Через выходной параметр applications функция возвращает сведения о компонентах KPA-пакета в виде вектора структур ApplicationInfo.

struct ApplicationInfo
{
    // Имя компонента KPA-пакета.
    std::string name;
    // Путь к директории относительно пути /<имя пакета>/res,
    // в которую установлен компонент KPA-пакета.
    std::string path;
    // Неиспользуемый параметр.
    std::string iconPath;
    // Неиспользуемый параметр.
    std::string containerPath;
    // Неиспользуемый параметр.
    std::string etcPath;
    // Хеш-сумма файла компонента KPA-пакета.
    std::string digest;
    // Объект формата JSON.
    ManifestType extensions;
    // Тип компонента KPA-пакета.
    std::string type;
};

Элемент структуры extensions описывает объект формата JSON. ManifestType является псевдонимом типа nlohmann:json.

Получение конфигураций запуска программы

Чтобы получить сведения о конфигурациях запуска программы, установленной из KPA-пакета, нужно вызвать функцию GetRunConfigurationsInfo(). Через выходной параметр runConfigurations функция возвращает сведения о конфигурациях запуска программы в виде вектора структур RunConfigurationInfo.

struct RunConfigurationInfo
{
    // Уникальный в рамках данного KPA-пакета идентификатор конфигурации запуска.
    std::string id;
    // Имя конфигурации запуска.
    std::string name;
    // Класс безопасности программы.
    std::string eiid;
    // Путь к файлу компонента KPA-пакета.
    std::string path;
    // Список аргументов в виде массива строк.
    std::vector<std::string> args{};
    // Список переменных окружения.
    std::vector<std::string> envs{};
    // Указывает, является эта конфигурация запуска первичной при старте программы:
    // true – является первичной, false – не является.
    bool primary{false};
    // Указывает, является эта конфигурация запускаемой автоматически:
    // true – является запускаемой автоматически, false – не является.
    bool autorun{false};
};

Получение сведений о программе

Чтобы получить сведения о программе, установленной из KPA-пакета, нужно вызвать функцию GetPackageInfo(). Через выходной параметр packageInfo функция возвращает сведения о конфигурациях запуска в виде структуры PackageInfo.

struct PackageInfo
{
    // Уникальный идентификатор программы.
    std::string id;
    // Название программы.
    std::string name;
    // Версия программы.
    std::string version;
    // Неиспользуемый параметр.
    std::string title;
    // Неиспользуемый параметр.
    std::string summary;
    // Описание программы.
    std::string description;
    // Номер сборки программы.
    std::string buildNumber;
    // Логическое значение, указывающее на то, является ли программа системной:
    // true – является, false – не является.
    bool systemApplication;
    // Объект произвольного формата.
    ManifestType extensions;
};

Получение сведений об изолированном хранилище программы

Чтобы получить сведения об изолированном хранилище программы, нужно вызвать функцию GetPrivateStorageInfo(). Через выходной параметр packageInfo функция возвращает сведения о конфигурациях запуска в виде структуры PrivateStorage.

struct PrivateStorage
{
    // Размер хранилища данных программы в МБ.
    size_t size;
    // Тип файловой системы хранилища данных программы.
    std::string fsType;
};

Получение сведений об объектах произвольного формата

Чтобы получить сведения об объектах произвольного формата, которые добавлены разработчиком KPA-пакета (ключ extensions из манифеста KPA-пакета), нужно вызвать функцию Get().

Функции i_package_manifest.h

Функция	Сведения о функции
`GetPackageID()`	Назначение Получает уникальный идентификатор программы, установленной из KPA-пакета. Параметры [out] `id` – уникальный идентификатор программы. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetApplicationsInfo()`	Назначение Получает сведения о компонентах KPA-пакета. Параметры [out] `applications` – вектор структур `ApplicationInfo`, содержащих сведения о компонентах KPA-пакета. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetRunConfigurationsInfo()`	Назначение Получает сведения о конфигурациях запуска программы, установленной из KPA-пакета. Параметры [out] `runConfigurations` – вектор структур `RunConfigurationInfo`, содержащих сведения о конфигурациях запуска. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetPackageInfo()`	Назначение Получает сведения о программе, установленной из KPA-пакета. Параметры [out] `packageInfo` – структура `PackageInfo`, содержащая сведения о программе. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`GetPrivateStorageInfo()`	Назначение Получает сведения об изолированно хранилище программы. Параметры [out] `packageInfo` – структура `PrivateStorage`, содержащая сведения об изолированном хранилище программы. Возвращаемые значения В случае успеха возвращает `kos::rtl::Ok`, иначе возвращает код ошибки.
`Get()`	Назначение Получает сведения об объектах произвольного формата, который добавлены в манифест разработчиком KPA-пакета. Параметры Нет. Возвращаемые значения Возвращает указатель на объект типа `pkgmgr::IPackageManifest::ManifestType`.

Пример использования:

client.cpp

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

namespace pkgmgr = package_manager;

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

    // Получить указатель на экземпляр интерфейса IPackageManifest
    // для KPA-пакета с уникальным идентификатором uid1.
    pkgmgr::IPackageManifestPtr manifest;
    if (pkgc->GetManifest(uid1, manifest) != kos::rtl::Ok)
        return EXIT_FAILURE;

    // Получить уникальный идентификатор программы.
    std::string packageID;
    if (manifest->GetPackageID(packageID) != kos::rtl::Ok)
        return EXIT_FAILURE;

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

    // Получить сведения о компонентах KPA-пакета.
    std::vector<package_manager::IPackageManifest::ApplicationInfo> infos;
    manifest->GetApplicationsInfo(infos);

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

    // Получить сведения об объектах произвольного формата.
    pkgmgr::IPackageManifest::ManifestType jsonManifest = manifest->Get();

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

    // Получить сведения о конфигурациях запуска программы, установленной из KPA-пакета.
    std::vector<package_manager::IPackageManifest::RunConfigurationInfo> runConfigurationInfos;
    manifest->GetRunConfigurationsInfo(runConfigurationInfos);

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

В начало