EvtIoInCallerContext function

[Applies to KMDF only]

A driver's EvtIoInCallerContext event callback function preprocesses an I/O request before the framework places it into an I/O queue.

Syntax

EVT_WDF_IO_IN_CALLER_CONTEXT EvtIoInCallerContext;

VOID EvtIoInCallerContext(
  _In_  WDFDEVICE Device,
  _In_  WDFREQUEST Request
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

Request [in]

A handle to a framework request object.

Return value

None

Remarks

The framework calls a driver's EvtIoInCallerContext callback function so that the driver can examine each I/O request, and possibly perform preliminary processing on the request, before the framework places it in an I/O queue. To register an EvtIoInCallerContext callback function for a device, the driver calls WdfDeviceInitSetIoInCallerContextCallback.

If a driver registers an EvtIoInCallerContext callback function for a device, the framework calls the callback function each time it receives an I/O request for the device. The callback function is called in the thread context of the process that sent the I/O request to the driver. This process is either the next-higher level driver or, if the driver is at the top of the driver stack, a user-mode application.

This callback function's primary purpose is to enable framework-based drivers to support the buffer-access method that is called neither buffered nor direct I/O. For this buffer-access method, the driver must access received buffers in the originator's process context.

After the callback function has obtained a request's buffers, it can store buffer addresses or handles in the request object's context storage. (The driver sets the size of the request object's context storage area by calling WdfDeviceInitSetRequestAttributes.)

Because the request does not yet belong to an I/O queue, the framework does not lock or synchronize the request. The driver is responsible for any synchronization that might be necessary. For more information about synchronization, see Synchronization Techniques for Framework-Based Drivers.

After the callback function has finished preprocessing the request, it must either queue it by calling WdfDeviceEnqueueRequest or complete it by calling WdfRequestComplete (if an error is detected).

For more information about the EvtIoInCallerContext callback function, see Intercepting an I/O Request before it is Queued and Accessing Data Buffers in Framework-Based Drivers.

If a driver has configured an I/O queue to support guaranteed forward progress, the framework might not call the driver's EvtIoInCallerContext callback function during low-memory situations. If all of the framework's reserved request objects are in use, the framework postpones processing the I/O request until a reserved request object is available. In this situation, the framework cannot call the EvtIoInCallerContext callback function for the postponed I/O request because, when a reserved request object becomes available, the framework will no longer be running in the thread context of the process that sent the I/O request to the driver.

The EvtIoInCallerContext callback function is called at the IRQL of the calling thread. If the calling thread is from a user-mode application, the callback function is called at IRQL = PASSIVE_LEVEL. If the calling thread is from a higher-level kernel-mode driver, your driver's EvtIoInCallerContext callback function can be called at IRQL <= DISPATCH_LEVEL if both the callback function and the higher-level driver are designed to pass the request at IRQL <= DISPATCH_LEVEL.

Examples

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

EVT_WDF_IO_IN_CALLER_CONTEXT  MyIoInCallerContext;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
 MyIoInCallerContext  (
    WDFDEVICE  Device,
    WDFREQUEST  Request
    )
  {...}

The EVT_WDF_IO_IN_CALLER_CONTEXT function type is defined in the Wdfdevice.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_IN_CALLER_CONTEXT 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

See also

EvtDeviceWdmIrpPreprocess

Send comments about this topic to Microsoft