Edit

Share via

EVT_WDFDEVICE_WDM_IRP_PREPROCESS callback function (wdfdevice.h)

  • Article

[Applies to KMDF only]

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

Syntax

EVT_WDFDEVICE_WDM_IRP_PREPROCESS EvtWdfdeviceWdmIrpPreprocess;

NTSTATUS EvtWdfdeviceWdmIrpPreprocess(
  [in]      WDFDEVICE Device,
  [in, out] PIRP Irp
)
{...}

Parameters

[in] Device

A handle to a framework device object.

[in, out] Irp

A pointer to an IRP structure.

Return value

The EvtDeviceWdmIrpPreprocess callback function must:

  • 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.
  • Return the value that the WdfDeviceWdmDispatchPreprocessedIrp method returns, if the callback function calls that method.

Remarks

To register an EvtDeviceWdmIrpPreprocess callback function, your driver must call WdfDeviceInitAssignWdmIrpPreprocessCallback.

Your driver can use an EvtDeviceWdmIrpPreprocess callback function to do any, or all, of the following:

  • Handle an IRP that the framework does not support, by following the WDM rules for handling IRPs.
  • Preprocess an IRP before the framework handles it.
  • Set a completion routine so that the driver can postprocess an IRP after the framework handles it.
For more information about how to implement an EvtDeviceWdmIrpPreprocess callback function, see Handling WDM IRPs Outside of the Framework.

If you want the framework to subsequently handle the IRP as it would if the EvtDeviceWdmIrpPreprocess callback function had not been called, the callback function must call WdfDeviceWdmDispatchPreprocessedIrp to return the IRP to the framework.

If your driver registers an EvtDeviceWdmIrpPreprocess callback function, the framework adds an additional I/O stack location to IRPs that the callback function receives. The additional I/O stack location allows the callback function to set an IoCompletion routine before it calls WdfDeviceWdmDispatchPreprocessedIrp.

The EvtDeviceWdmIrpPreprocess callback function is called at the IRQL of the calling thread. The IRQL is determined by the type of IRP that the framework is passing to EvtDeviceWdmIrpPreprocess. For example, if the PnP manager sends IRP_MN_QUERY_DEVICE_RELATIONS at IRQL = PASSIVE_LEVEL, the framework calls EvtDeviceWdmIrpPreprocess at IRQL = PASSIVE_LEVEL.

Requirements

Requirement Value
Target Platform Universal
Minimum KMDF version 1.0
Header wdfdevice.h (include Wdf.h)
IRQL <=DISPATCH_LEVEL

See also

WdfDeviceInitAssignWdmIrpPreprocessCallback

WdfDeviceWdmDispatchPreprocessedIrp