EvtDeviceD0Exit function

[Applies to KMDF and UMDF]

A driver's EvtDeviceD0Exit event callback function performs operations that are needed when the driver's device leaves the D0 power state.

Syntax

C++


EVT_WDF_DEVICE_D0_EXIT EvtDeviceD0Exit;

NTSTATUS EvtDeviceD0Exit(
  _In_  WDFDEVICE Device,
  _In_  WDF_POWER_DEVICE_STATE TargetState
)
{ ... }

Parameters

Device [in]: A handle to a framework device object.
TargetState [in]: A WDF_POWER_DEVICE_STATE-typed enumerator that identifies the device power state that the device is about to enter.

Return value

If the EvtDeviceD0Exit callback function encounters no errors, it must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, it must return a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

To register an EvtDeviceD0Exit callback function, a driver must call WdfDeviceInitSetPnpPowerEventCallbacks.

If the driver has registered an EvtDeviceD0Exit callback function, the framework calls the function each time one of the driver's devices leaves its working (D0) state. A device leaves the D0 state when one of the following occurs:

The system and all of its devices are about to leave their working states and enter a low-power state.
The device is about to enter a low-power state because it is idle, if the device supports low-power idle.
The Plug and Play manager is attempting to redistribute the system's hardware resources.
A user has indicated, typically by means of an application's user interface, that he or she wants to remove the device.

The framework also calls the EvtDeviceD0Exit callback function after a device has been removed unexpectedly (surprise-removed).

For more information about when the framework calls this callback function, see PnP and Power Management Scenarios.

Unless the device has been surprise-removed, the framework calls this callback function immediately after it disables the device's interrupts, but before the device's power is reduced from D0. The TargetState parameter identifies the device power state that the device is about to enter.

The EvtDeviceD0Exit callback function must perform any operations that are necessary before the device enters the specified low-power state, such as saving any information that the driver will need later to restore the device to its D0 power state.

If the TargetState parameter is WdfPowerDevicePrepareForHibernation, the driver must not shut off the device, because the system will use the device when saving its hibernation file.

If TargetState is WdfPowerDeviceD3Final, you should assume that the system is being turned off, the device is about to be removed, or a resource rebalance is in progress. If your driver must save information, it should write it to disk or some other permanent storage medium.

For more information about drivers that provide this callback function, see Supporting PnP and Power Management in Function Drivers.

Examples

To define an EvtDeviceD0Exit callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtDeviceD0Exit callback function that is named MyDeviceD0Exit, use the EVT_WDF_DEVICE_D0_EXIT type as shown in this code example:


EVT_WDF_DEVICE_D0_EXIT  MyDeviceD0Exit;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyDeviceD0Exit (
    WDFDEVICE  Device,
    WDF_POWER_DEVICE_STATE  TargetState
    )
  {...}

The EVT_WDF_DEVICE_D0_EXIT function type is defined in the Wdfdevice.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_DEVICE_D0_EXIT function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	Wdfdevice.h (include Wdf.h)
IRQL	PASSIVE_LEVEL