EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST コールバック関数 (wdfio.h)

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

[KMDF にのみ適用]

ドライバーの EvtIoAllocateResourcesForReservedRequest コールバック関数は、ドライバーが将来 I/O 要求を処理するために使用できる要求固有のリソースを割り当てます。フレームワークは、メモリ不足の状況で将来使用するために、指定された要求オブジェクトを事前に割り当て中です。

構文

EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST EvtWdfIoAllocateResourcesForReservedRequest;

NTSTATUS EvtWdfIoAllocateResourcesForReservedRequest(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

パラメーター

[in] Queue

I/O キューオブジェクトへのハンドル。

[in] Request

将来のメモリ不足の状況で使用するためにフレームワークによって作成された要求オブジェクトへのハンドル。

戻り値

EvtIoAllocateResourcesForReservedRequest コールバック関数は、関数でエラーが発生しない場合、NT_SUCCESS(status) が TRUE であるSTATUS_SUCCESSまたは別の状態値を返す必要があります。それ以外の場合、この関数は、NT_SUCCESS(status) が FALSE である状態値を返す必要があります。

注釈

ドライバーは、WdfIoQueueAssignForwardProgressPolicy を呼び出すときに、EvtIoAllocateResourcesForReservedRequest コールバック関数を登録できます。

ドライバーが EvtIoAllocateResourcesForReservedRequest コールバック関数を登録する場合、フレームワークはメモリ不足の状況に備えて予約する要求オブジェクトを作成した直後に関数を呼び出します。

コールバック関数は、メモリ不足の状況が原因で予約済み要求をフレームワークが使用する場合に、ドライバーが後で要求を処理するために必要なリソースを割り当てることができます。

要求固有のリソースにメモリを割り当てるには、 EvtIoAllocateResourcesForReservedRequest コールバック関数が WdfObjectAllocateContext を呼び出し、 Request パラメーターが指定する要求オブジェクトハンドルを指定する場合があります。

または、ドライバーは WdfDeviceCreate を呼び出す前に WdfDeviceInitSetRequestAttributes を呼び出す場合もあります。その結果、フレームワークは、オブジェクトの作成時に予約済み要求オブジェクトごとにコンテキスト領域を割り当てます。

ドライバーが予約済み要求オブジェクトのオブジェクトコンテキスト領域を割り当てる場合、ドライバーは、予約された要求オブジェクトを使用する I/O 要求を完了するときに、コンテキスト領域を再初期化する必要があります。フレームワークは、使用後に予約済み要求オブジェクトのコンテキスト領域を再初期化しません。

ドライバーが WdfDeviceInitSetRequestAttributes を呼び出し、その要求オブジェクトに対して EvtCleanupCallback または EvtDestroyCallback コールバック関数を指定する場合、フレームワークは、関連付けられた I/O キューを削除した場合にのみ、予約済み要求オブジェクトに対してこれらのコールバック関数を呼び出します。

ドライバーの要求ハンドラーは WdfRequestIsReserved を呼び出して、予約済み要求オブジェクトが使用されているかどうかを判断できます。

オブジェクトコンテキスト空間の使用方法の詳細については、「 Framework オブジェクトコンテキスト空間」を参照してください。

コールバック関数がリソースを正常に割り当てた場合は、STATUS_SUCCESSを返す必要があります。

メモリ不足などのリソース割り当てエラーが発生した場合、コールバック関数はエラー状態の値を返す必要があります。この場合、フレームワークは予約済み要求オブジェクトの割り当てを停止し、コールバック関数の戻り値を WdfIoQueueAssignForwardProgressPolicy の戻り値として使用します。

EvtIoAllocateResourcesForReservedRequest コールバック関数の詳細については、「I/O 操作の前方進行状況の保証」を参照してください。