From acd3eb42bfdf16b6947f2ceacecc59001a67957f Mon Sep 17 00:00:00 2001 From: Ruth Waiganjo Date: Fri, 15 May 2026 17:14:36 +0300 Subject: [PATCH 1/6] specs: Add EnergySaverStatus2 API spec Introduces spec for the new Microsoft.Windows.System.Power.PowerManager EnergySaverStatus2 API, which expands the legacy two-state EnergySaverStatus (On/Off) to a three-state model (Off/Standard/HighSavings) reflecting the Windows Germanium Energy Saver update. New APIs documented: - PowerManager.EnergySaverStatus2 property - PowerManager.EnergySaverStatus2Changed event - PowerManager.IsEnergySaverStatus2Supported() method - EnergySaverStatus2 enum ADO: Task 60383995, 61020635, 61020638, 61020649 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../EnergySaverStatus2/EnergySaverStatus2.md | 363 ++++++++++++++++++ 1 file changed, 363 insertions(+) create mode 100644 specs/EnergySaverStatus2/EnergySaverStatus2.md diff --git a/specs/EnergySaverStatus2/EnergySaverStatus2.md b/specs/EnergySaverStatus2/EnergySaverStatus2.md new file mode 100644 index 0000000000..951f783a16 --- /dev/null +++ b/specs/EnergySaverStatus2/EnergySaverStatus2.md @@ -0,0 +1,363 @@ +# EnergySaverStatus2 API + +| | | +|-|-| +| **Area** | OS\Windows Client and Services\Fundamentals\PH-Platform Health\Sustainability | +| **Product/Program Manager** | Ugochi Nweze (nwezeugochi) | +| **Developer** | Tobi Adebisi (adebisitobi), Ruth Waiganjo (ruthwaiganjo) | +| **API Design Representative** | Minsang Kim (mikim) | +| **ADO – Implementation** | Task 60383995 | +| **ADO – Testing** | Task 61020635 | +| **ADO – Sample** | Task 61020638 | +| **ADO – Documentation** | Task 61020649 | + +# Background + +The existing `Microsoft.Windows.System.Power.PowerManager.EnergySaverStatus` property reports +only two states: `Off` and `On`. Starting with the Windows Germanium release, the OS Energy Saver +feature was updated to support three distinct operating modes — **Off**, **Standard**, and +**High Savings** — which are now visible to users in the Windows Settings app. + +The original two-state API contains a bug: when Energy Saver is active in **Standard** mode +(battery above 20%), `EnergySaverStatus` incorrectly reports `Off`. Only the **High Savings** +state (battery at or below 20%) correctly maps to `On`. + +This spec introduces `EnergySaverStatus2`, a new enum and associated APIs on +`Microsoft.Windows.System.Power.PowerManager`, that accurately reflects all three energy saver +states. The legacy `EnergySaverStatus` API is unchanged for backward compatibility. + +> **Minimum OS requirement:** These APIs require a Germanium+ OS build. On earlier OS versions, +> `IsEnergySaverStatus2Supported` returns `false` and `EnergySaverStatus2` returns `Unknown`. + +# Conceptual pages (How To) + +_(This is conceptual documentation that will go to docs.microsoft.com "how to" page)_ + +## Responding to Energy Saver state changes in your app + +Energy Saver helps extend battery life by signaling apps to reduce resource consumption. +Starting with Windows Germanium, Energy Saver has three states that your app can respond to +with varying levels of optimization: + +| State | Meaning | Recommended app behavior | +|---|---|---| +| `Off` | Energy Saver is disabled | Normal operation | +| `Standard` | Energy Saver active; mild performance impact acceptable | Reduce background sync frequency, defer non-critical work | +| `HighSavings` | Energy Saver active; maximum power savings preferred | Pause background sync, defer all non-critical work, reduce UI refresh rates | + +Use `PowerManager.EnergySaverStatus2` to read the current state and subscribe to +`PowerManager.EnergySaverStatus2Changed` to respond to transitions at runtime. + +Always call `PowerManager.IsEnergySaverStatus2Supported()` first if your app targets systems +that may run on OS versions earlier than Germanium. On unsupported systems, the property +returns `Unknown` and the changed event is never raised. + +# API Pages + +_(Each of the following L2 sections correspond to a page that will be on docs.microsoft.com)_ + +## PowerManager.EnergySaverStatus2 property + +Gets the current Energy Saver v2 status for the device. + +```csharp +public static EnergySaverStatus2 EnergySaverStatus2 { get; } +``` + +```cppwinrt +static EnergySaverStatus2 EnergySaverStatus2(); +``` + +Use this property together with `EnergySaverStatus2Changed` to monitor power-state transitions +and adjust your app's resource usage accordingly. When Energy Saver is in `Standard` mode your +app should reduce non-critical background work; in `HighSavings` mode it should defer or pause +background operations entirely. + +### Example – Reading the current status (C#) + +```csharp +using Microsoft.Windows.System.Power; + +EnergySaverStatus2 status = PowerManager.EnergySaverStatus2; +switch (status) +{ + case EnergySaverStatus2.Off: + // Normal operation + break; + case EnergySaverStatus2.Standard: + // Reduce background activity + break; + case EnergySaverStatus2.HighSavings: + // Pause background activity + break; + case EnergySaverStatus2.Unknown: + default: + // API not supported on this OS build + break; +} +``` + +### Example – Reading the current status (C++/WinRT) + +```cpp +#include + +using namespace winrt::Microsoft::Windows::System::Power; + +EnergySaverStatus2 status = PowerManager::EnergySaverStatus2(); +switch (status) +{ + case EnergySaverStatus2::Off: + // Normal operation + break; + case EnergySaverStatus2::Standard: + // Reduce background activity + break; + case EnergySaverStatus2::HighSavings: + // Pause background activity + break; + case EnergySaverStatus2::Unknown: + default: + // API not supported on this OS build + break; +} +``` + +### Remarks + +- Returns `Unknown` if `IsEnergySaverStatus2Supported()` returns `false`. +- This property is safe to call from background tasks and non-foreground windows. +- Does not require any special app capabilities. + +--- + +## PowerManager.EnergySaverStatus2Changed event + +Occurs when the `EnergySaverStatus2` value changes. + +```csharp +public static event System.EventHandler EnergySaverStatus2Changed; +``` + +```cppwinrt +static winrt::event_token EnergySaverStatus2Changed( + winrt::Windows::Foundation::EventHandler const& handler); + +static void EnergySaverStatus2Changed(winrt::event_token const& token) noexcept; +``` + +Subscribe to this event to receive notifications when the device transitions between Energy Saver +states. When the event fires, call `PowerManager.EnergySaverStatus2` to retrieve the new value. + +### Example – Subscribing to status changes (C#) + +```csharp +using Microsoft.Windows.System.Power; + +// Subscribe +PowerManager.EnergySaverStatus2Changed += OnEnergySaverStatus2Changed; + +// Handler +private static void OnEnergySaverStatus2Changed(object sender, object e) +{ + EnergySaverStatus2 status = PowerManager.EnergySaverStatus2; + switch (status) + { + case EnergySaverStatus2.Standard: + ReduceBackgroundActivity(); + break; + case EnergySaverStatus2.HighSavings: + PauseBackgroundActivity(); + break; + case EnergySaverStatus2.Off: + ResumeNormalActivity(); + break; + } +} + +// Unsubscribe when done +PowerManager.EnergySaverStatus2Changed -= OnEnergySaverStatus2Changed; +``` + +### Example – Subscribing to status changes (C++/WinRT) + +```cpp +#include + +using namespace winrt::Microsoft::Windows::System::Power; + +auto revoker = PowerManager::EnergySaverStatus2Changed( + winrt::auto_revoke, + [](auto, winrt::Windows::Foundation::IInspectable const&) + { + EnergySaverStatus2 status = PowerManager::EnergySaverStatus2(); + // Respond to new state + }); +``` + +### Remarks + +- The event is never raised on OS builds where `IsEnergySaverStatus2Supported()` returns `false`. +- The event is raised on the thread that registered, unless the implementation routes it through a + dispatcher — subscribe and unsubscribe on the same thread. + +--- + +## PowerManager.IsEnergySaverStatus2Supported method + +Returns a value indicating whether the current OS supports `EnergySaverStatus2`. + +```csharp +public static bool IsEnergySaverStatus2Supported(); +``` + +```cppwinrt +static bool IsEnergySaverStatus2Supported(); +``` + +Call this method before using `EnergySaverStatus2` or `EnergySaverStatus2Changed` when your app +may run on OS versions earlier than Germanium. On unsupported builds, the property returns +`Unknown` and the event is never raised. + +### Example (C#) + +```csharp +using Microsoft.Windows.System.Power; + +if (!PowerManager.IsEnergySaverStatus2Supported()) +{ + // Fall back to legacy EnergySaverStatus + return; +} + +EnergySaverStatus2 status = PowerManager.EnergySaverStatus2; +``` + +### Remarks + +- Calling this method is optional. You can use `EnergySaverStatus2` without it; if the feature is + unsupported the property safely returns `Unknown`. +- Returns `true` only on Germanium+ OS builds. + +--- + +## EnergySaverStatus2 enum + +Represents the current Energy Saver mode of the device using the expanded v2 state. + +```csharp +public enum EnergySaverStatus2 +{ + Unknown = 0, + Off = 1, + Standard = 2, + HighSavings = 3 +} +``` + +| Value | Description | +|---|---| +| `Unknown` | The Energy Saver v2 status is unavailable, either because the OS does not support it or because the status has not yet been initialized. | +| `Off` | Energy Saver is disabled. Apps should operate normally. | +| `Standard` | Energy Saver is active with mild performance impact acceptable. Energy saving behaviors that have mild performance impact are encouraged (for example, a sync client might reduce sync frequency). This state is returned when the user has opted into Energy Saver but battery life is not critical. | +| `HighSavings` | Energy Saver is active and maximum battery savings are preferred, even at the cost of performance. This state is returned when battery level is low and the device is not plugged in. | + +### Remarks + +- `EnergySaverStatus2` may be extended with additional values in future OS releases. Your code + should handle unknown enum values gracefully (for example, with a `default` case in a `switch`). +- The enum values map to the legacy `EnergySaverStatus` as follows: + +| `EnergySaverStatus2` | Legacy `EnergySaverStatus` | +|---|---| +| `Off` | `Off` | +| `Standard` | `Off` _(legacy API does not distinguish this state)_ | +| `HighSavings` | `On` | + +--- + +## Other PowerManager members + +For the full list of existing `PowerManager` members see +[Microsoft.Windows.System.Power.PowerManager](https://learn.microsoft.com/windows/apps/api-reference/). + +# API Details + +```csharp (but really MIDL3) +namespace Microsoft.Windows.System.Power +{ + [contractversion(3)] + apicontract PowerNotificationsContract{}; + + // Existing EnergySaverStatus enum (unchanged) + [contract(PowerNotificationsContract, 1)] + enum EnergySaverStatus + { + Uninitialized = 0, + Disabled, + Off, + On + }; + + /// Represents the current energy saver mode of the device using the expanded v2 state. + [contract(PowerNotificationsContract, 3)] + enum EnergySaverStatus2 + { + /// The status is unavailable or unsupported on this OS build. + Unknown = 0, + /// Energy Saver is disabled. + Off = 1, + /// Energy Saver is active; mild performance impact is acceptable. + Standard = 2, + /// Energy Saver is active; maximum battery savings are preferred. + HighSavings = 3 + }; + + [contract(PowerNotificationsContract, 1)] + static runtimeclass PowerManager + { + // ... existing members (unchanged) ... + + /// Gets the current Energy Saver v2 status for the device. + [contract(PowerNotificationsContract, 3)] + static EnergySaverStatus2 EnergySaverStatus2{ get; }; + + /// Occurs when the EnergySaverStatus2 value changes. + [contract(PowerNotificationsContract, 3)] + static event Windows.Foundation.EventHandler EnergySaverStatus2Changed; + + /// Returns true if this OS build supports EnergySaverStatus2; false otherwise. + [contract(PowerNotificationsContract, 3)] + static Boolean IsEnergySaverStatus2Supported(); + }; +} +``` + +# Appendix + +## Legacy API compatibility and mapping + +`EnergySaverStatus2` is an additive API and does not replace `EnergySaverStatus`. Apps that +currently use `EnergySaverStatus` will continue to work unchanged. The legacy API's behavior +is not modified. + +The legacy `EnergySaverStatus` has a known limitation: when Energy Saver is active in **Standard** +mode (battery above 20%), it reports `Off`, meaning apps using the legacy API cannot distinguish +"Energy Saver Standard active" from "Energy Saver disabled". `EnergySaverStatus2` fixes this. + +## Alternative designs considered + +- **Extend the existing enum** – Adding `Standard` and `HighSavings` values to `EnergySaverStatus` + was rejected because it would be a breaking change for existing switch statements that do not + handle new enum values. +- **New PowerManager class** – Rejected in favor of additive members on the existing + `PowerManager` static class to maintain API surface consistency. + +## Related ADO tasks + +| Task | Description | +|---|---| +| 60383995 | Energy Saver on UWP: New 3P API Development and SDK Updates | +| 61020635 | Testing: Energy Saver on UWP | +| 61020638 | Sample Application(s): Energy Saver on UWP | +| 61020649 | Documentation: Energy Saver on UWP | From 8f66acc973c3dda2e8425c2a5af6ca1959304e8f Mon Sep 17 00:00:00 2001 From: Ruth Date: Fri, 15 May 2026 18:00:39 +0300 Subject: [PATCH 2/6] Revise EnergySaverStatus2 API documentation Updated EnergySaverStatus2 documentation to reflect changes in API behavior and requirements for Windows 11, 24H2. Clarified enum descriptions and fixed formatting issues. --- .../EnergySaverStatus2/EnergySaverStatus2.md | 105 +++--------------- 1 file changed, 13 insertions(+), 92 deletions(-) diff --git a/specs/EnergySaverStatus2/EnergySaverStatus2.md b/specs/EnergySaverStatus2/EnergySaverStatus2.md index 951f783a16..fd1174111a 100644 --- a/specs/EnergySaverStatus2/EnergySaverStatus2.md +++ b/specs/EnergySaverStatus2/EnergySaverStatus2.md @@ -1,22 +1,12 @@ # EnergySaverStatus2 API -| | | -|-|-| -| **Area** | OS\Windows Client and Services\Fundamentals\PH-Platform Health\Sustainability | -| **Product/Program Manager** | Ugochi Nweze (nwezeugochi) | -| **Developer** | Tobi Adebisi (adebisitobi), Ruth Waiganjo (ruthwaiganjo) | -| **API Design Representative** | Minsang Kim (mikim) | -| **ADO – Implementation** | Task 60383995 | -| **ADO – Testing** | Task 61020635 | -| **ADO – Sample** | Task 61020638 | -| **ADO – Documentation** | Task 61020649 | - # Background The existing `Microsoft.Windows.System.Power.PowerManager.EnergySaverStatus` property reports -only two states: `Off` and `On`. Starting with the Windows Germanium release, the OS Energy Saver -feature was updated to support three distinct operating modes — **Off**, **Standard**, and -**High Savings** — which are now visible to users in the Windows Settings app. +only two states: `Off` and `On`. +Starting with the Windows Germanium release, Windows 11, 24H2, the [Energy Saver](https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/energy-saver) +feature was updated to support three distinct operating modes: **Off**, **Standard**, and +**High Savings** which are now visible to users in the Windows Settings app. The original two-state API contains a bug: when Energy Saver is active in **Standard** mode (battery above 20%), `EnergySaverStatus` incorrectly reports `Off`. Only the **High Savings** @@ -26,17 +16,15 @@ This spec introduces `EnergySaverStatus2`, a new enum and associated APIs on `Microsoft.Windows.System.Power.PowerManager`, that accurately reflects all three energy saver states. The legacy `EnergySaverStatus` API is unchanged for backward compatibility. -> **Minimum OS requirement:** These APIs require a Germanium+ OS build. On earlier OS versions, +> **Minimum OS requirement:** These APIs require a Windows 11, 24H2 build. On earlier OS versions, > `IsEnergySaverStatus2Supported` returns `false` and `EnergySaverStatus2` returns `Unknown`. -# Conceptual pages (How To) - -_(This is conceptual documentation that will go to docs.microsoft.com "how to" page)_ +# Conceptual pages ## Responding to Energy Saver state changes in your app Energy Saver helps extend battery life by signaling apps to reduce resource consumption. -Starting with Windows Germanium, Energy Saver has three states that your app can respond to +Energy Saver has three states that your app can respond to with varying levels of optimization: | State | Meaning | Recommended app behavior | @@ -53,9 +41,6 @@ that may run on OS versions earlier than Germanium. On unsupported systems, the returns `Unknown` and the changed event is never raised. # API Pages - -_(Each of the following L2 sections correspond to a page that will be on docs.microsoft.com)_ - ## PowerManager.EnergySaverStatus2 property Gets the current Energy Saver v2 status for the device. @@ -64,10 +49,6 @@ Gets the current Energy Saver v2 status for the device. public static EnergySaverStatus2 EnergySaverStatus2 { get; } ``` -```cppwinrt -static EnergySaverStatus2 EnergySaverStatus2(); -``` - Use this property together with `EnergySaverStatus2Changed` to monitor power-state transitions and adjust your app's resource usage accordingly. When Energy Saver is in `Standard` mode your app should reduce non-critical background work; in `HighSavings` mode it should defer or pause @@ -126,8 +107,6 @@ switch (status) ### Remarks - Returns `Unknown` if `IsEnergySaverStatus2Supported()` returns `false`. -- This property is safe to call from background tasks and non-foreground windows. -- Does not require any special app capabilities. --- @@ -139,13 +118,6 @@ Occurs when the `EnergySaverStatus2` value changes. public static event System.EventHandler EnergySaverStatus2Changed; ``` -```cppwinrt -static winrt::event_token EnergySaverStatus2Changed( - winrt::Windows::Foundation::EventHandler const& handler); - -static void EnergySaverStatus2Changed(winrt::event_token const& token) noexcept; -``` - Subscribe to this event to receive notifications when the device transitions between Energy Saver states. When the event fires, call `PowerManager.EnergySaverStatus2` to retrieve the new value. @@ -179,28 +151,10 @@ private static void OnEnergySaverStatus2Changed(object sender, object e) PowerManager.EnergySaverStatus2Changed -= OnEnergySaverStatus2Changed; ``` -### Example – Subscribing to status changes (C++/WinRT) - -```cpp -#include - -using namespace winrt::Microsoft::Windows::System::Power; - -auto revoker = PowerManager::EnergySaverStatus2Changed( - winrt::auto_revoke, - [](auto, winrt::Windows::Foundation::IInspectable const&) - { - EnergySaverStatus2 status = PowerManager::EnergySaverStatus2(); - // Respond to new state - }); -``` - ### Remarks - The event is never raised on OS builds where `IsEnergySaverStatus2Supported()` returns `false`. -- The event is raised on the thread that registered, unless the implementation routes it through a - dispatcher — subscribe and unsubscribe on the same thread. - +- --- ## PowerManager.IsEnergySaverStatus2Supported method @@ -211,12 +165,7 @@ Returns a value indicating whether the current OS supports `EnergySaverStatus2`. public static bool IsEnergySaverStatus2Supported(); ``` -```cppwinrt -static bool IsEnergySaverStatus2Supported(); -``` - -Call this method before using `EnergySaverStatus2` or `EnergySaverStatus2Changed` when your app -may run on OS versions earlier than Germanium. On unsupported builds, the property returns + On unsupported builds, the property returns `Unknown` and the event is never raised. ### Example (C#) @@ -237,8 +186,7 @@ EnergySaverStatus2 status = PowerManager.EnergySaverStatus2; - Calling this method is optional. You can use `EnergySaverStatus2` without it; if the feature is unsupported the property safely returns `Unknown`. -- Returns `true` only on Germanium+ OS builds. - + --- ## EnergySaverStatus2 enum @@ -259,8 +207,8 @@ public enum EnergySaverStatus2 |---|---| | `Unknown` | The Energy Saver v2 status is unavailable, either because the OS does not support it or because the status has not yet been initialized. | | `Off` | Energy Saver is disabled. Apps should operate normally. | -| `Standard` | Energy Saver is active with mild performance impact acceptable. Energy saving behaviors that have mild performance impact are encouraged (for example, a sync client might reduce sync frequency). This state is returned when the user has opted into Energy Saver but battery life is not critical. | -| `HighSavings` | Energy Saver is active and maximum battery savings are preferred, even at the cost of performance. This state is returned when battery level is low and the device is not plugged in. | +| `Standard` | Energy Saver is active with mild performance impact acceptable(at battery level greater than 20%). Energy saving behaviors that have mild performance impact are encouraged (for example, a sync client might reduce sync frequency). This state is returned when the user has opted into Energy Saver but battery life is not critical. | +| `HighSavings` | Energy Saver is active and maximum battery savings are preferred, even at the cost of performance(at battery level less than or equal to 20%). This state is returned when battery level is low and the device is not plugged in. | ### Remarks @@ -279,17 +227,14 @@ public enum EnergySaverStatus2 ## Other PowerManager members For the full list of existing `PowerManager` members see -[Microsoft.Windows.System.Power.PowerManager](https://learn.microsoft.com/windows/apps/api-reference/). +[Microsoft.Windows.System.Power.PowerManager](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager?view=windows-app-sdk-1.7). # API Details - -```csharp (but really MIDL3) namespace Microsoft.Windows.System.Power { [contractversion(3)] apicontract PowerNotificationsContract{}; - // Existing EnergySaverStatus enum (unchanged) [contract(PowerNotificationsContract, 1)] enum EnergySaverStatus { @@ -303,13 +248,9 @@ namespace Microsoft.Windows.System.Power [contract(PowerNotificationsContract, 3)] enum EnergySaverStatus2 { - /// The status is unavailable or unsupported on this OS build. Unknown = 0, - /// Energy Saver is disabled. Off = 1, - /// Energy Saver is active; mild performance impact is acceptable. Standard = 2, - /// Energy Saver is active; maximum battery savings are preferred. HighSavings = 3 }; @@ -337,27 +278,7 @@ namespace Microsoft.Windows.System.Power ## Legacy API compatibility and mapping -`EnergySaverStatus2` is an additive API and does not replace `EnergySaverStatus`. Apps that -currently use `EnergySaverStatus` will continue to work unchanged. The legacy API's behavior -is not modified. - The legacy `EnergySaverStatus` has a known limitation: when Energy Saver is active in **Standard** mode (battery above 20%), it reports `Off`, meaning apps using the legacy API cannot distinguish "Energy Saver Standard active" from "Energy Saver disabled". `EnergySaverStatus2` fixes this. -## Alternative designs considered - -- **Extend the existing enum** – Adding `Standard` and `HighSavings` values to `EnergySaverStatus` - was rejected because it would be a breaking change for existing switch statements that do not - handle new enum values. -- **New PowerManager class** – Rejected in favor of additive members on the existing - `PowerManager` static class to maintain API surface consistency. - -## Related ADO tasks - -| Task | Description | -|---|---| -| 60383995 | Energy Saver on UWP: New 3P API Development and SDK Updates | -| 61020635 | Testing: Energy Saver on UWP | -| 61020638 | Sample Application(s): Energy Saver on UWP | -| 61020649 | Documentation: Energy Saver on UWP | From c359fd242123241e30a89b33872fee3f40da9110 Mon Sep 17 00:00:00 2001 From: Ruth Date: Fri, 15 May 2026 18:06:02 +0300 Subject: [PATCH 3/6] Add namespace for PowerNotificationsContract Added namespace declaration for PowerNotificationsContract. --- specs/EnergySaverStatus2/EnergySaverStatus2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specs/EnergySaverStatus2/EnergySaverStatus2.md b/specs/EnergySaverStatus2/EnergySaverStatus2.md index fd1174111a..324d0bb43d 100644 --- a/specs/EnergySaverStatus2/EnergySaverStatus2.md +++ b/specs/EnergySaverStatus2/EnergySaverStatus2.md @@ -230,6 +230,7 @@ For the full list of existing `PowerManager` members see [Microsoft.Windows.System.Power.PowerManager](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.system.power.powermanager?view=windows-app-sdk-1.7). # API Details +``` namespace Microsoft.Windows.System.Power { [contractversion(3)] From 0bd00545853bc20533ed20ac127c41ddbe3fc614 Mon Sep 17 00:00:00 2001 From: Ruth Date: Tue, 19 May 2026 16:53:06 +0300 Subject: [PATCH 4/6] Implement feedback Updated documentation to reflect changes in the Energy Saver feature, including the introduction of three modes: Off, Standard, and High Savings. Removed outdated examples and remarks related to unsupported OS builds. --- .../EnergySaverStatus2/EnergySaverStatus2.md | 112 ++++-------------- 1 file changed, 23 insertions(+), 89 deletions(-) diff --git a/specs/EnergySaverStatus2/EnergySaverStatus2.md b/specs/EnergySaverStatus2/EnergySaverStatus2.md index 324d0bb43d..fe7f61c7db 100644 --- a/specs/EnergySaverStatus2/EnergySaverStatus2.md +++ b/specs/EnergySaverStatus2/EnergySaverStatus2.md @@ -4,7 +4,7 @@ The existing `Microsoft.Windows.System.Power.PowerManager.EnergySaverStatus` property reports only two states: `Off` and `On`. -Starting with the Windows Germanium release, Windows 11, 24H2, the [Energy Saver](https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/energy-saver) +Starting with the [Windows 11, 24H2]() release, the [Energy Saver](https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/energy-saver) feature was updated to support three distinct operating modes: **Off**, **Standard**, and **High Savings** which are now visible to users in the Windows Settings app. @@ -17,7 +17,7 @@ This spec introduces `EnergySaverStatus2`, a new enum and associated APIs on states. The legacy `EnergySaverStatus` API is unchanged for backward compatibility. > **Minimum OS requirement:** These APIs require a Windows 11, 24H2 build. On earlier OS versions, -> `IsEnergySaverStatus2Supported` returns `false` and `EnergySaverStatus2` returns `Unknown`. +> `EnergySaverStatus2` returns `Unknown`. # Conceptual pages @@ -36,8 +36,7 @@ with varying levels of optimization: Use `PowerManager.EnergySaverStatus2` to read the current state and subscribe to `PowerManager.EnergySaverStatus2Changed` to respond to transitions at runtime. -Always call `PowerManager.IsEnergySaverStatus2Supported()` first if your app targets systems -that may run on OS versions earlier than Germanium. On unsupported systems, the property +On unsupported systems, the property returns `Unknown` and the changed event is never raised. # API Pages @@ -57,59 +56,40 @@ background operations entirely. ### Example – Reading the current status (C#) ```csharp +/* +Example: An app or service that periodically sends a heartbeat (ping/pong) +to a server to maintain connectivity and monitor health. The interval can +be adjusted based on the system's energy saver level to reduce power/battery usage +*/ + using Microsoft.Windows.System.Power; +// Default heartbeat interval (Normal operation) +TimeSpan heartbeatInterval = TimeSpan.FromSeconds(10); + EnergySaverStatus2 status = PowerManager.EnergySaverStatus2; + switch (status) { case EnergySaverStatus2.Off: - // Normal operation + // Normal operation: maintain default heartbeat interval (e.g., 10 sec) break; case EnergySaverStatus2.Standard: - // Reduce background activity + // Moderate savings: reduce background network activity + // (e.g., increase heartbeat interval to reduce frequency) + heartbeatInterval = TimeSpan.FromSeconds(20); break; case EnergySaverStatus2.HighSavings: - // Pause background activity - break; - case EnergySaverStatus2.Unknown: - default: - // API not supported on this OS build - break; -} -``` - -### Example – Reading the current status (C++/WinRT) - -```cpp -#include - -using namespace winrt::Microsoft::Windows::System::Power; - -EnergySaverStatus2 status = PowerManager::EnergySaverStatus2(); -switch (status) -{ - case EnergySaverStatus2::Off: - // Normal operation - break; - case EnergySaverStatus2::Standard: - // Reduce background activity - break; - case EnergySaverStatus2::HighSavings: - // Pause background activity + // Aggressive savings: reduce ping/pong traffic to the server by ~50%+ + // (e.g., double or triple the interval between heartbeats to conserve power) + heartbeatInterval = TimeSpan.FromSeconds(30); break; - case EnergySaverStatus2::Unknown: default: // API not supported on this OS build break; } ``` -### Remarks - -- Returns `Unknown` if `IsEnergySaverStatus2Supported()` returns `false`. - ---- - ## PowerManager.EnergySaverStatus2Changed event Occurs when the `EnergySaverStatus2` value changes. @@ -151,44 +131,6 @@ private static void OnEnergySaverStatus2Changed(object sender, object e) PowerManager.EnergySaverStatus2Changed -= OnEnergySaverStatus2Changed; ``` -### Remarks - -- The event is never raised on OS builds where `IsEnergySaverStatus2Supported()` returns `false`. -- ---- - -## PowerManager.IsEnergySaverStatus2Supported method - -Returns a value indicating whether the current OS supports `EnergySaverStatus2`. - -```csharp -public static bool IsEnergySaverStatus2Supported(); -``` - - On unsupported builds, the property returns -`Unknown` and the event is never raised. - -### Example (C#) - -```csharp -using Microsoft.Windows.System.Power; - -if (!PowerManager.IsEnergySaverStatus2Supported()) -{ - // Fall back to legacy EnergySaverStatus - return; -} - -EnergySaverStatus2 status = PowerManager.EnergySaverStatus2; -``` - -### Remarks - -- Calling this method is optional. You can use `EnergySaverStatus2` without it; if the feature is - unsupported the property safely returns `Unknown`. - ---- - ## EnergySaverStatus2 enum Represents the current Energy Saver mode of the device using the expanded v2 state. @@ -259,18 +201,10 @@ namespace Microsoft.Windows.System.Power static runtimeclass PowerManager { // ... existing members (unchanged) ... - - /// Gets the current Energy Saver v2 status for the device. - [contract(PowerNotificationsContract, 3)] - static EnergySaverStatus2 EnergySaverStatus2{ get; }; - - /// Occurs when the EnergySaverStatus2 value changes. - [contract(PowerNotificationsContract, 3)] - static event Windows.Foundation.EventHandler EnergySaverStatus2Changed; - - /// Returns true if this OS build supports EnergySaverStatus2; false otherwise. + [contract(PowerNotificationsContract, 3)] - static Boolean IsEnergySaverStatus2Supported(); + static EnergySaverStatus2 EnergySaverStatus2{ get; }; // Gets the current Energy Saver v2 status for the device. + static event Windows.Foundation.EventHandler EnergySaverStatus2Changed; // Occurs when the EnergySaverStatus2 value changes. }; } ``` From 109662c662871f1e2be5ab5f26fdc4658356f2f2 Mon Sep 17 00:00:00 2001 From: Ruth Waiganjo Date: Thu, 21 May 2026 15:27:16 +0300 Subject: [PATCH 5/6] specs: add deprecation notices for legacy EnergySaverStatus API Mark PowerManager.EnergySaverStatus, PowerManager.EnergySaverStatusChanged, and the EnergySaverStatus enum as deprecated in the EnergySaverStatus2 spec. Deprecation notices added in Background section, EnergySaverStatus2 enum Remarks, and Appendix/Legacy API compatibility section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/EnergySaverStatus2/EnergySaverStatus2.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/specs/EnergySaverStatus2/EnergySaverStatus2.md b/specs/EnergySaverStatus2/EnergySaverStatus2.md index fe7f61c7db..ce7ee3c343 100644 --- a/specs/EnergySaverStatus2/EnergySaverStatus2.md +++ b/specs/EnergySaverStatus2/EnergySaverStatus2.md @@ -16,6 +16,10 @@ This spec introduces `EnergySaverStatus2`, a new enum and associated APIs on `Microsoft.Windows.System.Power.PowerManager`, that accurately reflects all three energy saver states. The legacy `EnergySaverStatus` API is unchanged for backward compatibility. +> ⚠️ **Deprecation notice:** `PowerManager.EnergySaverStatus`, `PowerManager.EnergySaverStatusChanged`, +> and the `EnergySaverStatus` enum are deprecated. Use `PowerManager.EnergySaverStatus2`, +> `PowerManager.EnergySaverStatus2Changed`, and the `EnergySaverStatus2` enum instead. + > **Minimum OS requirement:** These APIs require a Windows 11, 24H2 build. On earlier OS versions, > `EnergySaverStatus2` returns `Unknown`. @@ -156,6 +160,9 @@ public enum EnergySaverStatus2 - `EnergySaverStatus2` may be extended with additional values in future OS releases. Your code should handle unknown enum values gracefully (for example, with a `default` case in a `switch`). +- The legacy `EnergySaverStatus` enum, `PowerManager.EnergySaverStatus` property, and + `PowerManager.EnergySaverStatusChanged` event are deprecated. Migrate to `EnergySaverStatus2`, + `PowerManager.EnergySaverStatus2`, and `PowerManager.EnergySaverStatus2Changed`. - The enum values map to the legacy `EnergySaverStatus` as follows: | `EnergySaverStatus2` | Legacy `EnergySaverStatus` | @@ -213,7 +220,11 @@ namespace Microsoft.Windows.System.Power ## Legacy API compatibility and mapping -The legacy `EnergySaverStatus` has a known limitation: when Energy Saver is active in **Standard** +> ⚠️ **Deprecation notice:** `PowerManager.EnergySaverStatus`, `PowerManager.EnergySaverStatusChanged`, +> and the `EnergySaverStatus` enum are deprecated. Use `PowerManager.EnergySaverStatus2`, +> `PowerManager.EnergySaverStatus2Changed`, and the `EnergySaverStatus2` enum instead. + +The legacy `EnergySaverStatus` has a known limitation:when Energy Saver is active in **Standard** mode (battery above 20%), it reports `Off`, meaning apps using the legacy API cannot distinguish "Energy Saver Standard active" from "Energy Saver disabled". `EnergySaverStatus2` fixes this. From 65daec5edb37b9d2d590a5d9be2952b24a8d83f1 Mon Sep 17 00:00:00 2001 From: Ruth Date: Thu, 21 May 2026 15:34:25 +0300 Subject: [PATCH 6/6] Update deprecation notice for EnergySaverStatus Clarify the limitation of the legacy EnergySaverStatus and its impact on app behavior. --- specs/EnergySaverStatus2/EnergySaverStatus2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/EnergySaverStatus2/EnergySaverStatus2.md b/specs/EnergySaverStatus2/EnergySaverStatus2.md index ce7ee3c343..132184238e 100644 --- a/specs/EnergySaverStatus2/EnergySaverStatus2.md +++ b/specs/EnergySaverStatus2/EnergySaverStatus2.md @@ -224,7 +224,7 @@ namespace Microsoft.Windows.System.Power > and the `EnergySaverStatus` enum are deprecated. Use `PowerManager.EnergySaverStatus2`, > `PowerManager.EnergySaverStatus2Changed`, and the `EnergySaverStatus2` enum instead. -The legacy `EnergySaverStatus` has a known limitation:when Energy Saver is active in **Standard** +The legacy `EnergySaverStatus` has a known limitation: when Energy Saver is active in **Standard** mode (battery above 20%), it reports `Off`, meaning apps using the legacy API cannot distinguish "Energy Saver Standard active" from "Energy Saver disabled". `EnergySaverStatus2` fixes this.