WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 結構 (wdfdevice.h)

發行項
08/08/2023

[適用於 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 ，而且 Enabled 成員設定為 WdfUseDefault，架構會讀取登錄，以了解使用者是否已啟用喚醒系統。

在後續呼叫 WdfDeviceAssignSxWakeSettings 期間，架構不會儲存 UserControlOfWakeSettings 成員的值。換句話說，此架構會在驅動程式第一次呼叫 WdfDeviceAssignSxWakeSettings 時執行下列步驟，但在後續呼叫期間不會執行下列步驟：

儲存 UserControlOfWakeSettings 成員的值。
如果 Enabled 成員的值是 WdfUseDefault，請在登錄中尋找用戶設定。

下列規則適用於您為 DxState 成員指定的值：

此值不可為 PowerDeviceD0。
如果您指定 PowerDeviceMaximum，架構會使用驅動程式在其WDF_DEVICE_POWER_CAPABILITIES結構之 DeviceWake 成員中提供之裝置總線的值。
您無法在總線驅動程式WDF_DEVICE_POWER_CAPABILITIES結構的 DeviceWake 成員中，指定低於裝置電源狀態的裝置電源狀態。 (換句話說，如果總線驅動程式的 DeviceWake 值為 PowerDeviceD2，則函式驅動程式的 DxState 值不能是 PowerDeviceD3.)

如需控制裝置喚醒功能的登錄專案相關信息，請參閱裝置閑置和喚醒行為的使用者控制。

如果 WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS 結構的裝置是父裝置，則父裝置的驅動程式可以使用 ArmForWakeIfChildrenAreArmedForWake 和 IndicateChildWakeOnParentWake 成員，如下所示：

如果驅動程式將 ArmForWakeIfChildrenAreArmedForWake 成員設定為 TRUE，則架構會呼叫驅動程式的 EvtDeviceArmWakeFromSx 或 EvtDeviceArmWakeFromSxWithReason 回呼函式，即使父裝置的喚醒功能未啟用也一樣。
若要減少耗電量，除非您也支持喚醒功能的子裝置已插入電源，否則您可能不想啟用裝置的喚醒能力。如果您的驅動程式將 ArmForWakeIfChildrenAreArmedForWake 成員設定為 TRUE， 則 Enabled 成員的值具有下列意義：
- 如果 Enabled 是 WdfFalse，則只有在啟用子裝置的喚醒能力時，架構才會啟用驅動程式的喚醒能力。
- 如果 Enabled 是 WdfTrue，架構一律會啟用驅動程式的喚醒能力，不論您的裝置是否已啟用喚醒子裝置。
- 如果 Enabled 為 WdfUseDefault ，且 UserControlOfWakeSettings 為 WakeAllowUserControl，則使用者可以控制您的裝置是否一律啟用喚醒，或只有在您的裝置有啟用喚醒功能的子裝置時才啟用。
如果驅動程式將 IndicateChildWakeOnParentWake 成員設定為 TRUE，架構會在父裝置的驅動程式和每個啟用喚醒的子裝置的驅動程式中呼叫 EvtDeviceWakeFromSxTriggered 回呼函式。如果驅動程式將此成員設定為 FALSE，架構只會在父裝置的驅動程式中呼叫 EvtDeviceWakeFromSxTriggered 回呼函式。如果裝置子系的驅動程式必須檢查硬體，則驅動程序應該將 IndicateChildWakeOnParentWake 設定為 TRUE ，以判斷系統被喚醒的原因。