EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL callback function (wdfio.h)

[Applies to KMDF and UMDF]

A driver's EvtIoDeviceControl event callback function processes a specified device I/O control request.

Syntax

EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL EvtWdfIoQueueIoDeviceControl;

void EvtWdfIoQueueIoDeviceControl(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

Parameters

[in] Queue

A handle to the framework queue object that is associated with the I/O request.

[in] Request

A handle to a framework request object.

[in] OutputBufferLength

The length, in bytes, of the request's output buffer, if an output buffer is available.

[in] InputBufferLength

The length, in bytes, of the request's input buffer, if an input buffer is available.

[in] IoControlCode

The driver-defined or system-defined I/O control code (IOCTL) that is associated with the request.

Return value

None

Remarks

A driver registers an EvtIoDeviceControl callback function when it calls WdfIoQueueCreate. For more information about calling WdfIoQueueCreate, see Creating I/O Queues.

If a driver has registered an EvtIoDeviceControl callback function for a device's I/O queue, the callback function receives every I/O control request (IRP_MJ_DEVICE_CONTROL) from the queue. For more information, see Request Handlers.

The EvtIoDeviceControl callback function must process each received I/O request in some manner. For more information, see Processing I/O Requests.

Drivers receive I/O control requests when a user application calls DeviceIoControl (described in Microsoft Windows SDK documentation) or when another driver creates a request by calling either WdfIoTargetSendIoctlSynchronously or WdfIoTargetFormatRequestForIoctl.

The type of operation to be performed depends on the value of the IoControlCode parameter. You must determine the set of IoControlCode values that applications and other drivers can send to your driver. For more information about IOCTLs, see Using I/O Control Codes.

Most device I/O control operations require an input buffer, an output buffer, or both. For information about how the driver can access a request's buffers, see Accessing Data Buffers in Framework-Based Drivers.

The techniques that your driver can use to access the request's input and output buffers (if they exist) depend on the TransferType field of the IOCTL. The value of the IOCTL's TransferType field can be METHOD_BUFFERED, METHOD_DIRECT_IN, METHOD_DIRECT_OUT, or METHOD_NEITHER. For more information about the TransferType field, see Defining I/O Control Codes.

The EvtIoDeviceControl callback function can be called at IRQL <= DISPATCH_LEVEL, unless the ExecutionLevel member of the device or driver's WDF_OBJECT_ATTRIBUTES structure is set to WdfExecutionLevelPassive.

If the IRQL is PASSIVE_LEVEL, the framework calls the callback function within a critical region.

For more information about IRQL levels for request handlers, see Using Automatic Synchronization.

A driver's EvtIoDeviceControl callback function should not call the following queue object methods:

WdfIoQueueDrainSynchronously

WdfIoQueuePurgeSynchronously

WdfIoQueueStopSynchronously

Requirements

See also

EvtIoInternalDeviceControl

WDF_OBJECT_ATTRIBUTES

WdfIoQueueCreate

WdfIoTargetFormatRequestForIoctl

WdfIoTargetSendIoctlSynchronously