WdfDeviceConfigureWdmIrpDispatchCallback method

[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,
  [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 codeDescription
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

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

See also

EvtDeviceWdmIrpDispatch
WdfDeviceWdmDispatchIrp
WdfDeviceWdmDispatchIrpToIoQueue

 

 

Send comments about this topic to Microsoft

Show: