Функция WdfIoQueueCreate (wdfio.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfIoQueueCreate создает и настраивает очередь ввода-вывода для указанного устройства.

Синтаксис

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.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

По умолчанию объект устройства платформы, указываемый параметром Device , становится родительским объектом для нового объекта очереди платформы. Если драйвер указывает родительский объект в элементе ParentObjectструктуры WDF_OBJECT_ATTRIBUTES, родительским объектом может быть объект устройства платформы или любой объект, цепочка родителей которого приводит к объекту устройства платформы. Платформа удалит объект очереди при удалении родительского объекта.

Если драйвер предоставляет функции обратного вызова EvtCleanupCallback или EvtDegradCallback для объекта очереди платформы, платформа вызывает эти функции обратного вызова в IRQL = PASSIVE_LEVEL.

Дополнительные сведения о WdfIoQueueCreate см. в разделе Создание очередей ввода-вывода.

Примеры

В следующем примере кода показан раздел функции обратного вызова EvtDriverDeviceAdd , которая создает очередь ввода-вывода устройства по умолчанию. В примере инициализируется структура 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)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)