WdfIoQueueCreate method

[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

Device [in]

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

Config [in]

A pointer to a caller-allocated WDF_IO_QUEUE_CONFIG structure.

QueueAttributes [in, optional]

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.

Queue [out, optional]

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 codeDescription
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

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, DriverCreate, DrvAckIoStop, KmdfIrql, KmdfIrql2

See also

WdfRequestForwardToIoQueue
WdfDeviceConfigureRequestDispatching
WDF_IO_QUEUE_CONFIG
WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE
WDF_OBJECT_ATTRIBUTES

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft