RtlInitializeGenericTableAvl 函式 (ntddk.h)

發行項
02/26/2024

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 參數如下所示：

Table (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 例程。請注意，由於這個「額外的記憶體」，呼叫端提供的例程不得存取泛型數據表中任何元素的第一個 sizeof (RTL_BALANCED_LINKS) 位元組。

[in] FreeRoutine

解除分配回呼例程的進入點，宣告如下：

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

FreeRoutine 參數如下所示：

Table (FreeRoutine)

泛型數據表的指標。

Buffer

正在刪除之項目的指標。

Rtl。。。GenericTableAvl 例程會呼叫 FreeRoutine ，以解除分配要從泛型數據表中刪除之專案的記憶體。 FreeRoutine 與 AllocateRoutine 相反。

[in, optional] TableContext

泛型數據表之呼叫端所提供內容的選擇性指標。此參數可以是 Null。

傳回值

無

備註

文件系統會呼叫 RtlInitializeGenericTableAvl 來初始化泛型數據表來儲存文件系統特定數據，例如目前開啟檔案的名稱查閱資訊。專案的排序順序、結構和內容都是呼叫端定義的。

文件系統必須先呼叫 RtlInitializeGenericTableAvl ，才能使用任何其他 Rtl...新泛型數據表上的 GenericTableAvl 例程。初始化的泛型數據表結構應該視為不透明。

Rtl 的呼叫端 ...GenericTableAvl 例程負責獨佔同步處理泛型數據表的存取權。獨佔快速 Mutex 是用於此用途的最有效率同步處理機制。

呼叫端提供的 CompareRoutine 會在 AllocateRoutine 之前呼叫，以找出應該插入新元素的適當位置。 CompareRoutine 也會在 FreeRoutine 之前呼叫，以找出要刪除的專案。

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 應該從非分頁集區配置記憶體。

規格需求

需求	值
目標平台	Universal
標頭	ntddk.h (包含 Ntddk.h、Ntifs.h、Fltkernel.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (请参阅一节)