WdfRequestForwardToParentDeviceIoQueue 函数 (wdfrequest.h)

[仅适用于 KMDF]

WdfRequestForwardToParentDeviceIoQueue 方法将子设备的 I/O 队列中的 I/O 请求重新排队到子设备的指定 I/O 队列。

语法

NTSTATUS WdfRequestForwardToParentDeviceIoQueue(
  [in] WDFREQUEST                   Request,
  [in] WDFQUEUE                     ParentDeviceQueue,
  [in] PWDF_REQUEST_FORWARD_OPTIONS ForwardOptions
);

参数

[in] Request

框架请求对象的句柄。

[in] ParentDeviceQueue

框架队列对象的句柄。

[in] ForwardOptions

指向调用方分配 WDF_REQUEST_FORWARD_OPTIONS 结构的指针。

返回值

如果作成功,WdfRequestForwardToParentDeviceIoQueue 返回STATUS_SUCCESS。 否则,此方法可能会返回以下值之一:

返回代码 描述
STATUS_INFO_LENGTH_MISMATCH
提供的WDF_REQUEST_FORWARD_OPTIONS结构的大小无效。
STATUS_INVALID_PARAMETER
提供的WDF_REQUEST_FORWARD_OPTIONS结构的成员包含无效值。
STATUS_INVALID_DEVICE_REQUEST
如果出现以下情况之一,则返回此值:
  • 驱动程序未从 I/O 队列获取 I/O 请求。
  • 源队列和目标 I/O 队列相同。
  • 指定的 I/O 队列不属于父设备。
  • 驱动程序已启用 保证向前进度,并且指定的 I/O 请求保留为低内存情况。
  • 驱动程序未调用 WdfPdoInitAllowForwardingRequestToParent
STATUS_WDF_BUSY
指定的 I/O 队列不接受新请求。
 

此方法也可能返回其他 NTSTATUS 值

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

言论

在驱动程序调用 WdfRequestForwardToParentDeviceIoQueue之前,它必须调用 WdfPdoInitAllowForwardingRequestToParent

驱动程序必须使用同一 方法来访问父设备和子设备的数据缓冲区(缓冲、直接或两者都没有)。

如果驱动程序将调用 WdfRequestForwardToParentDeviceIoQueue 以重新排队 I/O 请求,驱动程序不得将请求对象用作其他框架对象的父对象,例如计时器对象或工作项对象。

如果驱动程序已调用 WdfDeviceInitSetRequestAttributes 设备的请求对象指定 上下文空间,框架不会添加此上下文空间来请求驱动程序在子设备队列中接收的对象。 驱动程序可以调用 WdfObjectAllocateContext 在驱动程序调用 WdfRequestForwardToParentDeviceIoQueue之前将上下文空间添加到请求对象。 另一方面,如果驱动程序为 设备的请求对象 WdfDeviceInitSetRequestAttributes,并且父设备的请求对象使用与子设备的上下文空间相等或小于的上下文空间,驱动程序可以使用请求对象的上下文空间,而无需调用 WdfObjectAllocateContext

目前,驱动程序必须使用 发送和忘记选项 所有重新排队的 I/O 请求。 因此,请注意,在框架删除重新排队的请求对象时,它可能已经删除了最初接收请求对象的子设备。 因此,驱动程序不得使用重新排队的请求对象的 EvtCleanupCallbackEvtDestroyCallback 函数来访问子设备资源,因为在运行 EvtCleanupCallbackEvtDestroyCallback 函数之前,可能会删除这些资源。

有关 WdfRequestForwardToParentDeviceIoQueue的详细信息,请参阅 重新排队 I/O 请求

例子

下面的代码示例首先确定接收 I/O 请求的设备的父设备,然后将 I/O 请求重新排队到父设备的默认 I/O 队列。

WDFDEVICE device, parentDevice;
WDF_REQUEST_FORWARD_OPTIONS forwardOptions;
NTSTATUS status;

device = WdfIoQueueGetDevice(WdfRequestGetIoQueue(Request));
parentDevice = WdfPdoGetParent(device);

WDF_REQUEST_FORWARD_OPTIONS_INIT(&forwardOptions);
status = WdfRequestForwardToParentDeviceIoQueue(
             Request,
             WdfDeviceGetDefaultQueue(parentDevice),
             &forwardOptions
             );
if (!NT_SUCCESS(status)) {
    WdfRequestComplete(
                       Request,
                       status
                       );
  }

要求

要求 价值
目标平台 普遍
最低 KMDF 版本 1.9
标头 wdfrequest.h (包括 Wdf.h)
Wdf01000.sys(请参阅框架库版本控制。
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate(kmdf)

另请参阅

WdfPdoInitAllowForwardingRequestToParent