WdfRequestReuse 函数 (wdfrequest.h)

项目
08/08/2023

[适用于 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)
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)