WdfRequestCreateFromIrp 函数 (wdfrequest.h)

项目
08/08/2023

[仅适用于 KMDF]

WdfRequestCreateFromIrp 方法从指定的 WDM IRP 创建框架请求对象。

语法

NTSTATUS WdfRequestCreateFromIrp(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in]           PIRP                   Irp,
  [in]           BOOLEAN                RequestFreesIrp,
  [out]          WDFREQUEST             *Request
);

参数

[in, optional] RequestAttributes

指向调用方分配的WDF_OBJECT_ATTRIBUTES 结构的指针，该结构指定请求对象的对象属性。此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[in] Irp

指向包含 WDM I/O 请求数据包的 IRP 结构的指针。

[in] RequestFreesIrp

一个布尔值，如果 为 TRUE，则指示框架在销毁请求句柄时删除 IRP。如果 为 FALSE，驱动程序必须使用以下示例部分演示的步骤调用 IoFreeIrp 以删除 IRP。

[out] Request

指向接收框架请求对象的句柄的位置的指针。

返回值

如果操作成功，WdfRequestCreateFromIrp 将返回STATUS_SUCCESS。有关其他返回值的列表，请参阅框架对象创建错误。

此方法还可能返回其他 NTSTATUS 值。

注解

通常，仅当基于框架的驱动程序在 WDM 调度例程中收到 WDM IRP，然后将请求转发到框架 I/O 目标时，才调用 WdfRequestCreateFromIrp 。

如果驱动程序调用 WdfRequestCreateFromIrp 来创建请求对象，则它不得为请求对象调用 WdfRequestComplete 。相反，驱动程序必须在使用完请求对象后调用 WdfObjectDelete 。

此外，驱动程序不得使用新的请求对象调用 WdfRequestRetrieveOutputMemory、 WdfRequestRetrieveOutputBuffer、 WdfRequestRetrieveInputBuffer 或 WdfRequestRetrieveInputMemory 。

默认情况下，新请求对象的父对象是 WdfDriverCreate 方法创建的框架驱动程序对象。可以使用 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员来指定不同的父级。框架在删除父对象时删除请求对象。如果驱动程序未更改默认父级，则驱动程序应在请求对象使用完对象后删除该对象;否则，请求对象将一直保留，直到 I/O 管理器卸载驱动程序。

有关创建框架请求对象的详细信息，请参阅创建框架请求对象。

基于框架的驱动程序不得使用 IRP 结构的 Tail.Overlay.DriverContext 成员，因为框架使用此成员。

示例

示例 1

下面的代码示例从指定的 WDM IRP 创建框架请求对象，然后将其删除。此示例将 RequestFreesIrp 参数设置为 TRUE，因此框架在销毁请求句柄时删除 IRP。

WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 TRUE,
                                 &request
                                 );
...
//Deletion
WdfObjectDelete(request);

示例 2

下面的代码示例还从指定的 WDM IRP 创建框架请求对象，然后将其删除。此示例将 RequestFreesIrp 参数设置为 FALSE，因此驱动程序必须调用 IoFreeIrp 才能删除 IRP。需要此示例中的所有函数调用。

WDF_REQUEST_REUSE_PARAMS params;
WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 FALSE,
                                 &request
                                 );
...
//Deletion
WDF_REQUEST_REUSE_PARAMS_INIT(
                              &params,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_SUCCESS
                              );
WDF_REQUEST_REUSE_PARAMS_SET_NEW_IRP(
                                     &params,
                                     NULL
                                     );
status = WdfRequestReuse(
                         request,
                         &params
                         );
ASSERT(NT_SUCCESS(status));
IoFreeIrp(irp);
WdfObjectDelete(request);

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
标头	wdfrequest.h (包括 Wdf.h)
Library	Wdf01000.sys (请参阅框架库版本控制.)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)