WdfRequestReuse 函式（wdfrequest.h）

發行項
02/07/2025

[適用於 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 回呼函式，驅動程式必須在呼叫 WdfRequestSetCompletionRoutine 之後呼叫 WdfRequestReuse。

如需 WdfRequestReuse的詳細資訊，請參閱重複使用 Framework 要求物件。

例子

下列程式代碼範例是 CompletionRoutine 回呼函式的一部分，該函式會呼叫 WdfRequestReuse，讓驅動程式可以重複使用驅動程式配置的要求。

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
標頭	wdfrequest.h （包括 Wdf.h）
連結庫	Wdf01000.sys （KMDF）：WUDFx02000.dll （UMDF）
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate（kmdf），InvalidReqAccess（kmdf），InvalidReqAccessLocal，KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），ReqSendFail（kmdf）