WdfDeviceConfigureWdmIrpDispatchCallback method

[Applies to KMDF only]

The WdfDeviceConfigureWdmIrpDispatchCallback method registers a driver's EvtDeviceWdmIrpDispatch callback function.

Syntax

C++


NTSTATUS WdfDeviceConfigureWdmIrpDispatchCallback(
  [in]            WDFDEVICE Device,
  [in, optional]  WDFDRIVER Driver,
  [in]            UCHAR MajorFunction,
  [in]            PFN_WDFDEVICE_WDM_IRP_DISPATCH EvtDeviceWdmIrpDispatch,
  [in, optional]  WDFCONTEXT DriverContext
);

Parameters

Device [in]: A handle to a framework device object.
Driver [in, optional]: A handle to the driver's framework driver object that the driver obtained from a previous call to WdfDriverCreate or WdfGetDriver. This parameter is optional.
MajorFunction [in]: One of the following IRP major function codes: IRP_MJ_DEVICE_CONTROL, IRP_MJ_INTERNAL_DEVICE_CONTROL, IRP_MJ_READ, IRP_MJ_WRITE.
EvtDeviceWdmIrpDispatch [in]: A pointer to the driver's EvtDeviceWdmIrpDispatch callback function.
DriverContext [in, optional]: An untyped pointer to driver-defined context information that the framework passes to the driver's EvtDeviceWdmIrpDispatch callback function. This parameter is optional and can be NULL.

Return value

If the WdfDeviceConfigureWdmIrpDispatchCallback method encounters no errors, it returns STATUS_SUCCESS. Additional return values include:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid MajorFunction value was supplied.
STATUS_INSUFFICIENT_RESOURCES	Insufficient memory was available.

Remarks

A driver calls the WdfDeviceConfigureWdmIrpDispatchCallback method to register an EvtDeviceWdmIrpDispatch callback function. The framework then calls EvtDeviceWdmIrpDispatch whenever it receives an I/O request packet (IRP) containing an IRP major function code that matches the MajorFunction parameter of this method.

A driver typically calls WdfDeviceConfigureWdmIrpDispatchCallback from its EvtDriverDeviceAdd callback function.

You must call WdfDeviceConfigureWdmIrpDispatchCallback once for each MJ function for which the driver wants to register a callback function. In other words, multiple calls are required for intercepting multiple MJ functions.

A driver might call the WdfDeviceConfigureWdmIrpDispatchCallback method for these reasons:

To examine an IRP and assign it to a specific queue based on domain-specific criteria, for example, direct all I/O associated with a file object to a particular queue.
To select on an individual request basis the need to call the EvtIoInCallerContext callback function.

Requirements