Функция 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,, если новый элемент с данными в буфере вставлен в универсальную таблицу; или FALSE, если новый элемент не был вставлен.
Возвращаемое значение
RtlInsertElementGenericTable возвращает указатель на недавно вставленные данные элемента или возвращает указатель на данные существующего элемента, если соответствующий элемент уже существует в универсальной таблице. Если не найден соответствующий элемент, но новый элемент не может быть вставлен (например, так как AllocateRoutine завершается ошибкой), RtlInsertElementGenericTable возвращает NULL.
Замечания
Чтобы вставить элемент, RtlInsertElementGenericTable вызывает CompareRoutine и AllocateRoutine, зарегистрированные при инициализации универсальной таблицы RtlInitializeGenericTable. После вставки нового элемента RtlInsertElementGenericTable перебалансирует дерево ссылок воспроизведения.
При вставке нового элемента в таблицу его данные копируются из Buffer в новый элемент. Таким образом, указатель, возвращаемый RtlInsertElementGenericTable, никогда не равен буферу.
Если вызывающий CompareRoutine возвращает GenericEqual, предполагается, что данные buffer дублируют данные для существующего элемента в универсальной таблице. В этом случае RtlInsertElementGenericTable не добавляет новый элемент (и поэтому не вызывает AllocateRoutine), так как универсальная таблица не может содержать повторяющиеся элементы.
Если соответствующий элемент уже существует в универсальной таблице, RtlInsertElementGenericTable возвращает указатель на данные существующего элемента и задает NewElement значение FALSE.
Вызывающие объект Rtl.. Подпрограммы GenericTable отвечают за исключительно синхронизацию доступа к универсальной таблице. Эксклюзивный быстрый мьютекс является наиболее эффективным механизмом синхронизации, используемым для этой цели.
По умолчанию операционная система использует деревья воспроизведения для реализации универсальных таблиц. При некоторых обстоятельствах операции с деревом воспроизведения сделают дерево глубоким и узким и даже может превратить его в прямую линию. Очень глубокие деревья ухудшают производительность поиска. Вы можете обеспечить более сбалансированную, неглубокую реализацию универсальных таблиц с помощью деревьев Adelson-Velsky/Landis (AVL). Если вы хотите настроить универсальные подпрограммы таблиц для использования деревьев AVL вместо деревьев воспроизведения в драйвере, вставьте следующую инструкцию определения в общий файл заголовка перед включением Ntddk.h:
#define RTL_USE_AVL_TABLES 0
Если RTL_USE_AVL_TABLES не определен, необходимо использовать форму AVL универсальных подпрограмм таблиц. Например, используйте подпрограмму RtlInsertElementGenericTableAvl вместо RtlInsertElementGenericTable. В вызове RtlInsertElementGenericTableAvlвызывающий объект должен передать структуру таблицы RTL_AVL_TABLE, а не RTL_GENERIC_TABLE.
Вызывающие RtlInsertElementGenericTable должны работать в IRQL < DISPATCH_LEVEL, если имеет одно из следующих условий:
- Выделенная вызывающей памятью таблица или буфера можно пространить.
- Вызывающий CompareRoutine или AllocateRoutine содержит код, доступный для страниц.
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Всеобщий |
| заголовка | ntddk.h (include Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (см. раздел "Примечания") |