Использование контейнеров данных (valcontainer.h)

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

API позволяет использовать контейнеры данных, элементами которых являются регионы памяти процесса с одинаковым размером и выравниванием. Контейнер данных создается пустым, а при добавлении в него элемента выделяется регион памяти, в который копируются требуемые данные. Данные в элементах контейнера можно изменять. Контейнер может содержать элементы с одинаковыми данными. Помимо операции добавления элемента поддерживаются операции поиска элемента по содержимому, перечисления элементов, удаления элемента, очистки контейнера.

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

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

Чтобы создать контейнер, нужно вызвать функцию KosValContainerCreate(). Через параметры size и align нужно задать размер и выравнивание элементов соответственно. Через параметр ops можно передать указатель на структуру, содержащую указатели на callback-функции, вызываемые перед добавлением и удалением элемента, а также указатель на callback-функцию сравнения содержимого элементов с ключом поиска. Кроме указателей на callback-функции, эта структура содержит поле ctx с указателем на объект данных, который используется callback-функциями для получения входных данных и/или сохранения выходных данных. (Все три callback-функции имеют параметр ctx, через который принимают указатель на этот объект данных.) Если этот объект данных не требуется ни одной из callback-функций, в поле ctx нужно указать RTL_NULL.

Можно задать только часть callback-функций. Также, если не требуется обрабатывать добавление и удаление элемента, а для сравнения содержимого элементов с ключом поиска подходит используемая по умолчанию функция, то в параметре ops нужно указать значение RTL_NULL. По умолчанию для сравнения содержимого элементов с ключом поиска используется функция, идентичная функции memcmp() из API библиотеки libc. При этом через третий параметр функции сравнении передается размер элемента.

Callback-функция, соответствующая указателю insert, вызывается перед добавлением элемента, то есть после выделения региона памяти и копирования данных в этот регион, но перед его включением в список элементов контейнера. Помимо параметра ctx эта callback-функция имеет параметр data, через который получает указатель на данные, скопированные в выделенный регион памяти. Эту callback-функцию можно использовать, например, чтобы проверить или обработать содержимое добавляемого элемента. Если код возврата имеет значение rcOk, то выделенный регион памяти включается в список элементов контейнера, иначе освобождается.

Callback-функция, соответствующая указателю remove, вызывается перед удалением элемента, то есть перед исключением региона памяти из списка элементов контейнера, после чего этот регион освобождается. В дополнение к параметру ctx, эта callback-функция имеет параметр data, через который получает указатель на содержимое удаляемого элемента. Эту callback-функцию можно использовать, например, чтобы освободить ресурсы.

Callback-функция, соответствующая указателю compare, используется для сравнения содержимого элементов с ключом поиска. Наряду с параметром ctx эта callback-функция имеет параметры data и key, через которые принимает указатели на содержимое элемента и ключ поиска соответственно. Эту callback-функцию можно использовать, например, чтобы выполнять поиск по хеш-суммам от содержимого элементов вместо побайтового сравнения, применяемого по умолчанию. Если содержимое элемента соответствует ключу поиска, код возврата должен иметь значение 0, иначе должен быть ненулевым.

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

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

Получение элемента контейнера

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

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

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

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

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

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

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

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

Обход элементов контейнера

Чтобы выполнить обход элементов контейнера, нужно использовать макрос KOS_VAL_CONTAINER_FOR_EACH(). Этот макрос раскрывается в заголовок оператора for. Указатель, заданный в параметре data, будет содержать адрес очередного элемента на каждой итерации. Используя этот указатель, можно, например, изменять содержимое элементов.

Перечисление элементов контейнера

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

Получение числа элементов в контейнере

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

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

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

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

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

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

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