WdfRequestReuse 関数 (wdfrequest.h)

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

[KMDF と UMDF に適用]

WdfRequestReuse メソッドは、フレームワーク要求オブジェクトを再初期化して再利用できるようにします。

構文

NTSTATUS WdfRequestReuse(
  [in] WDFREQUEST                Request,
  [in] PWDF_REQUEST_REUSE_PARAMS ReuseParams
);

パラメーター

[in] Request

フレームワーク要求オブジェクトへのハンドル。

[in] ReuseParams

呼び出し元によって割り当てられた WDF_REQUEST_REUSE_PARAMS 構造体へのポインター。

戻り値

操作が成功した場合、WdfRequestReuse はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	入力パラメーターが無効です。
STATUS_WDF_REQUEST_INVALID_STATE	ドライバーは、WDF_REQUEST_REUSE_PARAMS 構造体で IRP を提供しましたが、指定された要求オブジェクトが WdfRequestCreateFromIrp から取得されませんでした。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

フレームワークベースのドライバーは、 WdfRequestCreate または WdfRequestCreateFromIrp の以前の呼び出しによって作成されたフレームワーク要求オブジェクトを再利用できます。ドライバーは、フレームワークから受信した要求オブジェクトを再利用することもできますが、それらの要求オブジェクトの WDF_REQUEST_REUSE_SET_NEW_IRP フラグを設定することはできません。

注意

ドライバーは、フレームワークから受信した要求オブジェクトを再利用する場合は注意が必要です。このような要求を再利用すると、基になる IRP のキャンセルフラグがリセットされ、呼び出し元のドライバーが要求をキャンセルできなくなる可能性があります。

ドライバーは、元の要求が完了した後、要求オブジェクトを再利用できます。ドライバーが WdfRequestReuse を呼び出した後、要求の内容を再初期化する必要があります。ドライバーは、 WDF_REQUEST_REUSE_PARAMS 構造体でいくつかの要求パラメーターを指定できます。

再利用された要求に CompletionRoutine コールバック関数を含める場合、ドライバーは WdfRequestRequestReuse を呼び出した後に WdfRequestSetCompletionRoutine を呼び出す必要があります。

WdfRequestReuse の詳細については、「フレームワーク要求オブジェクトの再利用」を参照してください。

例

次のコード例は、ドライバーがドライバー割り当て要求を再利用できるように WdfRequestReuse を呼び出す CompletionRoutine コールバック関数の一部です。

VOID
MyRequestCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{
    WDF_REQUEST_REUSE_PARAMS  params;
    NTSTATUS  status;
...
    WDF_REQUEST_REUSE_PARAMS_INIT(
                                  &params,
                                  WDF_REQUEST_REUSE_NO_FLAGS,
                                  STATUS_SUCCESS
                                  );

    status = WdfRequestReuse(
                             Request,
                             &params
                             );
    ASSERT(NT_SUCCESS(status));
...
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfrequest.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 InvalidReqAccess(kmdf)、 InvalidReqAccessLocal(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 ReqSendFail(kmdf)