RtlInitializeGenericTableAvl 函数 (ntddk.h)

项目
03/08/2023

RtlInitializeGenericTableAvl 例程使用 Adelson-Velsky/Landis (AVL) 树初始化泛型表。

语法

NTSYSAPI VOID RtlInitializeGenericTableAvl(
  [out]          PRTL_AVL_TABLE            Table,
  [in]           PRTL_AVL_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_AVL_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_AVL_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                     TableContext
);

参数

[out] Table

指向调用方分配的缓冲区的指针，该缓冲区 的大小 必须至少为 (RTL_AVL_TABLE) 字节，才能包含初始化的泛型表结构。

[in] CompareRoutine

比较回调例程的入口点，声明如下：

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    );

CompareRoutine 参数如下所示：

表 (CompareRoutine)

指向泛型表的指针。

FirstStruct

指向要比较的第一项的指针。

SecondStruct

指向要比较的第二项的指针。

CompareRoutine 必须严格跟踪泛型表中所有元素的顺序，以便它可以标识任何特定元素。元素数据的调用方定义的结构通常包括一个成员，其值是唯一的，可用作排序键。所有 Rtl... 调用 CompareRoutine 的 GenericTableAvl 例程将缓冲区指针作为参数，该参数将依次传递给 CompareRoutine。缓冲区包含调用方提供的键值， CompareRoutine 将与要搜索的元素的键进行匹配。

给定两个这样的键值， CompareRoutine 返回 GenericLessThan、 GenericGreaterThan 或 GenericEqual。

[in] AllocateRoutine

分配回调例程的入口点，声明如下：

PVOID
(*PRTL_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in CLONG  ByteSize
    );

AllocateRoutine 参数如下所示：

Table (AllocateRoutine)

指向泛型表的指针。

ByteSize

要分配的字节数。

对于每个新元素，调用 AllocateRoutine 来为调用方提供的数据分配内存，以及一些额外的内存供 Rtl...GenericTableAvl 例程。请注意，由于这种“额外内存”，调用方提供的例程不得访问泛型表中任何元素的第一个大小 (RTL_BALANCED_LINKS) 字节。

[in] FreeRoutine

解除分配回调例程的入口点，声明如下：

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  Buffer
    );

FreeRoutine 参数如下所示：

表 (FreeRoutine)

指向泛型表的指针。

Buffer

指向要删除的元素的指针。

Rtl。。。GenericTableAvl 例程调用 FreeRoutine 以解除分配要从泛型表中删除的元素的内存。 FreeRoutine 与 AllocateRoutine 相反。

[in, optional] TableContext

指向泛型表的调用方提供的上下文的可选指针。此参数可以为 NULL。

返回值

无

备注

文件系统调用 RtlInitializeGenericTableAvl 来初始化泛型表以存储文件系统特定的数据，例如当前打开的文件的名称查找信息。元素的排序顺序、结构和内容由调用方定义。

文件系统必须调用 RtlInitializeGenericTableAvl 以初始化泛型表，然后才能使用任何其他 Rtl...新泛型表上的 GenericTableAvl 例程。初始化的泛型表结构应被视为不透明。

Rtl 的调用方 ...GenericTableAvl 例程负责以独占方式同步对泛型表的访问。排他快速互斥体是用于此目的的最有效同步机制。

调用方提供的 CompareRoutine 在 AllocateRoutine 之前调用，以找到应插入新元素的适当位置。 在 FreeRoutine 之前，还会调用 CompareRoutine，以查找要删除的元素。

RtlInitializeGenericTableAvl 例程显式分配使用 AVL 树的泛型表。使用此例程和其他 Rtl... 如果需要基于 AVL 树的表，并且未在包括 Ntddk.h 之前定义RTL_USE_AVL_TABLES，则必须使用 GenericTableAvl 例程。

如果要配置泛型表例程， 则 Rtl...GenericTable 若要在驱动程序中使用 AVL 树而不是 splay 树，请在包含 Ntddk.h 之前在通用头文件中插入以下 define 语句：

`#define RTL_USE_AVL_TABLES 0`

RtlInitializeGenericTableAvl 的调用方必须在 IRQL <= DISPATCH_LEVEL 运行。请注意，如果 Rtl...GenericTableAvl 例程要在 IRQL DISPATCH_LEVEL中使用， CompareRoutine、 AllocateRoutine 和 FreeRoutine 都必须是不可分页的代码，并且 AllocateRoutine 应从非分页池分配内存。

要求

要求	值
目标平台	通用
标头	ntddk.h (包括 Ntddk.h、Ntifs.h、Fltkernel.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (请参阅备注部分)