EvtIoDeviceControl function

[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 EvtIoDeviceControl;

VOID EvtIoDeviceControl(
  _In_  WDFQUEUE Queue,
  _In_  WDFREQUEST Request,
  _In_  size_t OutputBufferLength,
  _In_  size_t InputBufferLength,
  _In_  ULONG IoControlCode
)
{ ... }

Parameters

Queue [in]

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

Request [in]

A handle to a framework request object.

OutputBufferLength [in]

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

InputBufferLength [in]

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

IoControlCode [in]

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

WdfIoQueueDrainSynchronously
WdfIoQueuePurgeSynchronously
WdfIoQueueStopSynchronously

Examples

To define an EvtIoDeviceControl callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtIoDeviceControl callback function that is named MyIoDeviceControl, use the EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL type as shown in this code example:


EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL  MyIoDeviceControl;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID
 MyIoDeviceControl (
 IN WDFQUEUE  Queue,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

The EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL function type is defined in the Wdfio.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfio.h (include Wdf.h)

IRQL

<= DISPATCH_LEVEL (see Remarks section)

See also

WdfIoQueueCreate
WdfIoTargetFormatRequestForIoctl
WdfIoTargetSendIoctlSynchronously
WDF_OBJECT_ATTRIBUTES
EvtIoInternalDeviceControl

 

 

Send comments about this topic to Microsoft

Показ:
© 2014 Microsoft