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

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

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

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

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

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

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

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

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

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

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

Навигация в контейнере

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

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

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

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

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

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

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

Макрос KosForEachObjContainerNolockObject() раскрывается в заголовок оператора for. Указатель, заданный в параметре obj, будет содержать адрес очередного объекта на каждой итерации. Используя этот указатель, можно выполнять действия с объектами, например, удалять из контейнера вызовом функции KosRemoveObjContainerNolockObject().

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

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

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

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

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

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

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

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

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

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

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

Сведения о функциях и макросах API

Функции и макросы objcontainernolock.h

Функция/Макрос	Сведения о функции/макросе
`KosCreateObjContainerNolock()`	Назначение Создает контейнер. Параметры [in,optional] `parent` – идентификатор родительского контейнера или `RTL_NULL`, если не требуется добавлять создаваемый контейнер в уже существующий. [in] `name` – указатель на имя создаваемого контейнера. Максимальный размер имени контейнера (в байтах) соответствует значению константы `KOS_OBJ_CONTAINER_UNSAFE_NAME_MAX`. [out] `outContainer` – указатель на идентификатор созданного контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosDestroyObjContainerNolock()`	Назначение Удаляет контейнер. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosClearObjContainerNolock()`	Назначение Очищает контейнер. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosInsertObjContainerNolockObject()`	Назначение Добавляет объект в контейнер. Параметры [in] `container` – идентификатор контейнера. [in] `name` – указатель на имя объекта. [in] `object` – указатель на объект. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosRemoveObjContainerNolockObjectByName()`	Назначение Удаляет из контейнера объект с заданным именем. Параметры [in] `container` – идентификатор контейнера. [in] `name` – указатель на имя объекта. [in,optional] `object` – указатель на объект или `RTL_NULL`, если не требуется проверять, что имя объекта, заданное через параметр `name`, соответствует удаляемому объекту. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosRemoveObjContainerNolockObject()`	Назначение Удаляет объект из контейнера. Параметры [in] `container` – идентификатор контейнера. [in] `object` – указатель на объект. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosGetObjContainerNolockObjectByName()`	Назначение Выполняет поиск объекта с заданным именем в контейнере. Параметры [in] `container` – идентификатор контейнера. [in] `name` – указатель на имя объекта, поиск которого нужно выполнить. [out] `outObject` – указатель на адрес найденного объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Если объект с заданным именем не найден, функция передает через параметр `outObject` значение `RTL_NULL`.
`KosWalkObjContainerNolockObjects()`	Назначение Выполняет обход объектов в контейнере и вызывает заданную функцию для каждого объекта при обходе. Параметры [in] `container` – идентификатор контейнера. [in] `walk` – идентификатор callback-функции, вызываемой для каждого объекта при обходе. Тип параметра определен в заголовочном файле `sysroot-*-kos/include/kos/objects.h` из состава KasperskyOS SDK. [in,optional] `context` – указатель на данные, которые будут переданы callback-функции, заданной через параметр `walk`. Можно указать `RTL_NULL`, если данные передавать не требуется. Callback-функция получит переданные данные через свой параметр `context`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosEnumObjContainerNolockNames()`	Назначение Перечисляет имена объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. [in] `index` – индекс для перечисления имен объектов. Нумерация начинается с нуля. [out] `outStr` – указатель на идентификатор строки `KosString` с именем объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosCountObjContainerNolockObjects()`	Назначение Позволяет получить число объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения Число объектов в контейнере.
`KosInitObjContainerNolockIterator()`	Назначение Инициализирует итератор для навигации в контейнере и получения доступа к объектам. Параметры [in] `container` – идентификатор контейнера. Возвращаемые значения Инициализированный итератор для навигации в контейнере и получения доступа к объектам.
`KosIsObjContainerNolockIteratorEnd()`	Назначение Проверяет, находится ли итератор в конечной позиции. Параметры [in] `iterator` – указатель на итератор. Возвращаемые значения В случае успешной проверки возвращает `rtl_true`, иначе возвращает `rtl_false`.
`KosGetObjContainerNolockIteratorObject()`	Назначение Позволяет получить объект, соответствующий текущей позиции итератора. Параметры [in] `iterator` – указатель на итератор. Возвращаемые значения Указатель на объект. Если итератор находится в конечной позиции, возвращает `RTL_NULL`.
`KosNextObjContainerNolockIterator()`	Назначение Перемещает итератор в следующую позицию. Параметры [in] `iterator` – указатель на итератор. Возвращаемые значения Нет.
`KosForEachObjContainerNolockObject()`	Назначение Выполняет обход объектов в контейнере. Параметры [in] `container` – идентификатор контейнера. [in] `obj` – указатель для сохранения адресов объектов при обходе. Значения макроса Нет.
`KosIsObjContainerNolock()`	Назначение Проверяет, является ли объект контейнером `KosObjContainer` или `KosObjContainerNolock`. Параметры [in] `object` – указатель на объект. Возвращаемые значения В случае успешной проверки возвращает `rtl_true`, иначе возвращает `rtl_false`.

В начало