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

初期化されたジェネリックテーブル構造を格納するには、呼び出し元によって割り当てられたバッファーへのポインター。 sizeof(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

比較する 2 番目の項目へのポインター。

CompareRoutine は、特定の要素を識別できるように、ジェネリックテーブル内のすべての要素の順序を厳密に追跡する必要があります。通常、要素データの呼び出し元定義構造には、値が一意であり、並べ替えキーとして使用できるメンバーが含まれます。すべての Rtl...CompareRoutine を呼び出す GenericTableAvl ルーチンは、バッファーポインターをパラメーターとして受け取り、次に CompareRoutine に渡されます。バッファーには、 CompareRoutine によって検索対象の要素のキーと照合される呼び出し元が指定したキー値が含まれています。

このような 2 つのキー値を指定すると、 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)

ジェネリックテーブルへのポインター。

バッファー

削除される要素へのポインター。

Rtl。。。GenericTableAvl ルーチンは FreeRoutine を呼び出して、ジェネリックテーブルから削除される要素のメモリの割り当てを解除します。 FreeRoutine は AllocateRoutine の反対です。

[in, optional] TableContext

ジェネリックテーブルの呼び出し元が指定したコンテキストへの省略可能なポインター。このパラメーターは、NULL でもかまいません。

戻り値

なし

解説

ファイルシステムは RtlInitializeGenericTableAvl を呼び出して、現在開いているファイルの名前参照情報など、ファイルシステム固有のデータを格納する汎用テーブルを初期化します。要素の並べ替え順序、構造、および内容は呼び出し元によって定義されます。

ファイルシステムでは、他の Rtl..を使用する前に、汎用テーブルを初期化するために RtlInitializeGenericTableAvl を呼び出す必要があります 。新しいジェネリックテーブルの GenericTableAvl ルーチン。初期化されたジェネリックテーブル構造は不透明と見なす必要があります。

Rtl の呼び出し元 ...GenericTableAvl ルーチンは、ジェネリックテーブルへのアクセスを排他的に同期する役割を担います。排他高速ミューテックスは、この目的で使用する最も効率的な同期メカニズムです。

呼び出し元が指定した CompareRoutine は 、AllocateRoutine の前に呼び出され、新しい要素を挿入する適切な場所を見つけます。 また、削除する要素を見つけるために、FreeRoutine の前に CompareRoutine も呼び出されます。

RtlInitializeGenericTableAvl ルーチンは、AVL ツリーを使用する汎用テーブルを明示的に割り当てます。このルーチンと他の Rtl の使用 ...AVL ツリーベースのテーブルが必要であり、 Ntddk.h を含める前に RTL_USE_AVL_TABLES が定義されていない場合は、GenericTableAvl ルーチンが必要です。

汎用テーブルルーチンを構成する場合は、 Rtl...GenericTable では、ドライバーで再生ツリーの代わりに AVL ツリーを使用するには、 Ntddk.h を含める前に、共通のヘッダーファイルに次の define ステートメントを挿入します。

`#define RTL_USE_AVL_TABLES 0`

RtlInitializeGenericTableAvl の呼び出し元は IRQL <= DISPATCH_LEVELで実行されている必要があります。 Rtl..の場合は注意してください。GenericTableAvl ルーチンは IRQL DISPATCH_LEVELで使用されます。CompareRoutine、AllocateRoutine、FreeRoutine はすべて非ページコードである必要があり、AllocateRoutine は非ページプールからメモリを割り当てる必要があります。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	ntddk.h (Ntddk.h、Ntifs.h、Fltkernel.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (「解説」セクションを参照)