Edit

Share via

WdfDeviceConfigureWdmIrpDispatchCallback function (wdfdevice.h)

  • Article

[Applies to KMDF and UMDF]

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

Syntax

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

Parameters

[in] Device

A handle to a framework device object.

[in, optional] Driver

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.

[in] MajorFunction

One of the following IRP major function codes: IRP_MJ_DEVICE_CONTROL, IRP_MJ_INTERNAL_DEVICE_CONTROL, IRP_MJ_READ, IRP_MJ_WRITE.

EvtDeviceWdmIrpDispatch

A pointer to the driver's EvtDeviceWdmIrpDispatch callback function.

[in, optional] DriverContext

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.

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)
Library Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
DDI compliance rules DriverCreate(kmdf)

See also

EvtDeviceWdmIrpDispatch

WdfDeviceWdmDispatchIrp

WdfDeviceWdmDispatchIrpToIoQueue