Added AppLifecycle State/Power Notifications API spec. by andreww-msft · Pull Request #278 · microsoft/WindowsAppSDK

andreww-msft · 2020-11-06T21:51:33Z

No description provided.

Added AppLifecycle State/Power Notifications API spec.

jonwis

Looking good. Thanks for using the two-branch review model so we can refine the spec first here before we do the pull from user/andreww-msft into main.

jonwis · 2020-11-08T00:32:29Z

@@ -0,0 +1,247 @@
+# AppLifecycle - State Notifications
+
+Reunion introduces a new AppLifecycle component that provides a core set of functionality related to app activation and lifecycle. Much of this functionality is directly equivalent - or very similar - to existing functionality within the platform. However, there is value in abstracting this functionality so that all app types can use it, delivering it out-of-band from the OS, and making it available as open-source. The totality of AppLifecycle features in v1 is as follows (additional features may be added in later releases):


General note - please wrap your markdown at 80 characters. VSCode and others have extensions that will do this for you, like Prettier and Markdown-all-in-one.

jonwis · 2020-11-08T00:33:51Z

@@ -0,0 +1,247 @@
+# AppLifecycle - State Notifications


Note on file paths - Maybe move this under specs/AppLifecycle directly so it's specs/AppLifecycle/PowerStateNotification.md or similar.

jonwis · 2020-11-08T00:34:22Z

+
+This spec addresses the System State and Power Notifications APIs in the component.
+
+<br>


Remove <br>

jonwis · 2020-11-08T00:35:19Z

