ALLOCATE_FUNCTION_EX コールバック関数 (wdm.h)

[アーティクル]
02/29/2024

LookasideListAllocateEx ルーチンは、クライアントが空のルックアサイドリストからエントリを要求すると、新しいルックアサイドリストエントリにストレージを割り当てます。

構文

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

パラメーター

[in] PoolType

新しいルックアサイドリストエントリに割り当てるストレージの種類を指定します。呼び出し元は、このパラメーターを有効な POOL_TYPE 列挙値に設定し、次のいずれかのフラグビットを使用して、この値をビットごとの OR に設定します。

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

POOL_RAISE_IF_ALLOCATION_FAILURE フラグの詳細については、「 ExAllocatePoolWithTag」を参照してください。 POOL_QUOTA_FAIL_INSTEAD_OF_RAISE フラグの詳細については、「 ExAllocatePoolWithQuotaTag」を参照してください。

ルックアサイドリストを初期化した ExInitializeLookasideListEx 呼び出しで Flags パラメーターが 0 の場合、LookasideListAllocateEx ルーチンが受け取る PoolType パラメーターは、ExInitializeLookasideListEx に渡されたのと同じ PoolType パラメーター値になります。

ExInitializeLookasideListEx 呼び出しで Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAILの場合、LookasideListAllocateEx ルーチンが受け取る PoolType パラメーターは、POOL_RAISE_IF_ALLOCATION_FAILUREのビットごとの OR と、ExInitializeLookasideListEx に渡された PoolType パラメーター値です。 LookasideListAllocateEx ルーチンは、変更せずに PoolType パラメーター値を ExAllocatePoolWithTag ルーチンに渡すことができます。

ExInitializeLookasideListEx 呼び出しで Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISEの場合、LookasideListAllocateEx ルーチンが受け取る PoolType パラメーターは、POOL_QUOTA_FAIL_INSTEAD_OF_RAISEのビットごとの OR と、ExInitializeLookasideListEx に渡された PoolType 値です。 LookasideListAllocateEx ルーチンは、変更せずに PoolType パラメーター値を ExAllocatePoolWithQuotaTag ルーチンに渡すことができます。

[in] NumberOfBytes

割り当てる lookaside-list エントリのサイズをバイト単位で指定します。

[in] Tag

新しい lookaside-list エントリに割り当てられた記憶域をマークするために使用する 4 バイトプールタグを指定します。プールタグの詳細については、ExAllocatePoolWithTag の Tag パラメーターの説明を参照してください。

[in, out] Lookaside

ルックアサイドリストを記述する LOOKASIDE_LIST_EX 構造体へのポインター。この構造体は、以前は ExInitializeLookasideListEx ルーチンによって初期化されていました。

戻り値

LookasideListAllocateEx は 、割り当てられた lookaside-list エントリへのポインターを返します。ルーチンがエントリを割り当てることができない場合は、 NULL を返します。

注釈

ルックアサイドリストを作成するドライバーは、 LookasideListAllocateEx ルーチンを実装して、リストのバッファーを動的に割り当てることができます。使用されていないバッファーは、一覧のエントリとして格納されます。ルックアサイドリスト内のすべてのエントリは、一覧が初期化されたときにドライバーが指定する、均一なサイズのバッファーです。

ドライバーは、ルックアサイドリストを初期化する ExInitializeLookasideListEx 呼び出しの入力パラメーターとして、カスタム LookasideListAllocateEx ルーチンへのポインターを提供します。ドライバーがこのパラメーターを NULL に設定した場合、ルックアサイドリストでは代わりに既定の割り当てルーチンが使用されます。

ドライバーは ExAllocateFromLookasideListEx ルーチンを呼び出して、ルックアサイドリストからエントリを割り当てます。リストが空の場合 (エントリが含まれません)、 ExAllocateFromLookasideListEx はLookasideListAllocateEx を呼び出して、新しいエントリのストレージを動的に割り当てます。 LookasideListAllocateEx は、割り当てが成功した場合、新しく割り当てられたエントリへのポインターを返します。それ以外の場合は NULL を返します。

PoolType、NumberOfBytes、Tag、Lookaside の各パラメーターには、ルックアサイドリストを初期化した ExInitializeLookasideListEx 呼び出しで入力パラメーターとして渡されたのと同じ値が含まれます。

LookasideListAllocateEx ルーチンでは、Lookaside パラメーターを使用して、ドライバーがルックアサイドリストに関連付けているプライベートコンテキストデータにアクセスできます。詳細については、「 ExInitializeLookasideListEx」のコード例を参照してください。

ルックアサイドリストの詳細については、「Lookaside Listsの使用」を参照してください。

LookasideListAllocateEx ルーチンは、エントリを要求する ExAllocateFromLookasideListEx の呼び出しと同じ IRQL で呼び出されます。ページメモリに存在するエントリを要求する呼び出しの場合、呼び出し元は IRQL <= APC_LEVELを実行している必要があります。非ページメモリに存在するエントリを要求する呼び出しの場合、呼び出し元は IRQL <= DISPATCH_LEVELを実行している必要があります。

例

LookasideListAllocateEx コールバックルーチンを定義するには、まず、定義するコールバックルーチンの種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。コールバック関数の種類を使用して関数を宣言すると、ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析でエラーが検出され、Windows オペレーティングシステム用のドライバーを記述するための要件になります。

たとえば、という名前MyLookasideListAllocateExの LookasideListAllocateEx コールバックルーチンを定義するには、次のコード例に示すように、FREE_FUNCTION_EX型を使用します。

FREE_FUNCTION_EX MyLookasideListFreeEx;

次に、コールバックルーチンを次のように実装します。

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

FREE_FUNCTION_EX関数の種類は、Wdm.h ヘッダーファイルで定義されます。コード分析ツールを実行するときにエラーをより正確に識別するには、必ず注釈を _Use_decl_annotations_ 関数定義に追加してください。注釈により _Use_decl_annotations_ 、ヘッダーファイル内のFREE_FUNCTION_EX関数型に適用される注釈が確実に使用されます。関数宣言の要件の詳細については、「 WDM ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。の詳細 _Use_decl_annotations_については、「関数の動作に注釈を付ける」を参照してください。

要件

要件	値
対象プラットフォーム	デスクトップ
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	「解説」を参照してください。