WdfDeviceGetSystemPowerAction 函数 (wdfdevice.h)

[适用于 KMDF 和 UMDF]

WdfDeviceGetSystemPowerAction 方法返回计算机当前发生的系统电源操作（如果有）。

语法

POWER_ACTION WdfDeviceGetSystemPowerAction(
  [in] WDFDEVICE Device
);

[in] Device

框架设备对象的句柄。

WdfDeviceGetSystemPowerAction 返回POWER_ACTION类型的枚举器值。值指示计算机当前发生的系统电源操作。有关更多信息，请参见下面的“备注”部分。 POWER_ACTION枚举在 wdm.h 中定义。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

从 WDF 版本 1.31/2.31 (称为“v31”) 开始， WdfDeviceGetSystemPowerAction 已更新，以在设备是电源策略所有者时更准确地报告系统电源操作。驱动程序需要使用 v31 或更高版本重新编译才能获取以下新行为：

如果设备由于 S0 空闲 (在进行不相关的系统电源转换时看到 WdfDeviceAssignS0IdleSettings) 进入或退出 D0，WdfDeviceGetSystemPowerAction 可能会返回 PowerActionSleep。此问题在 v31 中已修复，现在它返回 PowerActionNone。
在 v31 之前，当系统从混合睡眠 (睡眠) 休眠文件唤醒时， WdfDeviceGetSystemPowerAction 始终返回 PowerActionHibernate。此问题在 v31 中已修复，现在它返回：
- 如果 PowerActionSleep 在未断电的情况下唤醒，则表示系统仍保留在 S3 中
- 如果 PowerActionHibernate 在断电后唤醒，则表示系统已从休眠文件恢复

WdfDeviceGetSystemPowerAction 方法使驱动程序能够确定设备的电源转换是由于设备处于空闲 (或) 唤醒，还是因为整个计算机进入 (或离开) 低功耗状态。

驱动程序必须仅在设备进入低功耗状态或返回到其工作状态时从框架调用的事件回调函数调用 WdfDeviceGetSystemPowerAction。

WdfDeviceGetSystemPowerAction 返回的值取决于以下情况：

如果计算机在驱动程序调用 WdfDeviceGetSystemPowerAction 时进入低功耗状态，该方法将返回计算机进入低功耗状态的原因。例如，如果计算机进入其 S1、S2 或 S3 低功耗状态，方法将返回 PowerActionSleep 。
如果计算机在驱动程序调用 WdfDeviceGetSystemPowerAction 时返回到其工作 (S0) 状态，则该方法返回计算机进入低功耗状态的原因。例如，如果计算机离开其 S1、S2 或 S3 低功耗状态，方法将返回 PowerActionSleep 。
如果计算机在驱动程序调用 WdfDeviceGetSystemPowerAction 时关闭) 后 (启动，则该方法返回 PowerActionNone。
如果设备在驱动程序调用 WdfDeviceGetSystemPowerAction 时进入低功耗空闲状态或返回到其工作 (D0) 状态，则当系统的其余部分保持其工作 (S0) 状态时，该方法将返回 PowerActionNone。
如果驱动程序调用 WdfDeviceGetSystemPowerAction 时计算机和设备都处于工作状态，则该方法返回 PowerActionNone。

有关低功耗状态的详细信息，请参阅设备进入 Low-Power 状态。

下面的代码示例获取计算机当前发生的电源转换活动。

POWER_ACTION SysPowerAction;

SysPowerAction = WdfDeviceGetSystemPowerAction(device);

要求	值
目标平台	通用
最低 KMDF 版本	1.9
最低 UMDF 版本	2.0
标头	wdfdevice.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)