[Applies to KMDF and UMDF]

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



NTSTATUS EvtDeviceWdmIrpDispatch(
  _In_    WDFDEVICE  Device,
  _In_    UCHAR      MajorFunction,
  _In_    UCHAR      MinorFunction,
  _In_    ULONG      Code,
  _In_    WDFCONTEXT DriverContext,
  _Inout_ PIRP       Irp,
  _In_    WDFCONTEXT DispatchContext
{ ... }


Device [in]

A handle to a framework device object.

MajorFunction [in]

One of the IRP major function codes that are defined in wdm.h.

MinorFunction [in]

One of the I/O IRP minor function codes that are defined in wdm.h for the MajorFunction code.

Code [in]

Specifies an I/O control code value. This parameter is valid only if MajorFunction is set to IRP_MJ_DEVICE_CONTROL.

DriverContext [in]

An untyped pointer to driver-defined context information that the driver provided when it called WdfDeviceConfigureWdmIrpDispatchCallback.

Irp [in, out]

A pointer to an IRP structure.

DispatchContext [in]

An untyped pointer to the framework's dispatch context information. The driver must provide this parameter when it calls WdfDeviceWdmDispatchIrp.

Return value

The EvtDeviceWdmIrpDispatch callback function must:

  • Return the value that the WdfDeviceWdmDispatchIrp method returns, if the callback function calls that method.
  • Return the value that the WdfDeviceWdmDispatchIrpToIoQueue method returns, if the callback function calls that method.
  • KMDF only

    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.
  • KMDF only

    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.
  • KMDF only

    Return STATUS_PENDING if the callback function calls IoMarkIrpPending.


The EvtDeviceWdmIrpDispatch callback function should only be used to select a specific queue for an IRP. To do so, the driver calls the WdfDeviceWdmDispatchIrpToIoQueue method from within the callback function.

If, after examining an IRP in this callback function, the driver does not know how to dispatch the IRP, the driver can call WdfDeviceWdmDispatchIrp to return the IRP to the framework for default handling.

A UMDF driver must call either WdfDeviceWdmDispatchIrp or WdfDeviceWdmDispatchIrpToIoQueue from this callback function. A KMDF driver has the additional option of calling neither, and instead completing the IRP or marking it pending.

To register an EvtDeviceWdmIrpDispatch callback function, your driver must call WdfDeviceConfigureWdmIrpDispatchCallback.

In its EvtDeviceWdmIrpDispatch callback function, a driver should not set a completion routine. If a completion routine is needed, a KMDF driver can provide a EvtDeviceWdmIrpPreprocess callback function instead of EvtDeviceWdmIrpDispatch.

For more information about specifying queues for IRPs as they arrive, see Dispatching IRPs to I/O Queues.


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


Then, implement your callback function:

 MyDeviceWdmIrpDispatch (
    WDFDEVICE Device,
    UCHAR MajorFunction,
    UCHAR MinorFunction,   
    ULONG Code,
    WDFCONTEXT DriverContext,
    PIRP Irp,
    WDFCONTEXT DispatchContext

The EVT_WDFDEVICE_WDM_IRP_DISPATCH 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_DISPATCH 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.


Target platform


Minimum KMDF version


Minimum UMDF version



Wdfdevice.h (include Wdf.h)



See also




Send comments about this topic to Microsoft