Edit

Share via

EVT_WDFDEVICE_WDM_IRP_DISPATCH callback function (wdfdevice.h)

  • Article

[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(
  [in]      WDFDEVICE Device,
  [in]      UCHAR MajorFunction,
  [in]      UCHAR MinorFunction,
  [in]      ULONG Code,
  [in]      WDFCONTEXT DriverContext,
  [in, out] PIRP Irp,
  [in]      WDFCONTEXT DispatchContext
)
{...}

Parameters

[in] Device

A handle to a framework device object.

[in] MajorFunction

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

[in] MinorFunction

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

[in] Code

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

[in] DriverContext

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

[in, out] Irp

A pointer to an IRP structure.

[in] 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.

Requirements

Requirement Value
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