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

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

儲存 UserControlOfWakeSettings 成員的值。
在登錄中尋找使用者設定，如果已啟用成員的值 WdfUseDefault。

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

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

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

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

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