EVT_WDF_IO_QUEUE_IO_INTERNAL_DEVICE_CONTROL callback function (wdfio.h)

Article
10/21/2021

[Applies to KMDF and UMDF]

A driver's EvtIoInternalDeviceControl event callback function processes an I/O request that contains an internal device I/O control code (IOCTL).

Syntax

EVT_WDF_IO_QUEUE_IO_INTERNAL_DEVICE_CONTROL EvtWdfIoQueueIoInternalDeviceControl;

void EvtWdfIoQueueIoInternalDeviceControl(
  [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 IOCTL that is associated with the request.

Return value

None

Remarks

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

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

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

Drivers receive internal I/O control requests when another driver creates a request by calling either WdfIoTargetSendInternalIoctlSynchronously or WdfIoTargetFormatRequestForInternalIoctl.

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 internal 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 EvtIoInternalDeviceControl 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 your driver is at the top of its driver stack, the callback function is called at IRQL = PASSIVE_LEVEL.)

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 EvtIoInternalDeviceControl callback function should not call the following queue object methods:

WdfIoQueueDrainSynchronously

WdfIoQueuePurgeSynchronously

WdfIoQueueStopSynchronously

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfio.h (include Wdf.h)
IRQL	<= DISPATCH_LEVEL (see Remarks section)