+- [RegisterPowerSettingNotification](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registerpowersettingnotification) uses a Windows message-based model. When the app registers for notifications, the system will send out WM_POWERBROADCAST messages.
+- [PowerSettingRegisterNotification](https://docs.microsoft.com/en-us/windows/win32/api/powersetting/nf-powersetting-powersettingregisternotification) uses a callback model. When the app registers for notifications, it supplies a pointer to a callback function, and the system will call back to this function instead of sending messages.
+
+Classic Win32 apps can use either the WM model and/or the callback model. The callback model is more consistent with other app types - including not only modern UWP apps, but also traditional MFC, Winforms and WPF apps. Given this, since all app types can work with the callback model, but only classic Win32 apps use the WM model, the Reunion API will use the callback model for Cobalt. Additional WM-based behavior can be added in a later release, if customer demand indicates it would provide significant benefit.


Might also call out that the callback model does not prescribe a windowing or threading model, which is better for headless/background components.

jonwis · 2020-11-08T00:37:23Z

+
+The net is that the Reunion PowerManager API will be a combination of WinRT PowerManager and Win32 PowerSettingRegisterNotification.
+
+


In this section, maybe call out explicitly that we're defining new WinRT types (with their full names, like Microsoft.ApplicationModel.PowerManager) that provide event handlers for apps to use.

jonwis · 2020-11-08T00:47:08Z

+Reunion AppLifecycle will not bring this function forward in its current form. Instead, AppLifecycle will bring the functionality forward using the PowerManager pattern for the additional PowerSettingRegisterNotification notifications:
+-	Instead of a single register function that takes a GUID, the new API will expose multiple new events, mapping to each of the GUIDs that are brought forward. Not all GUIDs will be brought forward, as some of them are already covered by PowerManager events.
+-	For Reunion v1, the target consumers of the new APIs are scoped to apps not services - this eliminates the need for the Flags parameter. 
+-	The new API will adopt the PowerManager pattern for registering and unregistering callbacks, which eliminates the need for the register/unregister handles.


Please don't use tabs; just - The new ...

jonwis · 2020-11-08T00:48:02Z

+
+|     New Classes and Enums                                                    |     Description                                                               |
+|------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
+|     enum   BatteryStatus {NotPresent, Discharging, Idle, Charging}           |     Clone   of Windows.System.Power.BatteryStatus.                            |


Some of these ended up with extra spacing between Clone and of for instance. Not a huge deal, but in the new names column you'll want to shorten to enum BatteryStatus for instance

jonwis · 2020-11-08T00:48:15Z

+|     static   SystemAwayModeStatus SystemAwayModeStatus                   |     Readonly   property, gets the entering/exiting status of the system away mode.    |
+|     static   event EventHandler<object> SystemAwayModeStatusChanged      |     Event   raised when the system is entering or exiting away mode.                  |
+
+<br>


jonwis · 2020-11-08T00:48:56Z

+
+<br>
+<br>
+


Do put a dump of the IDL of the new type, including its full namespace name, here. Just like we would have done in a product API spec.

jonwis · 2020-11-08T00:53:32Z

+}
+```
+
+In the app-defined callback, the app can do whatever it likes. Typically, it would fetch the current status of the particular feature (that is, the battery status, power supply status, energy saver status, and so on), and use that information to form its decision. For example, if battery is at a low power state and discharging, the app might choose to defer any non-critical background work, in the interests of being a good power/battery citizen.


Somewhere in here, or one of the other docs, we need a note about the threading model for the callbacks. As this sample explicitly mixes window threads and WinRT callbacks, we should be clear that the OnRemaining... will be invoked on the same thread that handles the incoming system thread. It may be up to the app to send itself a window message to hop back onto the window thread, or use a marshalable callback object so COM magically transitions the call back to this thread's [A]STA.

@jeffstall filed microsoft/xlang#673 which goes into some of the details.

* Create .gitkeep * Create .gitkeep * Create .gitkeep * Create .gitkeep * Added AppLifecycle State/Power Notifications API spec. (#278) * Add files via upload Added AppLifecycle State/Power Notifications API spec. * Update AppLifecycle StateNotifications.md * Update AppLifecycle StateNotifications.md * Added AppLifecycle Activation API spec. (#279) * Add files via upload * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md (#401) * Update AppLifecycle Activation.md * Added AppLifecycle Single/Multi-instancing API spec. (#280) * Add files via upload * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md (#434) * Update AppLifecycle Activation.md Added the exePath parameter to Register/Unregister methods. * Update AppLifecycle Activation.md Fixed the array declarations. * Update AppLifecycle Activation.md Changed RegisterForStartupActivation isEnabled to isDisabled. * Update AppLifecycle Activation.md Updated Startup registration to remove displayName, and add taskId to unregister. * Update AppLifecycle Activation.md Fixed array declarations again. * Update AppLifecycle Activation.md Removed isEnabled from StartupTask registration, as it makes no sense. * Update AppLifecycle Activation.md Fixed typo. * Update AppLifecycle Activation.md Dropped all the function overloads, added DisplayName to File & Protocol, added Logo to Protocol. * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md Renamed to AppInstance, and updated ExtendedActivationKind. * Update AppLifecycle SingleMulti-Instancing.md Renamed AppLifecycle to AppInstance, updated instancing APIs. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md Made GetActivatedEventArgs an instance method instead of static. * Update AppLifecycle SingleMulti-Instancing.md Made GetActivatedEventArgs an instance method not static. * Update AppLifecycle Activation.md Added ProcessId. * Update AppLifecycle SingleMulti-Instancing.md Added ProcessId. * Update AppLifecycle Activation.md Added ProcessId example. * Tidy up app activation * Tidy up instancing * Tidy up power state * Update AppLifecycle Activation.md Resolved a number of review comments. * Update AppLifecycle SingleMulti-Instancing.md Fixed most review comments. * Update AppLifecycle SingleMulti-Instancing.md Additional review fixes. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle StateNotifications.md Updated per review comments. Co-authored-by: Jon Wiswall <jonwis@microsoft.com>

* Create .gitkeep * Create .gitkeep * Create .gitkeep * Create .gitkeep * Added AppLifecycle State/Power Notifications API spec. (microsoft#278) * Add files via upload Added AppLifecycle State/Power Notifications API spec. * Update AppLifecycle StateNotifications.md * Update AppLifecycle StateNotifications.md * Added AppLifecycle Activation API spec. (microsoft#279) * Add files via upload * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md (microsoft#401) * Update AppLifecycle Activation.md * Added AppLifecycle Single/Multi-instancing API spec. (microsoft#280) * Add files via upload * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md (microsoft#434) * Update AppLifecycle Activation.md Added the exePath parameter to Register/Unregister methods. * Update AppLifecycle Activation.md Fixed the array declarations. * Update AppLifecycle Activation.md Changed RegisterForStartupActivation isEnabled to isDisabled. * Update AppLifecycle Activation.md Updated Startup registration to remove displayName, and add taskId to unregister. * Update AppLifecycle Activation.md Fixed array declarations again. * Update AppLifecycle Activation.md Removed isEnabled from StartupTask registration, as it makes no sense. * Update AppLifecycle Activation.md Fixed typo. * Update AppLifecycle Activation.md Dropped all the function overloads, added DisplayName to File & Protocol, added Logo to Protocol. * Update AppLifecycle SingleMulti-Instancing.md Removed toast sample snippet. * Update AppLifecycle Activation.md Renamed to AppInstance, and updated ExtendedActivationKind. * Update AppLifecycle SingleMulti-Instancing.md Renamed AppLifecycle to AppInstance, updated instancing APIs. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md Made GetActivatedEventArgs an instance method instead of static. * Update AppLifecycle SingleMulti-Instancing.md Made GetActivatedEventArgs an instance method not static. * Update AppLifecycle Activation.md Added ProcessId. * Update AppLifecycle SingleMulti-Instancing.md Added ProcessId. * Update AppLifecycle Activation.md Added ProcessId example. * Tidy up app activation * Tidy up instancing * Tidy up power state * Update AppLifecycle Activation.md Resolved a number of review comments. * Update AppLifecycle SingleMulti-Instancing.md Fixed most review comments. * Update AppLifecycle SingleMulti-Instancing.md Additional review fixes. * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle SingleMulti-Instancing.md * Update AppLifecycle StateNotifications.md Updated per review comments. Co-authored-by: Jon Wiswall <jonwis@microsoft.com>

Add files via upload

58c1b8b

Added AppLifecycle State/Power Notifications API spec.

ghost added the needs-triage label Nov 6, 2020

andreww-msft requested review from brialmsft and jonwis November 8, 2020 00:09

jonwis requested changes Nov 8, 2020

View reviewed changes

andreww-msft requested a review from kanismohammed-zz November 10, 2020 23:32

Update AppLifecycle StateNotifications.md

150d2f2

EHO-makai removed the needs-triage label Dec 2, 2020

Update AppLifecycle StateNotifications.md

18f3f40

andreww-msft merged commit b235505 into user/andreww-msft Jan 29, 2021

andreww-msft deleted the andreww-msft-patch-1 branch January 29, 2021 21:16

		@@ -0,0 +1,247 @@
		# AppLifecycle - State Notifications

		Reunion introduces a new AppLifecycle component that provides a core set of functionality related to app activation and lifecycle. Much of this functionality is directly equivalent - or very similar - to existing functionality within the platform. However, there is value in abstracting this functionality so that all app types can use it, delivering it out-of-band from the OS, and making it available as open-source. The totality of AppLifecycle features in v1 is as follows (additional features may be added in later releases):


		This spec addresses the System State and Power Notifications APIs in the component.

		<br>


		The net is that the Reunion PowerManager API will be a combination of WinRT PowerManager and Win32 PowerSettingRegisterNotification.

Conversation

andreww-msft commented Nov 6, 2020

Uh oh!

jonwis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants