EvtDeviceWdmIrpPreprocess function

[Applies to KMDF only]

A driver's EvtDeviceWdmIrpPreprocess event callback function receives an IRP before the framework processes the IRP.

Syntax

EVT_WDFDEVICE_WDM_IRP_PREPROCESS EvtDeviceWdmIrpPreprocess;

NTSTATUS EvtDeviceWdmIrpPreprocess(
  _In_     WDFDEVICE Device,
  _Inout_  PIRP Irp
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

Irp [in, out]

A pointer to an IRP structure.

Return value

The EvtDeviceWdmIrpPreprocess callback function must:

• Set the IoStatus.Status member of the IRP to STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE, and return the same value (after calling IoCompleteRequest), if the callback function successfully completes the received IRP.
• Set the IoStatus.Status member of the IRP to a status value for which NT_SUCCESS(status) equals FALSE, and return the same value (after calling IoCompleteRequest), if the callback function detects an error.
• Return STATUS_PENDING, if the callback function calls IoMarkIrpPending.
• Return the value that the WdfDeviceWdmDispatchPreprocessedIrp method returns, if the callback function calls that method.

Remarks

To register an EvtDeviceWdmIrpPreprocess callback function, your driver must call WdfDeviceInitAssignWdmIrpPreprocessCallback.

Your driver can use an EvtDeviceWdmIrpPreprocess callback function to do any, or all, of the following:

• Handle an IRP that the framework does not support, by following the WDM rules for handling IRPs.

• Preprocess an IRP before the framework handles it.

• Set a completion routine so that the driver can postprocess an IRP after the framework handles it.

For more information about how to implement an EvtDeviceWdmIrpPreprocess callback function, see Handling WDM IRPs Outside of the Framework.

If you want the framework to subsequently handle the IRP as it would if the EvtDeviceWdmIrpPreprocess callback function had not been called, the callback function must call WdfDeviceWdmDispatchPreprocessedIrp to return the IRP to the framework.

If your driver registers an EvtDeviceWdmIrpPreprocess callback function, the framework adds an additional I/O stack location to IRPs that the callback function receives. The additional I/O stack location allows the callback function to set an IoCompletion routine before it calls WdfDeviceWdmDispatchPreprocessedIrp.

The EvtDeviceWdmIrpPreprocess callback function is called at the IRQL of the calling thread. The IRQL is determined by the type of IRP that the framework is passing to EvtDeviceWdmIrpPreprocess. For example, if the PnP manager sends IRP_MN_QUERY_DEVICE_RELATIONS at IRQL = PASSIVE_LEVEL, the framework calls EvtDeviceWdmIrpPreprocess at IRQL = PASSIVE_LEVEL.

Examples

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

EVT_WDFDEVICE_WDM_IRP_PREPROCESS  MyDeviceWdmIrpPreprocess;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
 MyDeviceWdmIrpPreprocess (
    WDFDEVICE  Device,
    PIRP  Irp
    )
  {...}

The EVT_WDFDEVICE_WDM_IRP_PREPROCESS 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_WDFDEVICE_WDM_IRP_PREPROCESS 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

WdfDeviceInitAssignWdmIrpPreprocessCallback

WdfDeviceWdmDispatchPreprocessedIrp

Send comments about this topic to Microsoft