RtlInsertElementGenericTable 関数 (ntddk.h)
RtlInsertElementGenericTable ルーチンは、ジェネリック テーブルに新しい要素を追加します。
構文
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
パラメーター
[in] Table
ジェネリック テーブルへのポインター (RTL_GENERIC_TABLE)。 テーブルは RtlInitializeGenericTable を呼び出して初期化されている必要があります。
[in] Buffer
新しい要素にコピーされるデータを含む呼び出し元によって割り当てられたバッファーへのポインター。 詳細については、 RtlInitializeGenericTable の説明を参照してください。
[in] BufferSize
新しい要素が挿入されたときに呼び出し元から提供されたデータに割り当てられるバイト数。
[out, optional] NewElement
Buffer のデータを含む新しい要素がジェネリック テーブルに挿入された場合に TRUE を受け取る変数へのポインター。または、新しい要素が挿入されていない場合は FALSE。
戻り値
RtlInsertElementGenericTable は 、新しく挿入された要素の関連付けられたデータへのポインターを返します。一致する要素がジェネリック テーブルに既に存在する場合は、既存の要素のデータへのポインターを返します。 一致する要素が見つからないが、新しい要素を挿入できない場合 (たとえば、 AllocateRoutine が失敗するため)、 RtlInsertElementGenericTable は NULL を返します。
注釈
要素を挿入するために、RtlInsertElementGenericTable は、汎用テーブルが RtlInitializeGenericTable によって初期化されたときに登録された CompareRoutine と AllocateRoutine を呼び出します。 新しい要素を挿入すると、 RtlInsertElementGenericTable によって 、splay リンク ツリーが再調整されます。
新しい要素がテーブルに挿入されると、そのデータが Buffer から新しい要素にコピーされます。 したがって、 RtlInsertElementGenericTable によって返されるポインターが Buffer と等しいことはありません。
呼び出し元の CompareRoutine が GenericEqual を返す場合、 Buffer のデータはジェネリック テーブル内の既存の要素のデータを複製するものと見なされます。 この場合、 RtlInsertElementGenericTable は新しい要素を追加しません (したがって 、AllocateRoutine は呼び出されません)。ジェネリック テーブルに重複する要素を含めることはできません。
一致する要素がジェネリック テーブルに既に存在する場合、 RtlInsertElementGenericTable は 既存の要素のデータへのポインターを返し 、NewElement を FALSE に設定 します。
Rtl の呼び出し元..GenericTable ルーチンは、ジェネリック テーブルへのアクセスを排他的に同期する役割を担います。 排他高速ミューテックスは、この目的で使用する最も効率的な同期メカニズムです。
既定では、オペレーティング システムは splay ツリーを使用して汎用テーブルを実装します。 状況によっては、スプレイ ツリーを操作すると、ツリーが深く狭く、直線に変わる場合もあります。 非常に深いツリーでは、検索のパフォーマンスが低下します。 Adelson-Velsky/Landis (AVL) ツリーを使用して、ジェネリック テーブルのよりバランスの取れた浅いツリー実装を確保できます。 ドライバーでツリーを再生する代わりに AVL ツリーを使用するように汎用テーブル ルーチンを構成する場合は、 Ntddk.h を含める前に、共通ヘッダー ファイルに次の define ステートメントを挿入します。
#define RTL_USE_AVL_TABLES 0
RTL_USE_AVL_TABLESが定義されていない場合は、汎用テーブル ルーチンの AVL 形式を使用する必要があります。 たとえば、 RtlInsertElementGenericTable の代わりに RtlInsertElementGenericTableAvl ルーチンを使用 します。 RtlInsertElementGenericTableAvl の呼び出しでは、呼び出し元はRTL_GENERIC_TABLEではなく、RTL_AVL_TABLEテーブル構造を渡す必要があります。
次のいずれかの条件が満たされている場合、 RtlInsertElementGenericTable の呼び出し元は IRQL < DISPATCH_LEVELで実行されている必要があります。
- 呼び出し元によって割り当てられたメモリ ( Table または Buffer) はページング可能です。
- 呼び出し元から提供された CompareRoutine または AllocateRoutine には、ページング可能なコードが含まれています。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (「解説」セクションを参照) |