Функция RtlInsertElementGenericTable (ntddk.h)
Подпрограмма RtlInsertElementGenericTable добавляет новый элемент в общую таблицу.
Синтаксис
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Параметры
[in] Table
Указатель на универсальную таблицу (RTL_GENERIC_TABLE). Таблица должна быть инициализирована путем вызова RtlInitializeGenericTable.
[in] Buffer
Указатель на буфер, выделенный вызывающим объектом, содержащий данные для копирования в новый элемент. Дополнительные сведения см. в описании RtlInitializeGenericTable.
[in] BufferSize
Количество байтов, выделяемых для данных вызывающего объекта при вставке нового элемента.
[out, optional] NewElement
Указатель на переменную, которая получает значение TRUE , если новый элемент с данными в Buffer был вставлен в универсальную таблицу; или false , если новый элемент не был вставлен.
Возвращаемое значение
RtlInsertElementGenericTable возвращает указатель на связанные данные вновь вставленного элемента или указатель на данные существующего элемента, если соответствующий элемент уже существует в универсальной таблице. Если соответствующий элемент не найден, но новый элемент не может быть вставлен (например, из-за сбоя AllocateRoutine ), функция RtlInsertElementGenericTable возвращает значение NULL.
Комментарии
Чтобы вставить элемент, RtlInsertElementGenericTable вызывает CompareRoutine и AllocateRoutine , которые были зарегистрированы при инициализации универсальной таблицы rtlInitializeGenericTable. После вставки нового элемента RtlInsertElementGenericTable перераспределывает дерево ссылок splay.
При вставке нового элемента в таблицу его данные копируются из Buffer в новый элемент. Таким образом, указатель, возвращаемый RtlInsertElementGenericTable , никогда не равен Buffer.
Если Функция CompareRoutine вызывающего объекта возвращает GenericEqual, предполагается, что данные в buffer дублируют данные для существующего элемента в универсальной таблице. В этом случае RtlInsertElementGenericTable не добавляет новый элемент (и поэтому не вызывает AllocateRoutine), так как универсальная таблица не может содержать повторяющиеся элементы.
Если соответствующий элемент уже существует в универсальной таблице, RtlInsertElementGenericTable возвращает указатель на данные существующего элемента и устанавливает для NewElementзначение FALSE.
Вызывающие объект Rtl.. Подпрограммы GenericTable отвечают за исключительно синхронизацию доступа к универсальной таблице. Эксклюзивный быстрый мьютекс является наиболее эффективным механизмом синхронизации для этой цели.
По умолчанию операционная система использует деревья splay для реализации универсальных таблиц. В некоторых случаях операции с деревом splay сделают дерево глубоким и узким и может даже превратить его в прямую линию. Очень глубокие деревья ухудшают производительность поиска. С помощью деревьев Adelson-Velsky/Landis (AVL) можно обеспечить более сбалансированную и неглубокую реализацию универсальных таблиц. Если вы хотите настроить универсальные подпрограммы таблицы для использования деревьев AVL вместо деревьев splay в драйвере, вставьте следующую инструкцию define в общий файл заголовка перед включением Ntddk.h:
#define RTL_USE_AVL_TABLES 0
Если RTL_USE_AVL_TABLES не определен, необходимо использовать форму AVL универсальных подпрограмм таблиц. Например, используйте подпрограмму RtlInsertElementGenericTableAvl вместо RtlInsertElementGenericTable. При вызове RtlInsertElementGenericTableAvl вызывающий объект должен передать RTL_AVL_TABLE табличную структуру, а не RTL_GENERIC_TABLE.
Вызывающие элементы RtlInsertElementGenericTable должны выполняться на DISPATCH_LEVEL IRQL < , если выполняется одно из следующих условий:
- Память, выделенная вызывающим объектом в table или в буфере , доступна на страницы.
- Предоставленный вызывающим элементом CompareRoutine или AllocateRoutine содержит страничный код.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Верхняя часть | ntddk.h (включая Ntddk.h, Ntifs.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (см. раздел "Примечания") |