IWDFDevice：：CreateIoQueue 方法 (wudfddi.h)

项目
03/05/2024

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅使用 UMDF 入门。]

CreateIoQueue 方法配置与设备关联的默认 I/O 队列，或为设备创建辅助 I/O 队列。

语法

HRESULT CreateIoQueue(
  [in, optional] IUnknown                   *pCallbackInterface,
  [in]           BOOL                       bDefaultQueue,
  [in]           WDF_IO_QUEUE_DISPATCH_TYPE DispatchType,
  [in]           BOOL                       bPowerManaged,
  [in]           BOOL                       bAllowZeroLengthRequests,
  [out]          IWDFIoQueue                **ppIoQueue
);

参数

[in, optional] pCallbackInterface

指向 IUnknown 接口的指针，框架使用该接口来确定驱动程序在队列上订阅的事件回调函数。这些是发生相关事件时框架调用的函数。

对于 UMDF 版本 1.9 及更高版本，此参数对于使用顺序或并行调度方法的 I/O 队列是必需的，并且对于使用手动调度方法的 I/O 队列，此参数是可选的 (可以为 NULL) 。对于低于 1.9 的 UMDF 版本，所有调度方法都需要此参数。

[in] bDefaultQueue

一个 BOOL 值，该值指定是为设备配置默认 I/O 队列还是创建辅助 I/O 队列。 TRUE 指示配置默认 I/O 队列; FALSE 指示创建辅助 I/O 队列。

[in] DispatchType

一个WDF_IO_QUEUE_DISPATCH_TYPE类型的值，该值标识驱动程序必须如何从 I/O 队列接收请求。

[in] bPowerManaged

一个 BOOL 值，该值指定 I/O 队列是否受电源管理。 TRUE 表示框架使用即插即用 (PnP) 和设备的电源状态自动协调 I/O 队列的调度;FALSE 表示没有自动协调调度。

[in] bAllowZeroLengthRequests

一个 BOOL 值，该值指定框架是否将零长度的 I/O 请求直接放在 I/O 队列中供驱动程序处理。 TRUE 指示驱动程序应接收具有零长度缓冲区的读取和写入请求，也就是说，框架会自动将这些请求类型直接放入驱动程序的 I/O 队列中。 FALSE 指示框架完成长度为零的 I/O 请求，而不是将它们置于 I/O 队列中。

[out] ppIoQueue

指向变量的指针，该变量接收指向新创建的 I/O 队列对象或默认 I/O 队列对象的 IWDFIoQueue 接口的指针。

返回值

CreateIoQueue 返回以下值之一：

返回代码	说明
S_OK	已成功创建 I/O 队列。
HRESULT_FROM_WIN32 (ERROR_BAD_CONFIGURATION)	I/O 队列按以下方式之一进行配置： DispatchType 参数指定一个非操作队列，并且通过 pCallbackInterface 参数不支持在“备注”部分指定的 I/O 队列回调接口。 DispatchType 参数指定一个手动队列，并且通过 pCallbackInterface 参数支持在“备注”部分中指定的一个或多个 I/O 队列回调接口。有关这些配置的详细信息，请参阅“备注”部分。

返回代码

说明

S_OK

已成功创建 I/O 队列。

HRESULT_FROM_WIN32 (ERROR_BAD_CONFIGURATION)

I/O 队列按以下方式之一进行配置：

DispatchType 参数指定一个非操作队列，并且通过 pCallbackInterface 参数不支持在“备注”部分指定的 I/O 队列回调接口。
DispatchType 参数指定一个手动队列，并且通过 pCallbackInterface 参数支持在“备注”部分中指定的一个或多个 I/O 队列回调接口。

有关这些配置的详细信息，请参阅“备注”部分。

CreateIoQueue 也可能返回其他 HRESULT 值。

注解

驱动程序为 pCallbackInterface 参数提供的 IUnknown 接口可以支持多个队列回调函数。框架在提供的 IUnknown 接口上多次调用 QueryInterface 方法，以检索驱动程序支持的接口方法。当应用程序执行与受支持接口的方法相关的操作时， (例如 I/O 读取请求) ，框架将调用方法 (如 IQueueCallbackRead：：OnRead 方法) 通知驱动程序。框架为以下接口调用 QueryInterface ：

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

当驱动程序传递 CreateIoQueue 的 DispatchType 参数的 WdfIoQueueDispatchSequential 或 WdfIoQueueDispatchParallel 以创建非手动队列时，仅当驱动程序的队列回调对象实现至少一个上述接口并通过 pCallbackInterface 指向的 IUnknown 接口指示支持此类接口时，CreateIoQueue 才能返回S_OK。

当驱动程序传递 WdfIoQueueDispatchManual for DispatchType 创建手动队列时，仅当驱动程序的队列回调对象未实现或指示支持上述任何回调接口时， CreateIoQueue 才能返回S_OK。有关驱动程序的回调对象的详细信息，请参阅创建回调对象。

注意驱动程序不能对手动队列使用与驱动程序用于顺序或并行队列的同一回调对象。也就是说，如果驱动程序在调用 CreateIoQueue 以创建手动队列时将特定指针传递到 IUnknown 接口，则驱动程序以后无法在调用 CreateIoQueue 时将相同的指针传递到 IUnknown，以创建顺序或并行队列。

有关配置调度模式的详细信息，请参阅为 I/O 队列配置调度模式。

框架还在提供的 IUnknown 接口上调用 QueryInterface，以确定驱动程序是否支持以下任何接口：

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

框架还在提供的 IUnknown 接口上调用 QueryInterface，以确定驱动程序是否支持 IQueueCallbackStateChange 接口。驱动程序的队列回调对象可以选择实现并指示仅对手动队列支持 IQueueCallbackStateChange 。驱动程序的队列回调对象不得实现并指示对顺序或并行队列的 IQueueCallbackStateChange 的支持。

示例

有关如何使用 CreateIoQueue 方法的代码示例，请参阅 IWDFDriver：：CreateDevice。

要求

要求	值
结束支持	在 UMDF 2.0 及更高版本中不可用。
目标平台	桌面
最低 UMDF 版本	1.5
标头	wudfddi.h (包括 Wudfddi.h)
DLL	WUDFx.dll