Использование контейнеров KosObjContainer (objcontainer.h)

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

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

Создание контейнера

Чтобы создать контейнер, нужно вызвать функцию KosCreateObjContainer(). В параметре parent можно указать идентификатор родительского контейнера, то есть контейнера KosObjContainer, KosObjContainerNolock или KosBaseContainer, в который будет добавлен создаваемый контейнер.

Добавление объекта в контейнер

Чтобы добавить объект в контейнер, нужно вызвать функцию KosInsertObjContainerObject(). Можно добавить любой объект KosObject, включая контейнер KosObjContainer, KosObjContainerNolock или KosBaseContainer. Через параметр name нужно задать имя объекта, которое этот объект будет иметь внутри контейнера. Это имя не связано с именем, которое было задано при создании объекта. Имя объекта внутри контейнера должно быть уникальным. Можно добавить один и тот же объект несколько раз с разными именами. Добавление объекта в контейнер инкрементирует счетчик ссылок на этот объект.

Удаление объекта из контейнера

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

Поиск объекта в контейнере

Чтобы выполнить поиск объекта с заданным именем в контейнере, нужно вызвать функцию KosGetObjContainerObjectByName(). Поиск объекта в дочерних контейнерах не выполняется. Функция инкрементирует счетчик ссылок на найденный объект.

Обход объектов в контейнере

Чтобы выполнить обход объектов в контейнере, нужно вызвать функцию KosWalkObjContainerObjects(). Через параметр walk нужно задать callback-функцию, которая вызывается для каждого объекта при обходе и получает указатели на объект и данные, переданные функции KosWalkObjContainerObjects() через параметр context. Callback-функция не должна вызывать другие функции API. Если callback-функция возвращает значение с флагом KOS_OBJECT_WALK_FINISH, то функция KosWalkObjContainerObjects() прекращает обход. Если callback-функция возвращает значение с флагом KOS_OBJECT_WALK_REMOVE_OBJECT, то функция KosWalkObjContainerObjects() удаляет из контейнера соответствующий объект. (Флаги определены в заголовочном файле sysroot-*-kos/include/kos/objects.h из состава KasperskyOS SDK.)

Обход объектов в дочерних контейнерах не выполняется.

Перечисление имен объектов в контейнере

Чтобы перечислить имена объектов в контейнере, нужно использовать функцию KosEnumObjContainerNames(). Порядок перечисления имен объектов соответствует порядку добавления этих объектов в контейнер. Перечисление имен объектов в дочерних контейнерах не выполняется. Функция инкрементирует счетчик ссылок на строку KosString c именем объекта. Если эта строка больше не требуется, нужно декрементировать счетчик ссылок на нее вызовом функции KosPutString() из API strings.h.

Получение числа объектов в контейнере

Чтобы получить число объектов в контейнере, нужно вызвать функцию KosCountObjContainerObjects(). Объекты в дочерних контейнерах не учитываются.

Очистка контейнера

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

Проверка, является ли объект контейнером

Чтобы проверить, является ли объект контейнером KosObjContainer, нужно вызвать функцию KosIsContainer().

Удаление контейнера

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

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

Функции objcontainer.h

Функция	Сведения о функции
`KosCreateObjContainer()`	Назначение Создает контейнер. Параметры [in,optional] `parent` – идентификатор родительского контейнера или `RTL_NULL`, если не требуется добавлять создаваемый контейнер в уже существующий. [in] `name` – указатель на имя создаваемого контейнера. Максимальный размер имени контейнера (в байтах) соответствует значению константы `KOS_OBJ_CONTAINER_NAME_MAX`. [out] `outContainer` – указатель на идентификатор созданного контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosDestroyObjContainer()`	Назначение Удаляет контейнер. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosInsertObjContainerObject()`	Назначение Добавляет объект в контейнер. Параметры [in] `container` – идентификатор контейнера. [in] `name` – указатель на имя объекта. [in] `object` – указатель на объект. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosRemoveObjContainerObjectByName()`	Назначение Удаляет из контейнера объект с заданным именем. Параметры [in] `container` – идентификатор контейнера. [in] `name` – указатель на имя объекта. [in,optional] `object` – указатель на объект или `RTL_NULL`, если не требуется проверять, что имя объекта, заданное через параметр `name`, соответствует удаляемому объекту. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosRemoveObjContainerObject()`	Назначение Удаляет объект из контейнера. Параметры [in] `container` – идентификатор контейнера. [in] `object` – указатель на объект. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosGetObjContainerObjectByName()`	Назначение Выполняет поиск объекта с заданным именем в контейнере. Параметры [in] `container` – идентификатор контейнера. [in] `name` – указатель на имя объекта, поиск которого нужно выполнить. [out] `outObject` – указатель на адрес найденного объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Если объект с заданным именем не найден, функция передает через параметр `outObject` значение `RTL_NULL`.
`KosWalkObjContainerObjects()`	Назначение Выполняет обход объектов в контейнере и вызывает заданную функцию для каждого объекта при обходе. Параметры [in] `container` – идентификатор контейнера. [in] `walk` – идентификатор callback-функции, вызываемой для каждого объекта при обходе. Тип параметра определен в заголовочном файле `sysroot-*-kos/include/kos/objects.h` из состава KasperskyOS SDK. [in,optional] `context` – указатель на данные, которые будут переданы callback-функции, заданной через параметр `walk`. Можно указать `RTL_NULL`, если данные передавать не требуется. Callback-функция получит переданные данные через свой параметр `context`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosEnumObjContainerNames()`	Назначение Перечисляет имена объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. [in] `index` – индекс для перечисления имен объектов. Нумерация начинается с нуля. [out] `outStr` – указатель на идентификатор строки `KosString` с именем объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosCountObjContainerObjects()`	Назначение Позволяет получить число объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения Число объектов в контейнере.
`KosClearObjContainer()`	Назначение Очищает контейнер. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosIsContainer()`	Назначение Проверяет, является ли объект контейнером `KosObjContainer`. Параметры [in] `object` – указатель на объект. Возвращаемые значения В случае успешной проверки возвращает `rtl_true`, иначе возвращает `rtl_false`.

В начало