IWDFDevice::CreateIoQueue method

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The CreateIoQueue method configures the default I/O queue that is associated with a device or creates a secondary I/O queue for the device.

Syntax

HRESULT CreateIoQueue(
  IUnknown                   *pCallbackInterface,
  BOOL                       bDefaultQueue,
  WDF_IO_QUEUE_DISPATCH_TYPE DispatchType,
  BOOL                       bPowerManaged,
  BOOL                       bAllowZeroLengthRequests,
  IWDFIoQueue                **ppIoQueue
);

Parameters

pCallbackInterface

A pointer to the IUnknown interface that the framework uses to determine the event callback functions that the driver subscribes to on the queue. These are the functions that the framework calls when the relevant events occur.

For UMDF versions 1.9 and later, this parameter is required for I/O queues that use the sequential or parallel dispatching method, and it is optional (can be NULL) for I/O queues that use the manual dispatching method. For UMDF versions earlier than 1.9, this parameter is required for all dispatching methods.

bDefaultQueue

A BOOL value that specifies whether to configure the default I/O queue or create a secondary I/O queue for the device. TRUE indicates to configure the default I/O queue; FALSE indicates to create a secondary I/O queue.

DispatchType

A WDF_IO_QUEUE_DISPATCH_TYPE-typed value that identifies how the driver must receive requests from the I/O queue.

bPowerManaged

A BOOL value that specifies whether the I/O queue is power managed. TRUE indicates the framework automatically coordinates dispatching for the I/O queue with Plug and Play (PnP) and the power state of the device; FALSE indicates no automatically coordinated dispatching.

bAllowZeroLengthRequests

A BOOL value that specifies whether the framework puts zero-length I/O requests directly in the I/O queue for the driver to handle. TRUE indicates that the driver should receive read and write requests that have zero-length buffers--that is, the framework automatically puts these request types directly in the I/O queue for the driver. FALSE indicates that the framework completes zero-length I/O requests instead of putting them in the I/O queue.

ppIoQueue

A pointer to a variable that receives a pointer to the IWDFIoQueue interface for the newly created I/O queue object or the default I/O queue object.

Return Value

CreateIoQueue returns one of the following values:

Return code Description
S_OK
The I/O queue was successfully created.
HRESULT_FROM_WIN32(ERROR_BAD_CONFIGURATION)
The I/O queue is configured in one of the following ways:
  • The DispatchType parameter specifies a nonmanual queue and none of the I/O queue callback interfaces that are specified in the Remarks section are supported through the pCallbackInterface parameter.
  • The DispatchType parameter specifies a manual queue and one or more of the I/O queue callback interfaces that are specified in the Remarks section are supported through the pCallbackInterface parameter.
For more information about these configurations, see the Remarks section.
 

CreateIoQueue might also return other HRESULT values.

Remarks

The IUnknown interface that the driver supplies for the pCallbackInterface parameter can support several queue callback functions. The framework calls the QueryInterface method on the supplied IUnknown interface multiple times to retrieve the interface methods that the driver supports. When applications perform actions that are related to the methods of the supported interfaces (such as, an I/O read request), the framework calls the methods (such as, the IQueueCallbackRead::OnRead method) to notify the driver. The framework calls QueryInterface for the following interfaces:

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

When the driver passes either WdfIoQueueDispatchSequential or WdfIoQueueDispatchParallel for the DispatchType parameter of CreateIoQueue to create a nonmanual queue, CreateIoQueue can return S_OK only if the driver's queue callback object implements at least one of the preceding interfaces and indicates support of such interfaces through the IUnknown interface that pCallbackInterface points to.

When the driver passes WdfIoQueueDispatchManual for DispatchType to create a manual queue, CreateIoQueue can return S_OK only if the driver's queue callback object does not implement or indicate support of any of the preceding callback interfaces. For more information about the driver's callback objects, see Creating Callback Objects.

Note   The driver cannot use the same callback object for a manual queue that the driver uses for a sequential or parallel queue. That is, if the driver passes a particular pointer to an IUnknown interface in a call to CreateIoQueue to create a manual queue, the driver cannot later pass the identical pointer to IUnknown in a call to CreateIoQueue to create a sequential or parallel queue.
 
For more information about configuring dispatch mode, see Configuring Dispatch Mode for an I/O Queue.

The framework also calls QueryInterface on the supplied IUnknown interface to determine if the driver supports any of the following interfaces:

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

The framework also calls QueryInterface on the supplied IUnknown interface to determine if the driver supports the IQueueCallbackStateChange interface. The driver's queue callback object can optionally implement and indicate support of IQueueCallbackStateChange only for a manual queue. The driver's queue callback object must not implement and indicate support of IQueueCallbackStateChange for a sequential or parallel queue.

Examples

For a code example of how to use the CreateIoQueue method, see IWDFDriver::CreateDevice.

Requirements

   
End of support Unavailable in UMDF 2.0 and later.
Target Platform Desktop
Minimum UMDF version 1.5
Header wudfddi.h (include Wudfddi.h)
DLL WUDFx.dll

See Also

IObjectCleanup

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IWDFDevice

IWDFIoQueue

WDF_IO_QUEUE_DISPATCH_TYPE