WdfRequestForwardToIoQueue 函数 (wdfrequest.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WdfRequestForwardToIoQueue 方法将 I/O 请求重新排队到调用驱动程序的 I/O 队列之一。

语法

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

参数

[in] Request

框架请求对象的句柄。

[in] DestinationQueue

框架队列对象的句柄。

返回值

如果操作成功，WdfRequestForwardToIoQueue 将返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_INVALID_DEVICE_REQUEST	如果发生以下任一情况，则返回此值：驱动程序未从 I/O 队列获取请求。源队列和目标队列相同。源队列和目标队列不属于同一设备。驱动程序不拥有请求。请求可取消。
STATUS_WDF_BUSY	目标队列不接受新请求。

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

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

注解

驱动程序必须拥有 I/O 请求，并且必须已从其 I/O 队列之一获取请求。

源队列和目标队列不能相同。换句话说，驱动程序无法调用 WdfRequestForwardToIoQueue 将请求返回到它来自的队列。若要将请求重新排队到同一队列，请使用 WdfRequestRequeue。

源队列和目标队列必须属于同一设备。

请求不得取消。如果驱动程序已调用 WdfRequestMarkCancelable 或 WdfRequestMarkCancelableEx 以使请求可取消，则必须在调用 WdfRequestForwardToIoQueue 之前调用 WdfRequestUnmarkCancelable。

在驱动程序调用 WdfRequestForwardToIoQueue 之后，在框架将请求从新队列传递到驱动程序之前，驱动程序不会拥有重新排队的请求。当请求位于新队列中时，框架拥有该请求，并且可以取消它，而无需通知驱动程序。

在 WdfRequestForwardToIoQueue 返回之前，可能发生以下事件：

如果目标队列为空，框架可以将重新排队的 I/O 请求传递给目标队列的请求处理程序之一。
如果源队列的调度方法是顺序或并行的，则框架可以将另一个请求传递给源队列的请求处理程序之一。

有关 WdfRequestForwardToIoQueue 的详细信息，请参阅重新排队 I/O 请求和管理 I/O 队列。

示例

以下代码示例是 PCIDRV 示例驱动程序中的 EvtIoDeviceControl 回调函数。如果收到的请求包含 IOCTL_NDISPROT_INDICATE_STATUS 的 I/O 控制代码，驱动程序会调用 WdfRequestForwardToIoQueue 将请求移到其他 I/O 队列。

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfrequest.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DeferredRequestCompleted (kmdf) 、 DriverCreate (kmdf) 、 InvalidReqAccess (kmdf) 、 InvalidReqAccessLocal () kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf) ， RequestCompleted (kmdf) 、 RequestCompletedLocal (kmdf)