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

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

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

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

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

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

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

Добавление объектов в контейнер из другого контейнера

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

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

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

Перемещение объекта в другой контейнер

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функция/Макрос	Сведения о функции/макросе
KosBaseContainerCreateContainer()	Назначение Создает контейнер. Параметры [in,optional] parent – идентификатор родительского контейнера или RTL_NULL, если не требуется добавлять создаваемый контейнер в уже существующий. [out] outContainer – указатель на идентификатор созданного контейнера. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerDestroyContainer()	Назначение Удаляет контейнер. Параметры [in] container – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerInsertObject()	Назначение Добавляет объект в контейнер. Параметры [in] container – идентификатор контейнера. [in] object – указатель на объект. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerRemoveObject()	Назначение Удаляет объект из контейнера. Параметры [in] container – идентификатор контейнера. [in] object – указатель на объект. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerMoveObject()	Назначение Перемещает объект из одного контейнера в другой. Параметры [in] destination – идентификатор контейнера-приемника. [in] source – идентификатор контейнера-источника. [in] object – указатель на объект. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerWalkObjects()	Назначение Выполняет обход объектов в контейнере и вызывает заданную функцию для каждого объекта при обходе. Параметры [in] container – идентификатор контейнера. [in] walk – идентификатор callback-функции, вызываемой для каждого объекта при обходе. Тип параметра определен в заголовочном файле sysroot-*-kos/include/kos/objects.h из состава KasperskyOS SDK. [in,optional] context – указатель на данные, которые будут переданы callback-функции, заданной через параметр walk. Можно указать RTL_NULL, если данные передавать не требуется. Callback-функция получит переданные данные через свой параметр context. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerEnumContainerObjects()	Назначение Перечисляет объекты в контейнере. Параметры [in] container – идентификатор контейнера. [in] index – индекс для перечисления объектов. Нумерация начинается с нуля. Возвращаемые значения Указатель на объект. Если значение индекса превышено, возвращает RTL_NULL.
KosBaseContainerCount()	Назначение Позволяет получить число объектов в контейнере. Параметры [in] container – идентификатор контейнера. Возвращаемые значения Число объектов в контейнере.
KosBaseContainerClear()	Назначение Очищает контейнер. Параметры [in] container – идентификатор контейнера. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerAppend()	Назначение Добавляет в контейнер объекты из другого контейнера. Параметры [in] destination – идентификатор контейнера-приемника. [in] source – идентификатор контейнера-источника. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosBaseContainerIteratorInit()	Назначение Инициализирует итератор для навигации в контейнере и получения доступа к объектам. Параметры [in] container – идентификатор контейнера. Возвращаемые значения Инициализированный итератор для навигации в контейнере и получения доступа к объектам.
KosBaseContainerIteratorIsEnd()	Назначение Проверяет, находится ли итератор в конечной позиции. Параметры [in] iterator – указатель на итератор. Возвращаемые значения В случае успешной проверки возвращает rtl_true, иначе возвращает rtl_false.
KosBaseContainerIteratorGetObject()	Назначение Позволяет получить объект, соответствующий текущей позиции итератора. Параметры [in] iterator – указатель на итератор. Возвращаемые значения Указатель на объект. Если итератор находится в конечной позиции, возвращает RTL_NULL.
KosBaseContainerIteratorNext()	Назначение Перемещает итератор в следующую позицию. Параметры [in] iterator – указатель на итератор. Возвращаемые значения Нет.
KosBaseContainerIteratorForEachObject()	Назначение Выполняет обход объектов в контейнере. Параметры [in] container – идентификатор контейнера. [in] obj – указатель для сохранения адресов объектов при обходе. Значения макроса Нет.

В начало