WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS结构（wdfdevice.h）

2025-03-22

[适用于 KMDF 和 UMDF]

当两者处于低功率状态时，WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构包含有关设备唤醒自身和系统的能力的驱动程序提供的信息。

语法

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

成员

Size

此结构的大小（以字节为单位）。

DxState

一个 DEVICE_POWER_STATE类型枚举器，用于标识低设备电源状态当系统电源状态下降到可唤醒的低功率状态时，设备将进入该状态。 DxState 的值不能 PowerDeviceD0。 DEVICE_POWER_STATE 值在 wdm.h中定义。

UserControlOfWakeSettings

一个 WDF_POWER_POLICY_SX_WAKE_USER_CONTROL类型枚举器，指示用户是否能够修改设备的唤醒设置。

Enabled

WDF_TRI_STATE类型枚举器，指示当系统处于低功率状态时，设备是否可以唤醒系统（即，将系统还原到 S0）。此成员可以具有以下值之一：

WdfTrue - 启用系统唤醒。

WdfFalse - 已禁用系统。

WdfUseDefault - 默认情况下会唤醒系统;但是，如果 UserControlOfWakeSettings 成员设置为 WakeAllowUserControl，则用户的设置或驱动程序的 INF 文件覆盖初始值。

如果唤醒系统并且系统即将进入低功率状态，则框架会在设备进入低功率状态之前调用驱动程序的 EvtDeviceArmWakeFromSx 或 EvtDeviceArmWakeFromSxWithReason 回调函数。

ArmForWakeIfChildrenAreArmedForWake

一个布尔值，如果设置为 TRUE，则表示父设备唤醒自身的能力，并且当为设备的子设备启用此功能时，应启用系统。有关详细信息，请参阅以下“备注”部分。此成员在 1.7 及更高版本的 KMDF 中可用。

IndicateChildWakeOnParentWake

一个布尔值，如果设置为 TRUE，则表示如果父设备检测到唤醒信号，框架将为子设备提供唤醒状态。有关详细信息，请参阅以下“备注”部分。此成员在 1.7 及更高版本的 KMDF 中可用。

注解

WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构用作 WdfDeviceAssignSxWakeSettings的输入。

若要初始化其 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构，驱动程序应调用 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT。

驱动程序首次调用 WdfDeviceAssignSxWakeSettings时，将执行以下作：

框架存储所有 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构成员的值。
如果 UserControlOfWakeSettings 成员设置为 WakeAllowUserControl，并且 已启用 成员设置为 WdfUseDefault，则框架会读取注册表，以确定用户是否已启用唤醒系统。

在后续调用 WdfDeviceAssignSxWakeSettings期间，框架不会存储 UserControlOfWakeSettings 成员的值。换句话说，在驱动程序首次调用 WdfDeviceAssignSxWakeSetting s 时，框架将执行以下步骤，但在后续调用期间不会执行以下步骤：

存储 UserControlOfWakeSettings 成员的值。
如果已启用成员的值 WdfUseDefault，则查找注册表中的用户设置。

以下规则适用于为 DxState 成员指定的值：

该值不能 PowerDeviceD0。
如果指定 PowerDeviceMaximum，则框架将使用 DeviceWake 中提供的设备的总线驱动程序 其 WDF_DEVICE_POWER_CAPABILITIES 结构的成员的值。
不能指定设备电源状态低于 DeviceWake 中的设备电源状态 总线驱动程序 WDF_DEVICE_POWER_CAPABILITIES 结构的成员。（换句话说，如果总线驱动程序的 DeviceWake 值 PowerDeviceD2，则函数驱动程序的 DxState 值不能 PowerDeviceD3。

有关控制设备唤醒功能的注册表项的信息，请参阅设备空闲和唤醒行为的用户控制。

如果 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 结构描述的设备是父设备，则父设备的驱动程序可以使用 ArmForWakeIfChildrenAreArmedForWake，IndicateChildWakeOnParentWake 成员，如下所示：

如果驱动程序将 ArmForWakeIfChildrenAreArmedForWake 成员设置为 TRUE，则框架会在启用子设备的唤醒能力时调用驱动程序的 EvtDeviceArmWakeFromSx 或 EvtDeviceArmWakeFromSxWithReason 回调函数，即使未启用父设备的唤醒功能。
若要降低能耗，你可能不希望启用设备的唤醒能力，除非还支持唤醒功能的子设备已插入。如果驱动程序将 ArmForWakeIfChildrenAreArmedForWake 成员设置为 TRUE，Enabled 成员的值具有以下含义：
- 如果 已启用WdfFalse，则仅当启用了子设备的唤醒功能时，框架才启用驱动程序的唤醒功能。
- 如果 已启用WdfTrue，则框架始终启用驱动程序的唤醒功能，无论设备是否启用了唤醒子设备。
- 如果 已启用WdfUseDefault，并且 UserControlOfWakeSettingsWakeAllowUserControl，则用户可以控制设备是否始终启用唤醒，或者仅当设备具有启用唤醒的子设备时才启用唤醒。
如果驱动程序将 IndicateChildWakeOnParentWake 成员设置为 TRUE，则框架会在父设备的驱动程序和每个启用唤醒的子设备的驱动程序中调用 EvtDeviceWakeFromSxTriggered 回调函数。如果驱动程序将此成员设置为 FALSE，则框架仅调用父设备的驱动程序中的 EvtDeviceWakeFromSxTriggered 回调函数。如果设备的子级驱动程序必须检查硬件以确定系统觉醒的原因，驱动程序应将 IndicateChildWakeOnParentWake 设置为 true。