API design for power state, activation, and instancing#577
Merged
andreww-msft merged 21 commits intomainfrom Mar 24, 2021
Merged
API design for power state, activation, and instancing#577andreww-msft merged 21 commits intomainfrom
andreww-msft merged 21 commits intomainfrom
Conversation
* Add files via upload Added AppLifecycle State/Power Notifications API spec. * Update AppLifecycle StateNotifications.md * Update AppLifecycle StateNotifications.md
* Add files via upload * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md * Update AppLifecycle Activation.md (#401) * Update AppLifecycle Activation.md
* Add files via upload * Update AppLifecycle SingleMulti-Instancing.md
Removed toast sample snippet.
* 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.
ghost
added
the
Contributor
|
Nit: Can we get a better PR title next time? 😋 |
Member
|
We should run this through the API review group; I'll set up time for Tuesday 3/16 1-2pm Seattle time. And if I can figure it out, I'll drop a link for folks to join a Teams call. |
jonwis
changed the title
hulumane
reviewed
Mar 12, 2021
| | API | Description | | ||
| | ------------------------------------------------------------ | ------------------------------------------------------------ | | ||
| | enum class ExtendedActivationKind<br/>{<br/> /\* all existing platform ActivationKind values, \*/<br/> ExtensionBase = 5000,<br/> /\* new Reunion ExtendedActivationKind values\*/<br/>}; | This enum is based off the platform [ActivationKind](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.Activation.ActivationKind). All platform ActivationKind values are cloned to this class. Then, we set a high-value **ExtensionBase** value which is well above the existing highest ActivationKind value (1026), to allow for new values to be added to the platform. Going forward, any new platform values will also be added to the new enum, plus any new values that are only defined in the new enum. | | ||
| | class ActivationArguments<br/>{<br/>public:<br/> ExtendedActivationKind Kind ;<br/> IInspectable Data;<br/>}; | The platform defines [IActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.Activation.IActivatedEventArgs), which exposes a Kind property. Apps can get an IActivatedEventArgs reference, examine the Kind and then cast the reference to the specific concrete class type that implements IActivatedEventArgs. This enables generic functions such as GetActivatedEventArgs and the Activated event handler, which provide the app with an IActivatedEventArgs that the app can then convert to a specific concrete type. However, IActivatedEventArgs also defines other properties that are only useful in a UWP context. In addition, we need a mechanism that supports both platform ActivationKinds and also Reunion-only ExtendedActivationKinds and their corresponding concrete class types. <br />The new ActivationArguments type serves this purpose: the app can examine the Kind, and then cast the Data property to the specific concrete type (which can be either a platform IActivatedEventArgs concrete class, or a Reunion class).<br />**Kind** is the enum value that indicates the kind of activation this object represents.<br />**Data** can be cast to a specific concrete class corresponding to Kind. | |
Member
There was a problem hiding this comment.
So if we need to add a new PushActivatedKind which isn't part of Windows.Foundation today, we should be able to technically throw this into the IInspectable ref over here correct and add a new ActivationKindExtension?
@danielayala94 FYI
Contributor
There was a problem hiding this comment.
@hulumane Take a look at my instancing topic branch for a better idea of where the implementation is going at least. It should match this, but has some examples.
hulumane
reviewed
Mar 12, 2021
| | ------------------------------------------------------------ | ------------------------------------------------------------ | | ||
| | enum class ExtendedActivationKind<br/>{<br/> /\* all existing platform ActivationKind values, \*/<br/> ExtensionBase = 5000,<br/> /\* new Reunion ExtendedActivationKind values\*/<br/>}; | This enum is based off the platform [ActivationKind](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.Activation.ActivationKind). All platform ActivationKind values are cloned to this class. Then, we set a high-value **ExtensionBase** value which is well above the existing highest ActivationKind value (1026), to allow for new values to be added to the platform. Going forward, any new platform values will also be added to the new enum, plus any new values that are only defined in the new enum. | | ||
| | class ActivationArguments<br/>{<br/>public:<br/> ExtendedActivationKind Kind ;<br/> IInspectable Data;<br/>}; | The platform defines [IActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.Activation.IActivatedEventArgs), which exposes a Kind property. Apps can get an IActivatedEventArgs reference, examine the Kind and then cast the reference to the specific concrete class type that implements IActivatedEventArgs. This enables generic functions such as GetActivatedEventArgs and the Activated event handler, which provide the app with an IActivatedEventArgs that the app can then convert to a specific concrete type. However, IActivatedEventArgs also defines other properties that are only useful in a UWP context. In addition, we need a mechanism that supports both platform ActivationKinds and also Reunion-only ExtendedActivationKinds and their corresponding concrete class types. <br />The new ActivationArguments type serves this purpose: the app can examine the Kind, and then cast the Data property to the specific concrete type (which can be either a platform IActivatedEventArgs concrete class, or a Reunion class).<br />**Kind** is the enum value that indicates the kind of activation this object represents.<br />**Data** can be cast to a specific concrete class corresponding to Kind. | | ||
| | class AppInstance<br/>{<br/>public:<br/> static AppInstance GetCurrent();<br/> static IVector<AppInstance> GetInstances();<br/> static AppInstance FindOrRegisterForKey(string key);<br/> void UnregisterKey(string key);<br/> void RedirectTo(ActivationArguments args);<br/> ActivationArguments GetActivatedEventArgs();<br/> static void Activated(EventHandler<ActivationArguments> const& handler);<br/> string Key;<br/> bool IsCurrent;<br /> int ProcessId;<br/>}; | New class. This is the major new class exposed in the AppLifecycle component in Reunion. <br />**GetCurrent** returns an AppInstance that represents the current app instance.<br />**GetInstances** returns a collection of all running instances of the app. Note: the existing platform [AppInstance.GetInstances](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.appinstance.getinstances) only returns instances that have explicitly registered for multi-instance redirection. However, the new AppInstance Reunion class will provide an API surface for all manner of app-instance-related behaviors, not restricted to instance redirection. For this reason, Reunion will maintain a list of all running instances and will not require explicit registration by the app.<br />**FindOrRegisterForKey** enables an app to register an app-defined key for the current instance, or if another instance has already registered that key, then return that other instance instead. This is similar to the platform [AppInstance.FindOrRegisterInstanceForKey](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.appinstance.findorregisterinstanceforkey) except that that implementation is specific to instance redirection, whereas the Reunion design allows for the app to register a key for any reason.<br />**UnregisterKey** unregisters a given key for this instance. The existing platform behavior is specific to instance redirection, and unregistering the key unregisters that instance for redirection (and removes it from the platform's collection of registered instances). In the Reunion design, unregistering a key simply removes the key for this instance; it does not have any effect on instance redirection, nor does it remove this instance from the collection that Reunion is maintaining of all running instances. <br />**RedirectTo** enables an instance of the app to redirect the current activation request to another instance. This is very similar to the existing platform [AppInstance.RedirectActivationTo](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.appinstance.redirectactivationto) method, except that the Reunion implementation allows the app to pass an ActivationArguments payload, thus opening the scope to allow the app to modify or replace the activation arguments that the target instance will receive.<br />**GetActivatedEventArgs** provides similar behavior as the existing platform [AppInstance.GetActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.appinstance.getactivatedeventargs), except that it returns a new ActivationArguments object for the current activation instead of an IActivatedEventArgs. <br />**Key** an app-defined string value that can be used to identify an instance for redirection purposes.<br />**IsCurrent** indicates whether this instance object represents the current instance of the app or a different instance.<br />**ProcessId** the process ID of the instance.<br/> | |
Member
There was a problem hiding this comment.
What is the Activated Event in AppInstance specifically for? I think its missing a description in the second column of the table
ChrisGuzak
reviewed
Mar 16, 2021
Member
ChrisGuzak
left a comment
ChrisGuzak
left a comment
There was a problem hiding this comment.
"protocol" is a misnomer that has persisted based on its historic use. "uri scheme" is the correct terminology. it is hard to resist "protocol" given how widely it is used in our documentation and APIs, but I think this should be called out at some point "by protocol we mean uri scheme".
Contributor
|
@jonwis Friendly reminder re: teams URL. |
oldnewthing
reviewed
Mar 16, 2021
oldnewthing
reviewed
Mar 16, 2021
| @@ -0,0 +1 @@ | |||
|
|
|||
Member
There was a problem hiding this comment.
This file is unnecessary because the directory is nonempty.
| @@ -0,0 +1,506 @@ | |||
| # AppLifecycle - Rich Activation | |||
Contributor
There was a problem hiding this comment.
Markdown tip: rather than making this an H1, put "===" on the next line. Then reduce the heading level by one in all the headings below
jonwis
reviewed
Mar 16, 2021
Resolved a number of review comments.
Fixed most review comments.
Additional review fixes.
wjk
pushed a commit
to SunburstApps/ProjectReunion
that referenced
this pull request
Apr 12, 2021
* 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merge AppLifecycle API specs to main.