EVT_WDFDEVICE_WDM_IRP_DISPATCH callback function

[Applies to KMDF and UMDF]

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

Syntax

EVT_WDFDEVICE_WDM_IRP_DISPATCH EvtWdfdeviceWdmIrpDispatch;

NTSTATUS EvtWdfdeviceWdmIrpDispatch(
  WDFDEVICE Device,
  UCHAR MajorFunction,
  UCHAR MinorFunction,
  ULONG Code,
  WDFCONTEXT DriverContext,
  PIRP Irp,
  WDFCONTEXT DispatchContext
)
{...}

Parameters

Device

A handle to a framework device object.

MajorFunction

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

MinorFunction

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

Code

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

DriverContext

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

Irp

A pointer to an IRP structure.

DispatchContext

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.

Remarks

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.

Examples

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:

EVT_WDFDEVICE_WDM_IRP_DISPATCH  MyDeviceWdmIrpDispatch;

Then, implement your callback function:

_Use_decl_annotations_
NTSTATUS
 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.

Requirements

   
Target Platform Universal
Minimum KMDF version 1.11
Minimum UMDF version 2.17
Header wdfdevice.h (include Wdf.h)
IRQL "<=DISPATCH_LEVEL"

See Also

WdfDeviceConfigureWdmIrpDispatchCallback

WdfDeviceWdmDispatchIrp

WdfDeviceWdmDispatchIrpToIoQueue