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获取指定的请求对象。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

言论

基于框架的驱动程序可以重复使用之前调用 WdfRequestCreate 或 WdfRequestCreateFromIrp创建的框架请求对象。驱动程序还可以重复使用从框架接收的请求对象，但无法为这些请求对象设置 WDF_REQUEST_REUSE_SET_NEW_IRP 标志。

注意

在重用从框架接收的请求对象时，驱动程序应谨慎使用。重用此类请求会重置基础 IRP 的取消标志，并可能阻止调用驱动程序取消请求。

驱动程序可以在原始请求完成后重复使用请求对象。在驱动程序调用 WdfRequestReuse后，必须重新初始化请求的内容。驱动程序可以在 WDF_REQUEST_REUSE_PARAMS 结构中指定一些请求参数。

如果希望重复使用的请求具有 CompletionRoutine 回调函数，驱动程序必须在调用 WdfRequestReuse后调用 WdfRequestSetCompletionRoutine。

有关 WdfRequestReuse的详细信息，请参阅重用框架请求对象。

例子

下面的代码示例是 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）