nf-wdfio-wdfioqueuecreate.md

UID	title	description	old-location	tech.root	ms.date	keywords	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	f1_keywords	topic_type	api_type	api_location	api_name
NF:wdfio.WdfIoQueueCreate	WdfIoQueueCreate function (wdfio.h)	The WdfIoQueueCreate method creates and configures an I/O queue for a specified device.	wdf\wdfioqueuecreate.htm	wdf	02/26/2018	WdfIoQueueCreate function	DFQueueObjectRef_97b06453-cf79-4944-85d7-530b83211353.xml, WdfIoQueueCreate, WdfIoQueueCreate method, kmdf.wdfioqueuecreate, wdf.wdfioqueuecreate, wdfio/WdfIoQueueCreate	wdfio.h	Wdf.h	Universal			1.0	2.0	ChangeQueueState, DriverCreate, DrvAckIoStop, KmdfIrql, KmdfIrql2							Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)		<= DISPATCH_LEVEL	Windows		WdfIoQueueCreate wdfio/WdfIoQueueCreate	APIRef kbSyntax	LibDef	Wdf01000.sys Wdf01000.sys.dll WUDFx02000.dll WUDFx02000.dll.dll	WdfIoQueueCreate

WdfIoQueueCreate function

-description

[Applies to KMDF and UMDF]

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

-parameters

-param Device [in]

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

-param Config [in]

A pointer to a caller-allocated WDF_IO_QUEUE_CONFIG structure.

-param 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.

-param Queue [out, optional]

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

-returns

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;
    }
...
}

-see-also

WDF_IO_QUEUE_CONFIG

WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE

WDF_OBJECT_ATTRIBUTES

WdfDeviceConfigureRequestDispatching

WdfRequestForwardToIoQueue