WdfIoQueueCreate function (wdfio.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfIoQueueCreate method creates and configures an I/O queue for a specified device.

Syntax

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

Parameters

[in] Device

A handle to the framework device object that the queue will be associated with.

[in] Config

A pointer to a caller-allocated WDF_IO_QUEUE_CONFIG structure.

[in, optional] QueueAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the new object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Queue

A pointer to a location that receives a handle to a framework queue object.

Return value

WdfIoQueueCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter is invalid.
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_IO_QUEUE_CONFIG structure is incorrect.
STATUS_POWER_STATE_INVALID	The framework is performing a power management operation.
STATUS_INSUFFICIENT_RESOURCES	The amount of available memory is too low.
STATUS_WDF_NO_CALLBACK	The WDF_IO_QUEUE_CONFIG structure does not specify any request handlers, and the dispatching method is not WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	The driver is attempting to create a default queue while a default queue already exists for the device, or an internal error occurred.

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

Each call to WdfIoQueueCreate creates an I/O queue for a device. Your driver can create multiple I/O queues for each device.

The Config and QueueAttributes parameters specify the queue's configuration and object attributes.

By default, the framework device object that the Device parameter specifies becomes the parent object for the new framework queue object. If the driver specifies a parent object in the WDF_OBJECT_ATTRIBUTES structure's ParentObject member, the parent object can be a framework device object or any object whose chain of parents leads to a framework device object. The framework will delete the queue object when it deletes the parent object.

If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the framework queue object, the framework calls these callback functions at IRQL = PASSIVE_LEVEL.

For more information about WdfIoQueueCreate, see Creating I/O Queues.

Examples

The following code example is the section of an EvtDriverDeviceAdd callback function that creates a device's default I/O queue. The example initializes a WDF_IO_QUEUE_CONFIG structure and then calls 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;
    }
...
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfio.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via