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

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

構文

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

新しい lookaside-list エントリに割り当てるストレージの種類を指定します。 呼び出し元は、このパラメーターを有効な 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

新しいルックアサイド・リスト項目に割り振られた記憶域をマークするために使用する 4 バイト・プール・タグを指定します。 プール タグの詳細については、ExAllocatePoolWithTagTag パラメーターの説明を参照してください。

[in, out] Lookaside

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

戻り値

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

注釈

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

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

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

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

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

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

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

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

たとえば、名前付きの MyLookasideListAllocateExLookasideListAllocateEx コールバック ルーチンを定義するには、次のコード例に示すように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の詳細については、「関数の動作に注釈を付ける」を参照してください。

要件

   
サポートされている最小のクライアント Windows Vista 以降のバージョンの Windows でサポートされています。
対象プラットフォーム デスクトップ
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL 「解説」セクションを参照してください。

こちらもご覧ください

ExAllocateFromLookasideListEx

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTag

ExInitializeLookasideListEx

LOOKASIDE_LIST_EX

POOL_TYPE