EvtIoRead function

[Applies to KMDF and UMDF]

A driver's EvtIoRead event callback function processes a specified read request.

Syntax


EVT_WDF_IO_QUEUE_IO_READ EvtIoRead;

VOID EvtIoRead(
  _In_  WDFQUEUE Queue,
  _In_  WDFREQUEST Request,
  _In_  size_t Length
)
{ ... }

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.
Length [in]: The number of bytes to be read.

Return value

None

Remarks

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

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

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

Read requests require an output buffer, which receives data that the driver provides. For information about how the driver can access a read request's buffer, see Accessing Data Buffers in Framework-Based Drivers.

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

WdfIoQueueDrainSynchronously

WdfIoQueuePurgeSynchronously

WdfIoQueueStopSynchronously

Examples

To define an EvtIoRead 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 EvtIoRead callback function that is named MyIoRead, use the EVT_WDF_IO_QUEUE_IO_READ type as shown in this code example:


EVT_WDF_IO_QUEUE_IO_READ  MyIoRead;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID
 MyIoRead (
    WDFQUEUE  Queue,
    WDFREQUEST  Request,
    size_t  Length
    )
 {...}

The EVT_WDF_IO_QUEUE_IO_READ 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_READ 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)