RtlInsertElementGenericTableAvl 函数 （ntddk.h）
RtlInsertElementGenericTableAvl 例程向泛型表添加新条目。
语法
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
参数
[in] Table
指向通过调用 RtlInitializeGenericTableAvl初始化的泛型 Adelson-Velsky/Landis（AVL）表（RTL_AVL_TABLE）。
[in] Buffer
调用方分配的缓冲区，其中包含要复制到新元素的用户数据。 有关详细信息，请参阅 RtlInitializeGenericTableAvl。
[in] BufferSize
Buffer 中的数据大小（以字节为单位）。
[out, optional] NewElement
在输出中，值为 TRUE 表示在泛型表中插入新元素已成功。 值为 FALSE 表示插入失败。
返回值
RtlInsertElementGenericTableAvl 返回指向新插入条目的用户数据的指针，或者返回已存在于泛型表中的匹配项的用户数据。 如果未找到匹配项，但 RtlInsertElementGenericTableAvl 无法插入新条目（例如，因为 AllocateRoutine 失败），RtlInsertElementGenericTableAvl 返回 NULL。
言论
若要插入条目，RtlInsertElementGenericTableAvl 调用 CompareRoutine，AllocateRoutine，RtlInitializeGenericTableAvl初始化泛型表时注册。 插入新条目后，RtlInsertElementGenericTableAvl 重新平衡 AVL 链接树。
将新项插入表中时，其数据将从 Buffer 复制到新条目中。 因此，RtlInsertElementGenericTableAvl 返回的指针绝不等于 Buffer。
如果调用方 CompareRoutine 返回 GenericEqual，则假定 Buffer 处的数据复制泛型表中现有条目的数据。 在这种情况下，RtlInsertElementGenericTableAvl 不会添加新项（因此不调用 AllocateRoutine），因为泛型表不能有重复条目。
如果泛型表中已存在匹配项，RtlInsertElementGenericTableAvl 返回指向现有条目数据的指针，并将 newElement 设置为 FALSE。
如果表中没有匹配项，RtlInsertElementGenericTableAvl 例程为新条目的用户数据（BufferSize）以及与新条目关联的链接分配足够的空间。 因此，字节总数至少 bufferSize + sizeof（RTL_BALANCED_LINKS）。 调用方不应使用 AllocateRoutine分配的内存的第一个 sizeof（RTL_BALANCED_LINKS） 字节。
Rtl. 的调用方。GenericTableAvl 例程负责专门同步对泛型表的访问。 独占快速互斥体是用于此目的的最高效的同步机制。
默认情况下，作系统使用 splay 树来实现泛型表，但 RtlInsertElementGenericTableAvl 例程仅适用于 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。
如果满足以下任一条件，则必须在 IRQL < DISPATCH_LEVEL 运行 RtlInsertElementGenericTableAvl 的调用方：
- 表 或 缓冲区 的调用方分配的内存可分页。
- 调用方提供的 CompareRoutine 或 AllocateRoutine 包含可分页代码。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | 从 Windows XP 开始可用。 |
| 目标平台 | 普遍 |
| 标头 | ntddk.h （包括 Ntddk.h、 Ntifs.h） |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL（请参阅“备注”部分） |