RtlInsertElementGenericTableFullAvl 関数 (ntddk.h)

RtlInsertElementGenericTableFullAvl ルーチンは、ジェネリック テーブルに新しいエントリを追加します。

構文

NTSYSAPI PVOID RtlInsertElementGenericTableFullAvl(
  [in]            PRTL_AVL_TABLE      Table,
  [in]            PVOID               Buffer,
  [in]            CLONG               BufferSize,
  [out, optional] PBOOLEAN            NewElement,
  [in]            PVOID               NodeOrParent,
  [in]            TABLE_SEARCH_RESULT SearchResult
);

パラメーター

[in] Table

RtlInitializeGenericTableAvl の呼び出しによって初期化された汎用 Adelson-Velsky/Landis (AVL) テーブル (RTL_AVL_TABLE) へのポインター。

[in] Buffer

新しい要素にコピーするユーザー データを含む呼び出し元によって割り当てられたバッファー。 詳細については、「 RtlInitializeGenericTableAvl」を参照してください。

[in] BufferSize

Buffer 内のデータのサイズ (バイト単位 )。

[out, optional] NewElement

出力時に TRUE の 値は、ジェネリック テーブル内の新しい要素の挿入が成功したことを意味します。 FALSE の値は、挿入に失敗したことを意味します。

[in] NodeOrParent

RtlLookupElementGenericTableFullAvl の以前の呼び出しの検索結果。 この値は、ツリーが現在空かどうか、または空でない場合は親エントリの左または右に新しいエントリを挿入するかどうかを RtlInsertElementGenericTableFullAvl ルーチンに示します。 SearchResult パラメーターには、次のいずれかの値を指定できます。

TableEmptyTree

ツリーが空でした。 NodeOrParent の内容は変更されていません。

TableFoundNode

RtlInsertElementGenericTableFullAvl ルーチンで、Buffer 内のデータと一致するキーを持つテーブル エントリが見つかりました。 NodeOrParent には、一致したエントリへのポインターが含まれています。

TableInsertAsLeft

RtlInsertElementGenericTableFullAvl ルーチンで、Buffer 内のデータと一致するキーを持つテーブル エントリが見つかりませんでした。 RtlInsertElementGenericTableFullAvl が検索したエントリがテーブル内にある場合は、NodeOrParent が指すエントリの左側の子になります。

TableInsertAsRight

RtlInsertElementGenericTableFullAvl ルーチンで、Buffer 内のデータと一致するキーを持つテーブル エントリが見つかりませんでした。 RtlInsertElementGenericTableFullAvl が検索したエントリがテーブル内にある場合は、NodeOrParent が指すエントリの適切な子になります。

[in] SearchResult

テーブル エントリへのポインター。 RtlInsertElementGenericTableFullAvl ルーチンがエントリと一致する場合、NodeOrParent は一致したエントリを指します。 RtlInsertElementGenericTableFullAvl ルーチンが一致するものを見つけられない場合、NodeOrParent は RtlInsertElementGenericTableFullAvl ルーチンが検索していたエントリの親となるエントリを指します。

戻り値

RtlInsertElementGenericTableFullAvl は、新しく挿入されたエントリのユーザー データへのポインター、またはジェネリック テーブルに既に存在する一致するエントリのユーザー データへのポインターを返します。 一致するエントリが見つからないが、 RtlInsertElementGenericTableFullAvl が新しいエントリを挿入できない場合 ( AllocateRoutine が失敗するなど)、 RtlInsertElementGenericTableFullAvl は NULL を返します。

注釈

エントリを挿入するために、RtlInsertElementGenericTableFullAvl は、汎用テーブルが RtlInitializeGenericTableAvl によって初期化されたときに登録された CompareRoutine と AllocateRoutine を呼び出します。 新しいエントリを挿入すると、 RtlInsertElementGenericTableFullAvl によって AVL リンク ツリーが再調整されます。

新しいエントリがテーブルに挿入されると、そのデータが Buffer から新しいエントリにコピーされます。 したがって、 RtlInsertElementGenericTableFullAvl によって返されるポインターが Buffer と等しいことはありません。

呼び出し元の CompareRoutine から GenericEqual が返された場合、 Buffer のデータはジェネリック テーブル内の既存のエントリのデータを複製するものと見なされます。 この場合、 RtlInsertElementGenericTableFullAvl は新しいエントリを追加しません (したがって 、AllocateRoutine は呼び出されません)。ジェネリック テーブルに重複するエントリを含めることはできません。

一致するエントリがジェネリック テーブルに既に存在する場合、 RtlInsertElementGenericTableFullAvl は既存のエントリのデータへのポインターを返し 、NewElement を FALSE に設定 します。

テーブルに一致するエントリが既に存在しない場合、RtlInsertElementGenericTableFullAvl ルーチンは、新しいエントリ (BufferSize) のユーザー データと、新しいエントリに関連付けられているリンクに十分な領域を割り当てます。 したがって、合計バイト数は少なくとも BufferSize + sizeof(BALANCED_LINKS) になります。 呼び出し元は、AllocateRoutineによって割り当てられるメモリの最初の sizeof(BALANCED_LINKS) バイトを使用しないでください。

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

既定では、オペレーティング システムは splay ツリーを使用して汎用テーブルを実装しますが、 RtlInsertElementGenericTableFullAvl ルーチンは Adelson-Velsky/Landis (AVL) ツリーでのみ機能します。 ドライバーでツリーを再生する代わりに AVL ツリーを使用するように汎用テーブル ルーチンを構成するには、 Ntddk.h を含める前に、共通ヘッダー ファイルに次の define ステートメントを挿入します。

#define RTL_USE_AVL_TABLES 0

RTL_USE_AVL_TABLESが定義されていない場合は、汎用テーブル ルーチンの AVL 形式を使用する必要があります。 たとえば、 RtlInsertElementGenericTableFull の代わりに RtlInsertElementGenericTableFullAvl ルーチンを使用します。 RtlInsertElementGenericTableFullAvl の呼び出しでは、呼び出し元はRTL_GENERIC_TABLEではなくRTL_AVL_TABLEテーブル構造を渡す必要があります。

次のいずれかの条件が満たされている場合、 RtlInsertElementGenericTableFullAvl の呼び出し元は IRQL < DISPATCH_LEVELで実行されている必要があります。

• 呼び出し元によって割り当てられたメモリ ( Table または Buffer) はページング可能です。
• 呼び出し元から提供された CompareRoutine または AllocateRoutine には、ページング可能なコードが含まれています。

要件

こちらもご覧ください

RtlDeleteElementGenericTable

RtlInitializeGenericTable