WdfDeviceGetSystemPowerAction 函式 (wdfdevice.h)

[適用於 KMDF 和 UMDF]

WdfDeviceGetSystemPowerAction 方法會傳回計算機目前發生的系統電源動作。

語法

POWER_ACTION WdfDeviceGetSystemPowerAction(
  [in] WDFDEVICE Device
);

[in] Device

架構裝置物件的句柄。

WdfDeviceGetSystemPowerAction 會傳回POWER_ACTION類型的列舉值。值表示電腦目前發生的系統電源動作。如需詳細資訊，請參閱接下來的＜備註＞一節。 POWER_ACTION列舉定義於 wdm.h 中。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

從 WDF 1.31/2.31 版開始， (稱為 “v31” ) ，WdfDeviceGetSystemPowerAction 已更新為在裝置是電源原則擁有者時更精確地報告系統電源動作。驅動程式必須使用 v31 或更新版本重新編譯，才能取得下列新行為：

如果裝置因為 S0 閑置 (而進入或結束 D0，請參閱 WdfDeviceAssignS0IdleSettings) ，而未相關的系統電源轉換正在進行中， 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);

需求	值
目標平台	Universal
最小 KMDF 版本	1.9
最低UMDF版本	2.0
標頭	wdfdevice.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)