Функция RtlInsertElementGenericTableFullAvl (ntddk.h)
Подпрограмма RtlInsertElementGenericTableFullAvl добавляет новую запись в общую таблицу.
Синтаксис
NTSYSAPI PVOID RtlInsertElementGenericTableFullAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement,
[in] PVOID NodeOrParent,
[in] TABLE_SEARCH_RESULT SearchResult
);
Параметры
[in] Table
Указатель на универсальную таблицу Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE), которая была инициализирована вызовом RtlInitializeGenericTableAvl.
[in] Buffer
Выделенный вызывающим объектом буфер, содержащий данные пользователя для копирования в новый элемент. Дополнительные сведения см. в разделе RtlInitializeGenericTableAvl.
[in] BufferSize
Размер данных в байтах в буфере.
[out, optional] NewElement
В выходных данных значение TRUE означает, что вставка нового элемента в универсальной таблице выполнена успешно. Значение FALSE означает, что вставка завершилась сбоем.
[in] NodeOrParent
Результат поиска предыдущего вызова RtlLookupElementGenericTableFullAvl. Это значение указывает для подпрограммы RtlInsertElementGenericTableFullAvl , является ли дерево в настоящее время пустым или, если не пустым, следует ли вставить новую запись слева или справа от родительской записи. Параметр SearchResult может иметь любое из следующих значений:
TableEmptyTree
Дерево было пустым. Содержимое NodeOrParentне было изменено.
TableFoundNode
Подпрограмма RtlInsertElementGenericTableFullAvl обнаружила запись таблицы, ключ которой соответствует данным в буфере. NodeOrParent содержит указатель на соответствующую запись.
TableInsertAsLeft
Подпрограмма RtlInsertElementGenericTableFullAvlне обнаружила запись таблицы, ключ которой соответствует данным в буфере. Если запись, которую искал RtlInsertElementGenericTableFullAvl , была в таблице, она будет левым дочерним элементом записи, на которую указывает NodeOrParent .
TableInsertAsRight
Подпрограмма RtlInsertElementGenericTableFullAvlне обнаружила запись таблицы, ключ которой соответствует данным в буфере. Если запись, которую искал RtlInsertElementGenericTableFullAvl , находилась в таблице, она была бы правильным дочерним элементом записи, на которую указывает NodeOrParent .
[in] SearchResult
Указатель на запись таблицы. Если подпрограмма RtlInsertElementGenericTableFullAvl соответствует записи, NodeOrParent указывает на соответствующую запись. Если подпрограмме RtlInsertElementGenericTableFullAvl не удается найти совпадение, NodeOrParent указывает на запись, которая будет родительским элементом записи, которую искала подпрограмма RtlInsertElementGenericTableFullAvl .
Возвращаемое значение
RtlInsertElementGenericTableFullAvl возвращает указатель на пользовательские данные для вставленной записи или пользовательские данные для соответствующей записи, которая уже находится в универсальной таблице. Если соответствующая запись не найдена, но RtlInsertElementGenericTableFullAvl не может вставить новую запись (например, из-за сбоя AllocateRoutine ), RtlInsertElementGenericTableFullAvl возвращает значение NULL.
Комментарии
Чтобы вставить запись, RtlInsertElementGenericTableFullAvl вызывает CompareRoutine и AllocateRoutine , которые были зарегистрированы при инициализации универсальной таблицы RtlInitializeGenericTableAvl. После вставки новой записи RtlInsertElementGenericTableFullAvl повторно балансирует дерево ссылок AVL.
При вставке новой записи в таблицу ее данные копируются из буфера в новую запись. Таким образом, указатель, возвращаемый RtlInsertElementGenericTableFullAvl, никогда не равен Buffer.
Если CompareRoutine вызывающего объекта возвращает GenericEqual, предполагается, что данные в буфере дублируют данные для существующей записи в универсальной таблице. В этом случае RtlInsertElementGenericTableFullAvl не добавляет новую запись (и, следовательно, не вызывает AllocateRoutine), так как универсальная таблица не может содержать повторяющиеся записи.
Если соответствующая запись уже существует в универсальной таблице, RtlInsertElementGenericTableFullAvl возвращает указатель на данные существующей записи и задает для Свойства NewElementзначение FALSE.
Если в таблице уже нет соответствующей записи, подпрограмма RtlInsertElementGenericTableFullAvl выделяет достаточно места для пользовательских данных новой записи (BufferSize) и ссылок, связанных с новой записью. Таким образом, общее число байтов будет иметь значение по меньшей мере BufferSize + sizeof(BALANCED_LINKS). Вызывающий объект не должен использовать первый размер (BALANCED_LINKS) байтов памяти, выделенной AllocateRoutine.
Вызывающие объектRtl.. Подпрограммы GenericTableAvl отвечают за исключительно синхронизацию доступа к универсальной таблице. Эксклюзивный быстрый мьютекс является наиболее эффективным механизмом синхронизации для этой цели.
По умолчанию операционная система использует деревья splay для реализации универсальных таблиц, но подпрограмма RtlInsertElementGenericTableFullAvl работает только с деревьями Adelson-Velsky/Landis (AVL). Чтобы настроить в универсальных подпрограммах таблицы использование деревьев AVL вместо деревьев splay в драйвере, вставьте следующую инструкцию define в общий файл заголовка перед включением Ntddk.h:
#define RTL_USE_AVL_TABLES 0
Если RTL_USE_AVL_TABLES не определен, необходимо использовать форму AVL универсальных подпрограмм таблиц. Например, используйте подпрограмму RtlInsertElementGenericTableFullAvl вместо RtlInsertElementGenericTableFull. При вызове RtlInsertElementGenericTableFullAvl вызывающий объект должен передать RTL_AVL_TABLE табличную структуру, а не RTL_GENERIC_TABLE.
Вызывающие элементы RtlInsertElementGenericTableFullAvl должны выполняться на DISPATCH_LEVEL IRQL < , если выполняется одно из следующих условий:
- Память, выделенная вызывающим объектом в table или в буфере , доступна на страницы.
- Предоставленный вызывающим элементом CompareRoutine или AllocateRoutine содержит страничный код.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно в Windows XP и более поздних версиях операционных систем Windows. |
| Целевая платформа | Универсальное |
| Верхняя часть | ntddk.h (включая Ntddk.h, Ntifs.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (см. раздел "Примечания") |