EvtDeviceArmWakeFromSxWithReason function

[Applies to KMDF and UMDF]

A driver's EvtDeviceArmWakeFromSxWithReason event callback function arms (that is, enables) a device so that it can trigger a wake signal while in a low-power device state. The wake signal causes the device to enter its working state (D0) and causes the system to enter its working state (S0).

Syntax

EVT_WDF_DEVICE_ARM_WAKE_FROM_SX_WITH_REASON EvtDeviceArmWakeFromSxWithReason;

NTSTATUS EvtDeviceArmWakeFromSxWithReason(
  _In_  WDFDEVICE Device,
  _In_  BOOLEAN DeviceWakeEnabled,
  _In_  BOOLEAN ChildrenArmedForWake
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

DeviceWakeEnabled [in]

A Boolean value that, if TRUE, indicates that the device's ability to wake the system is enabled.

ChildrenArmedForWake [in]

A Boolean value that, if TRUE, indicates that the ability of one or more child devices to wake the system is enabled.

Return value

If the EvtDeviceArmWakeFromSxWithReason callback function encounters no error, 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.

If NT_SUCCESS(status) equals FALSE, the framework calls the driver's EvtDeviceDisarmWakeFromSx callback function. (The framework does not report a device failure to the PnP manager.)

Remarks

Version 1.7 and later versions of KMDF support the EvtDeviceArmWakeFromSxWithReason callback function in addition to the EvtDeviceArmWakeFromSx callback function.

To register an EvtDeviceArmWakeFromSxWithReason callback function, a driver must call WdfDeviceInitSetPowerPolicyEventCallbacks. Drivers can register either an EvtDeviceArmWakeFromSx callback function or an EvtDeviceArmWakeFromSxWithReason callback function, but not both.

The EvtDeviceArmWakeFromSxWithReason callback function provides two parameters that enable the driver to determine why the framework has called it:

• The framework sets the DeviceWakeEnabled parameter to TRUE if the Enabled member of the WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure indicates that the device can wake the system.

• The framework sets the ChildrenArmedForWake parameter to TRUE if one or more of the device's child devices can wake the system and the ArmForWakeIfChildrenAreArmedForWake member of WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS is set to TRUE.

Either one or both of these parameters can be TRUE, because of the following scenarios:

• The driver's device is enabled to wake the system.

• One or more of the device's child devices are enabled to wake the system.

• Both the device and one or more of its child devices are enabled to wake the system.

For more information about the EvtDeviceArmWakeFromSxWithReason callback function, see the Remarks section of EvtDeviceArmWakeFromSx.

Examples

To define an EvtDeviceArmWakeFromSxWithReason 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 EvtDeviceArmWakeFromSxWithReason callback function that is named MyDeviceArmWakeFromSxWithReason, use the EVT_WDF_DEVICE_ARM_WAKE_FROM_SX_WITH_REASON type as shown in this code example:

EVT_WDF_DEVICE_ARM_WAKE_FROM_SX_WITH_REASON  MyDeviceArmWakeFromSxWithReason;

Then, implement your callback function as follows:

_Use_decl_annotations_
 NTSTATUS
 MyDeviceArmWakeFromSxWithReason (
    WDFDEVICE  Device
    BOOLEAN  DeviceWakeEnabled,
    BOOLEAN  ChildrenArmedForWake
    )
  {...}

The EVT_WDF_DEVICE_ARM_WAKE_FROM_SX_WITH_REASON 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_ARM_WAKE_FROM_SX_WITH_REASON 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

See also

EvtDeviceArmWakeFromS0

EvtDeviceArmWakeFromSx

EvtDeviceDisarmWakeFromSx

Send comments about this topic to Microsoft