RtlInsertElementGenericTableAvl 関数 (ntddk.h)

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

構文

NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
  [in]            PRTL_AVL_TABLE Table,
  [in]            PVOID          Buffer,
  [in]            CLONG          BufferSize,
  [out, optional] PBOOLEAN       NewElement
);

パラメーター

[in] Table

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

[in] Buffer

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

[in] BufferSize

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

[out, optional] NewElement

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

戻り値

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

注釈

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

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

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

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

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

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

既定では、オペレーティング システムは splay ツリーを使用して汎用テーブルを実装しますが、 RtlInsertElementGenericTableAvl ルーチンは 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テーブル構造を渡す必要があります。

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

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

要件

こちらもご覧ください

RtlDeleteElementGenericTableAvl

RtlInitializeGenericTableAvl