EvtDeviceWdmIrpDispatch function

[Applies to KMDF only]

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

Syntax

EVT_WDFDEVICE_WDM_IRP_DISPATCH EvtDeviceWdmIrpDispatch;

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

Parameters

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

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.

Your driver can call either WdfDeviceWdmDispatchIrpToIoQueue or WdfDeviceWdmDispatchIrp from this callback function, but not both. A driver can also call neither, opting instead to complete the IRP or mark 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, consider providing 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

See also

WdfDeviceConfigureWdmIrpDispatchCallback

WdfDeviceWdmDispatchIrp

WdfDeviceWdmDispatchIrpToIoQueue

Send comments about this topic to Microsoft