Поделиться через


Метод IWDFDevice::CreateIoQueue (wudfddi.h)

[Предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе начало работы с помощью UMDF.]

Метод CreateIoQueue настраивает очередь ввода-вывода по умолчанию, связанную с устройством, или создает вторичную очередь ввода-вывода для устройства.

Синтаксис

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 и более поздних этот параметр является обязательным для очередей ввода-вывода, использующих последовательный или параллельный метод диспетчеризации. Он является необязательным (может иметь значение NULL) для очередей ввода-вывода, использующих метод диспетчеризации вручную. Для версий UMDF, предшествующих 1.9, этот параметр является обязательным для всех методов диспетчеризации.

[in] bDefaultQueue

Значение BOOL, указывающее, следует ли настроить очередь ввода-вывода по умолчанию или создать вторичную очередь ввода-вывода для устройства. ЗНАЧЕНИЕ TRUE указывает на настройку очереди ввода-вывода по умолчанию; ЗНАЧЕНИЕ FALSE указывает на создание вторичной очереди ввода-вывода.

[in] DispatchType

WDF_IO_QUEUE_DISPATCH_TYPE типизированное значение, указывающее, как драйвер должен получать запросы из очереди ввода-вывода.

[in] bPowerManaged

Значение BOOL, указывающее, управляется ли очередь ввода-вывода. Значение TRUE указывает, что платформа автоматически координирует отправку для очереди ввода-вывода с Plug and Play (PnP) и состоянием питания устройства; Значение FALSE указывает, что автоматическая координация не выполняется.

[in] bAllowZeroLengthRequests

Значение BOOL, указывающее, помещает ли платформа запросы ввода-вывода нулевой длины непосредственно в очередь ввода-вывода для обработки драйвером. Значение TRUE указывает, что драйвер должен получать запросы на чтение и запись с буферами нулевой длины, то есть платформа автоматически помещает эти типы запросов непосредственно в очередь ввода-вывода для драйвера. Значение FALSE указывает, что платформа выполняет запросы ввода-вывода нулевой длины, а не помещает их в очередь ввода-вывода.

[out] ppIoQueue

Указатель на переменную, которая получает указатель на интерфейс IWDFIoQueue для вновь созданного объекта очереди ввода-вывода или объекта очереди ввода-вывода по умолчанию.

Возвращаемое значение

CreateIoQueue возвращает одно из следующих значений:

Код возврата Описание
S_OK
Очередь ввода-вывода успешно создана.
HRESULT_FROM_WIN32(ERROR_BAD_CONFIGURATION)
Очередь ввода-вывода настраивается одним из следующих способов.
  • Параметр DispatchType указывает неуправляемую очередь, и ни один из интерфейсов обратного вызова очереди ввода-вывода, указанных в разделе Примечания, не поддерживается с помощью параметра pCallbackInterface .
  • Параметр DispatchType указывает очередь вручную, а один или несколько интерфейсов обратного вызова очереди ввода-вывода, указанных в разделе Примечания, поддерживаются с помощью параметра pCallbackInterface .
Дополнительные сведения об этих конфигурациях см. в разделе Примечания.
 

CreateIoQueue также может возвращать другие значения HRESULT.

Комментарии

Интерфейс IUnknown , который драйвер предоставляет для параметра pCallbackInterface , может поддерживать несколько функций обратного вызова очереди. Платформа вызывает метод QueryInterface для предоставленного интерфейса IUnknown несколько раз, чтобы получить методы интерфейса, поддерживаемые драйвером. Когда приложения выполняют действия, связанные с методами поддерживаемых интерфейсов (например, запрос на чтение ввода-вывода), платформа вызывает методы (например, метод IQueueCallbackRead::OnRead ) для уведомления драйвера. Платформа вызывает QueryInterface для следующих интерфейсов:

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

Когда драйвер передает WdfIoQueueDispatchSequential или WdfIoQueueDispatchParallel для параметра DispatchTypeCreateIoQueue для создания неуправляемой очереди, CreateIoQueue может вернуть S_OK только в том случае, если объект обратного вызова очереди драйвера реализует по крайней мере один из предыдущих интерфейсов и указывает на поддержку таких интерфейсов через интерфейс IUnknown , на который указывает pCallbackInterface .

Когда драйвер передает WdfIoQueueDispatchManual для DispatchType для создания очереди вручную, CreateIoQueue может вернуть S_OK только в том случае, если объект обратного вызова очереди драйвера не реализует или не указывает на поддержку любого из предыдущих интерфейсов обратного вызова. Дополнительные сведения об объектах обратного вызова драйвера см. в разделе Создание объектов обратного вызова.

Примечание Драйвер не может использовать тот же объект обратного вызова для очереди вручную, который драйвер использует для последовательной или параллельной очереди. То есть, если драйвер передает определенный указатель в интерфейс IUnknown в вызове CreateIoQueue для создания очереди вручную, драйвер не сможет передать идентичный указатель в IUnknown в вызове CreateIoQueue для создания последовательной или параллельной очереди.
 
Дополнительные сведения о настройке режима диспетчеризации см. в разделе Настройка режима диспетчеризации для очереди ввода-вывода.

Платформа также вызывает QueryInterface в предоставленном интерфейсе IUnknown , чтобы определить, поддерживает ли драйвер любой из следующих интерфейсов:

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

Платформа также вызывает QueryInterface в предоставленном интерфейсе IUnknown , чтобы определить, поддерживает ли драйвер интерфейс IQueueCallbackStateChange . Объект обратного вызова очереди драйвера может при необходимости реализовать и указать поддержку IQueueCallbackStateChange только для очереди вручную. Объект обратного вызова очереди драйвера не должен реализовывать и указывать поддержку IQueueCallbackStateChange для последовательной или параллельной очереди.

Примеры

Пример кода использования метода CreateIoQueue см. в разделе IWDFDriver::CreateDevice.

Требования

Требование Значение
Дата окончания поддержки Недоступно в UMDF 2.0 и более поздних версиях.
Целевая платформа Персональный компьютер
Минимальная версия UMDF 1.5
Верхняя часть wudfddi.h (включая Wudfddi.h)
DLL WUDFx.dll

См. также раздел

IObjectCleanup

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IWDFDevice

IWDFIoQueue

WDF_IO_QUEUE_DISPATCH_TYPE