Функция RtlInsertElementGenericTableAvl (ntddk.h)
Подпрограмма RtlInsertElementGenericTableAvl добавляет новую запись в универсальную таблицу.
Синтаксис
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Параметры
[in] Table
Указатель на универсальную таблицу Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE), которая была инициализирована вызовом RtlInitializeGenericTableAvl.
[in] Buffer
Выделенный вызывающим буфер, содержащий данные пользователя для копирования в новый элемент. Дополнительные сведения см. в разделе RtlInitializeGenericTableAvl.
[in] BufferSize
Размер в байтах данных в буфере .
[out, optional] NewElement
В выходных данных значение TRUE означает успешное вставка нового элемента в универсальной таблице. Значение FALSE означает сбой вставки.
Возвращаемое значение
RtlInsertElementGenericTableAvl возвращает указатель на пользовательские данные для недавно вставленной записи или данные пользователя для соответствующей записи, которая уже находится в универсальной таблице. Если запись не найдена, но RtlInsertElementGenericTableAvl не удается вставить новую запись (например, так как AllocateRoutine завершается ошибкой), RtlInsertElertElementGenericTableAvl возвращает NULL.
Замечания
Чтобы вставить запись, RtlInsertElementGenericTableAvl вызывает CompareRoutine и AllocateRoutine, зарегистрированные при инициализации универсальной таблицы RtlInitializeGenericTableAvl. После вставки новой записи RtlInsertElementGenericTableAvl перебалансирует дерево ссылок AVL.
При вставке новой записи в таблицу данные копируются из буфера в новую запись. Таким образом, указатель, возвращаемый RtlInsertElementGenericTableAvl, никогда не равен буферу.
Если вызывающий CompareRoutine возвращает GenericEqual, предполагается, что данные буфера дублируют данные для существующей записи в универсальной таблице. В этом случае RtlInsertElementGenericTableAvl не добавляет новую запись (и поэтому не вызывает AllocateRoutine), так как универсальная таблица не может содержать повторяющиеся записи.
Если соответствующая запись уже существует в универсальной таблице, RtlInsertElertElementGenericTableAvl возвращает указатель на данные существующей записи и задает NewElement значение FALSE.
Если в таблице нет соответствующей записи,RtlInsertElementGenericTableAvl выделяет достаточно места для пользовательских данных новой записи (BufferSize) и ссылок, связанных с новой записью. Таким образом, общее количество байтов будет по крайней мере BufferSize + sizeof(RTL_BALANCED_LINKS). Вызывающий объект не должен использовать первые размер(RTL_BALANCED_LINKS) памяти, выделенной AllocateRoutine.
Вызывающие Rtl.. Подпрограммы GenericTableAvl отвечают за исключительно синхронизацию доступа к универсальной таблице. Эксклюзивный быстрый мьютекс является наиболее эффективным механизмом синхронизации, используемым для этой цели.
По умолчанию операционная система использует деревья воспроизведения для реализации универсальных таблиц, но RtlInsertElementGenericTableAvl подпрограмма работает только с деревьями 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.
Вызывающие RtlInsertElementGenericTableAvl должны выполняться в IRQL < DISPATCH_LEVEL, если имеет одно из следующих условий:
- Выделенная вызывающей памятью таблица или буфера можно пространить.
- Вызывающий CompareRoutine или AllocateRoutine содержит код, доступный для страниц.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Доступно начиная с Windows XP. |
| целевая платформа | Всеобщий |
| заголовка | ntddk.h (include Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (см. раздел "Примечания") |