WdfRequestReuse 函式 (wdfrequest.h)

發行項
03/01/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。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
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));
...
}

規格需求

需求	值
目標平台	Universal
最低 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 (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) ， ReqSendFail (kmdf)