WdfIoQueueCreate 函数 (wdfio.h)

项目
02/27/2024

[适用于 KMDF 和 UMDF]

WdfIoQueueCreate 方法为指定设备创建和配置 I/O 队列。

语法

NTSTATUS WdfIoQueueCreate(
  [in]            WDFDEVICE              Device,
  [in]            PWDF_IO_QUEUE_CONFIG   Config,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES QueueAttributes,
  [out, optional] WDFQUEUE               *Queue
);

参数

[in] Device

队列将与之关联的框架设备对象的句柄。

[in] Config

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

[in, optional] QueueAttributes

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

[out, optional] Queue

指向接收框架队列对象的句柄的位置的指针。

返回值

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

返回代码	说明
STATUS_INVALID_PARAMETER	输入参数无效。
STATUS_INFO_LENGTH_MISMATCH	WDF_IO_QUEUE_CONFIG 结构的大小不正确。
STATUS_POWER_STATE_INVALID	框架正在执行电源管理操作。
STATUS_INSUFFICIENT_RESOURCES	可用内存量太低。
STATUS_WDF_NO_CALLBACK	WDF_IO_QUEUE_CONFIG 结构未指定任何请求处理程序，并且调度方法不是 WdfIoQueueDispatchManual。
STATUS_UNSUCCESSFUL	驱动程序正在尝试创建默认队列，而设备已存在默认队列，或发生内部错误。

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

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

注解

每次调用 WdfIoQueueCreate 都会为设备创建 I/O 队列。驱动程序可以为每个设备创建多个 I/O 队列。

Config 和 QueueAttributes 参数指定队列的配置和对象属性。

默认情况下， Device 参数指定的框架设备对象将成为新框架队列对象的父对象。如果驱动程序在 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员中指定父对象，则父对象可以是框架设备对象或其父级链导致框架设备对象的任何对象。框架在删除父对象时将删除队列对象。

如果驱动程序为框架队列对象提供 EvtCleanupCallback 或 EvtDestroyCallback 回调函数，框架会在 IRQL = PASSIVE_LEVEL调用这些回调函数。

有关 WdfIoQueueCreate 的详细信息，请参阅创建 I/O 队列。

示例

下面的代码示例是 EvtDriverDeviceAdd 回调函数的部分，用于创建设备的默认 I/O 队列。该示例初始化 WDF_IO_QUEUE_CONFIG 结构，然后调用 WdfIoQueueCreate。

NTSTATUS
MyEvtDriverDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_IO_QUEUE_CONFIG  ioQueueConfig;
    WDFQUEUE  hQueue;
...
    WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(
                                           &ioQueueConfig,
                                           WdfIoQueueDispatchSequential
                                           );

    ioQueueConfig.EvtIoDefault = MyEvtIoDefault;

    status = WdfIoQueueCreate(
                              device,
                              &ioQueueConfig,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &hQueue
                              );
    if (!NT_SUCCESS (status)) {
        return status;
    }
...
}

要求

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