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

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

API позволяет объединять объекты KosObject в контейнеры для удобства использования наборов этих объектов (об объектах KosObject см. "Использование объектов KosObject (objects.h)"). Контейнеры также являются объектами KosObject и могу быть элементами других контейнеров. Один и тот же объект KosObject может быть элементом нескольких контейнеров одновременно.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функции objcontainer.h

Функция	Сведения о функции
`KosCreateObjContainer()`	Назначение Создает контейнер. Параметры [in,optional] `parent` – идентификатор родительского контейнера или `RTL_NULL`, если не требуется добавлять создаваемый контейнер в уже существующий. [in] `name` – указатель на имя создаваемого контейнера. [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`, иначе возвращает код ошибки. Дополнительные сведения Callback-функция, заданная через параметр `walk`, не должна вызывать другие функции API. Если callback-функция, заданная через параметр `walk`, возвращает значение с флагом `KOS_OBJECT_WALK_FINISH`, то функция `KosWalkObjContainerObjects()` прекращает перечисление. Если callback-функция, заданная через параметр `walk`, возвращает значение с флагом `KOS_OBJECT_WALK_REMOVE_OBJECT`, то функция `KosWalkObjContainerObjects()` удаляет из контейнера соответствующий объект. Флаги `KOS_OBJECT_WALK_FINISH` и `KOS_OBJECT_WALK_REMOVE_OBJECT` определены в заголовочном файле `sysroot--kos/include/kos/objects.h` из состава KasperskyOS SDK.
`KosEnumObjContainerNames()`	Назначение Перечисляет имена объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. [in] `index` – индекс для перечисления имен объектов. Нумерация начинается с нуля. [out] `outStr` – указатель на идентификатор строки `KosString` с именем объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Функция `KosEnumObjContainerNames()` инкрементирует счетчик ссылок на строку `KosString` c именем объекта. Если эта строка больше не требуется, нужно декрементировать число ссылок на нее вызовом функции `KosPutString()` из API strings.h.
`KosCountObjContainerObjects()`	Назначение Позволяет получить число объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения Число объектов в контейнере.
`KosClearObjContainer()`	Назначение Очищает контейнер. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosIsContainer()`	Назначение Проверяет, является ли объект контейнером. Параметры [in] `object` – указатель на объект. Возвращаемые значения В случае успешной проверки возвращает `rtl_true`, иначе возвращает `rtl_false`.

В начало