RtlEnumerateGenericTableLikeADirectory 関数 (ntddk.h)
RtlEnumerateGenericTableLikeADirectory ルーチンは、ジェネリック テーブルの要素を照合順序順に 1 つずつ返します。
構文
NTSYSAPI PVOID RtlEnumerateGenericTableLikeADirectory(
[in] PRTL_AVL_TABLE Table,
[in, optional] PRTL_AVL_MATCH_FUNCTION MatchFunction,
[in, optional] PVOID MatchData,
[in] ULONG NextFlag,
[in, out] PVOID *RestartKey,
[in, out] PULONG DeleteCount,
[in] PVOID Buffer
);
パラメーター
[in] Table
列挙される Adelson-Velsky/Landis (AVL) テーブル (RTL_AVL_TABLE) へのポインター。
[in, optional] MatchFunction
返すエントリを決定する match 関数。 指定しない場合は、すべてのノードが返されます。
[in, optional] MatchData
match 関数に渡すデータ。
[in] NextFlag
RestartKey が NULL でない場合、値 TRUE は列挙が要素をスキップすることを示します。 FALSE の場合、列挙は RtlEnumerateGenericTableLikeADirectory の前回の呼び出しで中断したところから再開されます。 RestartKey が NULL の場合、値 TRUE は RtlEnumerateGenericTableLikeADirectory に、Buffer 内のデータと一致するエントリの後のツリー内の次のエントリを返すように指示します。 FALSE の値は、Buffer 内のデータと一致するツリー内のエントリを返すように RtlEnumerateGenericTableLikeADirectory に指示します。
[in, out] RestartKey
ジェネリック テーブル要素の列挙を開始または再開する場所を決定する 値。 RestartKey が NULL の場合、列挙は Buffer で説明されている位置から開始または再開されます。 NULL でない場合、列挙は RestartKey が示すポイントから再開されます。 戻り値の 場合、RestartKey には、列挙が中断されたツリー内の場所を示す値が保持されます。 RtlEnumerateGenericTableLikeADirectory 呼び出し元への次の呼び出しでは、列挙を再開する場所を RtlEnumerateGenericTableLikeADirectory に通知するために、同じ値を渡す必要があります。 次のコード例は、これを行う方法を示しています。
NextFlag = FALSE;
RestartKey = NULL;
DeleteCount = 0;
// Initialize Buffer for start/resume point
Buffer = ...
for (ptr = NULL; ptr != NULL; ) {
// Value returned in RestartKey will be passed back in
// on following call (iteration):
ptr = RtlEnumerateGenericTableLikeADirectory(
&MyTable, NULL, NULL, TRUE, &RestartKey,
&DeleteCount, &Buffer, sizeof(LONG) );
...
// The value output in RestartKey will still be in
// RestartKey when the
// RtlEnumerationGenericTableLikeADirectory routine
// is called in the next iteration of this loop.
// This ensures that the enumeration will pick up
// where it left off.
}
RtlEnumerateGenericTableLikeADirectory の呼び出しの間にツリーからノードが削除された場合、RestartKey の値に関係なく、「Buffer」で説明されているツリー内の位置から列挙が再開されます。
[in, out] DeleteCount
出力時に、テーブルから削除されたエントリの現在の数を示す値。 呼び出し元は、 RtlEnumerateGenericTableLikeADirectory の次の呼び出し時に、この値を戻す必要があります。 この値は 、RtlEnumerateGenericTableLikeADirectory ルーチンが RtlEnumerateGenericTableLikeADirectory の呼び出しの間にテーブルからの削除が発生したかどうかを判断するのに役立ちます。 削除が発生した場合、列挙は、RestartKey で示されるテーブル エントリではなく、Buffer 内のデータと一致するテーブル エントリを使用して再開されます。 RestartKey が NULL の場合、このパラメーターは列挙には影響しません。
[in] Buffer
RestartKey が NULL の場合に列挙を開始する場所を決定するキー式。 呼び出し元は、テーブル内の特定のエントリに一致する保存されたキーを渡すことができます。 RestartKey が NULL で NextFlag が FALSE の場合、列挙は保存されたキーで指定されたエントリから開始されます。 保存されたキーの直後にあるキーを返すには、ここでキーを渡し、 RestartKey を NULL に設定し、 NextFlag を TRUE に設定します。 保存したキーが削除された場合、列挙は次に一致するキーで始まります。
戻り値
RtlEnumerateGenericTableLikeADirectory ルーチンは、列挙体の次の table 要素に関連付けられているユーザー定義構造体へのポインターを返します。 戻り値を返す新しい要素がこれ以上ない場合、戻り値は NULL です。
注釈
RtlEnumerateGenericTableLikeADirectory ルーチンは、混在する挿入操作と削除操作の間で汎用テーブルを列挙するための安全な手段を提供します。 最初に一致したキー名から、 RtlEnumerateGenericTableLikeADirectory は 、列挙中に名前が挿入または削除されない限り、テーブル内の各名前を 1 回だけ返します。 列挙中 ( RtlEnumerateGenericTableLikeADirectory の呼び出しの間) にキー名を挿入または削除すると、列挙に含まれる場合と含まれない場合があります。 このような名前を含めるかどうかは、名前が見つかったディレクトリ範囲を RtlEnumerateGenericTableLikeADirectory が処理するときの名前の状態によって異なります。
ジェネリック テーブルを列挙するために使用できるルーチンは 4 つあります。
既定では、オペレーティング システムは splay ツリーを使用して汎用テーブルを実装しますが、 RtlEnumerateGenericTableLikeADirectory ルーチンは Adelson-Velsky/Landis (AVL) ツリーでのみ機能します。 ドライバーでツリーを再生する代わりに AVL ツリーを使用するように汎用テーブル ルーチンを構成するには、Ntddk.h を含める前に、共通ヘッダー ファイルに次の define ステートメントを挿入します。
#define RTL_USE_AVL_TABLES 0
RTL_USE_AVL_TABLESが定義されていない場合は、汎用テーブル ルーチンの AVL 形式を使用する必要があります。
RtlEnumerateGenericTableLikeADirectory の呼び出し元は、次のいずれかの条件が満たされている場合、IRQL <= APC_LEVELで実行されている必要があります。
呼び出し元によって割り当てられたメモリ ( Table または Buffer) はページング可能です。
呼び出し元から提供された MatchFunction には、ページング可能なコードが含まれています。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntddk.h、Ntifs.h、FltKernel.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | <= APC_LEVEL (「解説」セクションを参照) |