WdfDeviceEnqueueRequest 函数 (wdfdevice.h)

  • 项目

[仅适用于 KMDF]

WdfDeviceEnqueueRequest 方法将指定的 I/O 请求传递给框架，以便框架随后可以将请求添加到驱动程序为指定设备创建的 I/O 队列之一。

语法

NTSTATUS WdfDeviceEnqueueRequest(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request
);

参数

[in] Device

框架设备对象的句柄。

[in] Request

框架请求对象的句柄。

返回值

如果操作成功，该方法将返回STATUS_SUCCESS。 其他返回值包括：

返回代码 说明
STATUS_INSUFFICIENT_RESOURCES
 可用内存量较低。
STATUS_INVALID_DEVICE_REQUEST
 驱动程序尚未为设备创建任何 I/O 队列，并且驱动程序不是筛选器驱动程序。
STATUS_WDF_BUSY
 设备的 I/O 队列不接受请求。
 

该方法可能会返回其他 NTSTATUS 值。

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

注解

驱动程序只能从 EvtIoInCallerContext 回调函数调用 WdfDeviceEnqueueRequest。

WdfDeviceEnqueueRequest 方法将请求添加到驱动程序针对设备的特定于请求类型的 I/O 队列（如果驱动程序已创建）。 否则， 方法会将请求添加到设备的默认队列（如果驱动程序已创建一个队列）。

如果驱动程序尚未为设备创建任何 I/O 队列， 则 WdfDeviceEnqueueRequest 将执行以下操作：

  • 如果驱动程序是筛选器驱动程序， 则 WdfDeviceEnqueueRequest 会将请求发送到驱动程序的 I/O 目标。
  • 如果驱动程序不是筛选器驱动程序， 则 WdfDeviceEnqueueRequest 返回STATUS_INVALID_DEVICE_REQUEST。
执行 WdfDeviceEnqueueRequest 时，驱动程序可能会接收并完成或取消请求。

因此，如果驱动程序在调用 WdfDeviceEnqueueRequest 后需要使用请求或其上下文，则应在调用 WdfDeviceEnqueueRequest 之前对请求进行引用。

为此，驱动程序可以在调用 WdfDeviceEnqueueRequest 之前调用 WdfObjectReference，然后在调用 WdfDeviceEnqueueRequest 之后调用 WdfObjectDereference。 在退出 EvtIoInCallerContext 之前，驱动程序必须取消引用请求。

有关 WdfDeviceEnqueueRequest 方法的详细信息，请参阅 管理 I/O 队列。

对于 1.0 和 1.5 版 KMDF，必须在 PASSIVE_LEVEL 调用 WdfDeviceEnqueueRequest 。 对于版本 1.7 及更高版本，可以在 IRQL <= DISPATCH_LEVEL 调用 WdfDeviceEnqueueRequest。

示例

下面的代码示例是一个 EvtIoInCallerContext 回调函数，该函数查找包含自定义 I/O 控件代码的请求，IOCTL_NONPNP_METHOD_NEITHER。 如果未找到 I/O 控制代码，回调函数将请求返回给框架。 如果回调函数找到 I/O 控制代码，它会预处理请求，然后将其返回到框架。 如果遇到错误，回调函数将完成请求。

VOID
MyEvtDeviceIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    WDF_REQUEST_PARAMETERS  params;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );
    if(!(params.Type == WdfRequestTypeDeviceControl &&
         params.Parameters.DeviceIoControl.IoControlCode == IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if(!NT_SUCCESS(status)) {
            goto End;
        }
        return;
    }
    //
    // Found a match for the control code. Preprocess the request, and then
    // return the request to the framework.
    //

    //...(Preprocess the request here.)

    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;
End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
标头 wdfdevice.h (包括 Wdf.h)
Library Wdf01000.sys (请参阅框架库 Versioning.)
IRQL <= DISPATCH_LEVEL (请参阅备注部分)
DDI 符合性规则 DeferredRequestCompleted (kmdf) 、 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf) ， RequestCompleted (kmdf) ， RequestCompletedLocal (kmdf)

另请参阅

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters