From b73b26602de3e1b67d8e3fbdf89c832221bece18 Mon Sep 17 00:00:00 2001 From: andreww-msft <30507740+andreww-msft@users.noreply.github.com> Date: Thu, 28 Jan 2021 11:37:17 -0800 Subject: [PATCH] Update AppLifecycle Activation.md --- .../Activation/AppLifecycle Activation.md | 25 ++++--------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/specs/AppLifecycle/Activation/AppLifecycle Activation.md b/specs/AppLifecycle/Activation/AppLifecycle Activation.md index edbd98baf4..f49bd665cc 100644 --- a/specs/AppLifecycle/Activation/AppLifecycle Activation.md +++ b/specs/AppLifecycle/Activation/AppLifecycle Activation.md @@ -30,7 +30,7 @@ This part of Reunion AppLifecycle makes rich UWP activation functionality availa The first release focuses on the most commonly-used rich activation kinds. The AppLifecycle component will provide a converged GetActivatedEventArgs API which will get all args, regardless of activation kind, effectively merging in the functionality of GetCommandLineArgs/GetCommandLineW. It will also be decoupled from multi-instancing. -Of the 44 UWP activation kinds, 5 of the most commonly-used kinds are also supported for Desktop Bridge and Windows [reg-free WinRT](https://blogs.windows.com/windowsdeveloper/2019/04/30/enhancing-non-packaged-desktop-apps-using-windows-runtime-components/) apps. The AppLifecycle implementation is based on this set. Some activation kinds require prior registration, others do not. The target list for v1 is as follows: +Of the 44 UWP activation kinds, 4 of the most commonly-used kinds are also supported for Desktop Bridge and Windows [reg-free WinRT](https://blogs.windows.com/windowsdeveloper/2019/04/30/enhancing-non-packaged-desktop-apps-using-windows-runtime-components/) apps. The AppLifecycle implementation is based on this set. Some activation kinds require prior registration, others do not. The target list for v1 is as follows: | Activation kind | Description | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -38,7 +38,7 @@ Of the 44 UWP activation kinds, 5 of the most commonly-used kinds are also suppo | File | The app is activated when the user double-clicks a registered file, or when a caller calls ShellExecute or LaunchFileAsync on a registered file. | | Protocol | Activated via ShellExecute or LaunchUriAsync, or by specifying a protocol string on a command-line. | | StartupTask | The app starts on user log-in - either registered in the registry, or via shortcuts in a well-known startup folder. | -| ToastNotification | The app sends a toast, the user responds, and this activates the app. | + ### Activation registration @@ -62,7 +62,7 @@ Providing APIs for activation registration means that an app can register at any Each registered filetype must be unique for the app. To allow for the case where the app determines the combination of options at runtime (and potentially changes the combinations at a later time), where an app registers the same filetype multiple times, the latest registration is honored and overwrites any previous registrations. -For startup and toast activation, only one of each of these is allowed. If an app attempts to register either of these more than once, the latest registration is honored and overwrites any previous registrations. +For startup activation, only one of each of these is allowed. If an app attempts to register either of these more than once, the latest registration is honored and overwrites any previous registrations. ```c++ int APIENTRY wWinMain( @@ -109,10 +109,6 @@ void RegisterForActivation() // Register for startup activation. ActivationRegistrationManager::RegisterForStartupActivation( "MyTaskId", true, "Contoso Photo Viewer"); - - // Register for toast activation, - // where g_ToastGuid is defined as a static guid. - ActivationRegistrationManager::RegisterForToastActivation("Contoso Toast"); } ``` ### Get rich activation objects @@ -146,18 +142,13 @@ void RespondToActivation() auto startupArgs = args.as(); DoSomethingWithStartupArgs(startupArgs.TaskId()); } - else if (kind == ActivationKind::ToastNotification) - { - auto toastArgs = args.as(); - DoSomethingWithToastArgs(toastArgs.Argument()); - } } } ``` ### Unregister The primary requirement is to be able to register for the supported activation kinds dynamically. A secondary requirement is to be able to unregister for any or all of these. -For filetype associations, the app can register for multiple filetypes. We will provide the ability to unregister one or more filetypes. For protocol registrations, the app can register for multiple protocols individually, so the API will also enable the app to unregister for each of these individually. For each of the other supported activation kinds, there can be at most one registration for the app. Therefore, the app does not need to pass any parameters in order to unregister for these activation kinds. +For filetype associations, the app can register for multiple filetypes. We will provide the ability to unregister one or more filetypes. For protocol registrations, the app can register for multiple protocols individually, so the API will also enable the app to unregister for each of these individually. For the other supported activation kinds, there can be at most one registration for the app. Therefore, the app does not need to pass any parameters in order to unregister for these activation kinds. ```c++ void UnregisterForActivation() @@ -168,7 +159,6 @@ void UnregisterForActivation() ActivationRegistrationManager::UnregisterForProtocolActivation("foo"); ActivationRegistrationManager::UnregisterForStartupActivation(); - ActivationRegistrationManager::UnregisterForToastActivation(); } ```
@@ -187,7 +177,6 @@ This spec proposes 6 new classes and one enum: | class FileActivatedEventArgs | Based on the existing [FileActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.activation.fileactivatedeventargs). | | class ProtocolActivatedEventArgs | Based on the existing [ProtocolActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.activation.protocolactivatedeventargs). | | class StartupTaskActivatedEventArgs | Based on the existing [StartupTaskActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.activation.startuptaskactivatedeventargs). | -| class ToastNotificationActivatedEventArgs | Based on the existing [ToastNotificationActivatedEventArgs](https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.activation.toastnotificationactivatedeventargs). | | enum ActivationKind | Based on the existing [ActivationKind](https://docs.microsoft.com/en-us/uwp/api/Windows.ApplicationModel.Activation.ActivationKind). | ### Properties, methods and sub-types @@ -208,8 +197,6 @@ The following table lists the existing APIs that will be implemented in AppLifec | interface IProtocolActivatedEventArgs
{
Uri Uri;
}
| **Uri** is the minimum required property for this activation type. | | class StartupTaskActivatedEventArgs | Implements IActivatedEventArgs, plus the following: | | interface IStartupTaskActivatedEventArgs
{
string TaskId;
}
| **TaskId** is an app-defined value; the app can use this later in the StartupTask API to request enabling or disabling of the startup behavior. | -| class ToastNotificationActivatedEventArgs | Implements IActivatedEventArgs, plus the following: | -| interface IToastNotificationActivatedEventArgs
{
string Argument;
ValueSet UserInput;
}
| **Argument** is the minimum required property for this activation type.
**UserInput** consists of pairs of keys and values, in which the keys are the identifiers for the elements for which the user provided input and the values represent the input from the user. For elements that specify that the type of the input is text, the value is the string that the user specified. For elements that specify that the type of the input is an item that the user selects from a predefined list, the value is the identifier for the item that the user selected. | Also see the related API Spec AppLifecycle - Single/Multi-instancing, which describes the new Activated event. An app can use GetActivatedEventArgs even if it is not choosing to use multi-instance redirection. If it is using multi-instance redirection, then it can use GetActivatedEventArgs and also handle the Activated event. @@ -220,7 +207,7 @@ The new RegisterForXXXActivation methods will be exposed as static methods from The aim is that the app would call any of these RegisterForXXXActivation methods at any time dynamically from the app itself. For v1, this API does not support calling from the app's installer. For filetype and protocol, the app can call the RegisterForXXXActivation method multiple times, each time providing different filetype names or different protocol names. These registrations would be cumulative, so long as the parameters are different. If the app tries to register for the same filetype name or the same protocol multiple times, this is idempotent (there's only one registration per unique filetype name or protocol name; no error for multiple identical registrations, any new values supplied for the same registration overwrite any old values). -Similarly, if the app registers multiple times for startup or toast, this is also idempotent (a single registration, no error, any new values supplied overwrite any old values). +Similarly, if the app registers multiple times for startup, this is also idempotent (a single registration, no error, any new values supplied overwrite any old values). | API | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -228,7 +215,6 @@ Similarly, if the app registers multiple times for startup or toast, this is als | static void RegisterForFileTypeActivation(
string supportedFileTypes[],
string logo,
int? index,
string? supportedVerbs[]
); | **supportedFileTypes**: one or more supported filetypes, specified by the file extension including the leading ".", eg ".docx".
**logo**: used in File Explorer for this filetype if this app is the default handler. In UWP this is a package-relative path to an image resource file. In Win32 registry-based filetype registrations, it's a filepath to a binary file plus a resource index. The caller can pass either.
**index**: optional - if this is not supplied, we will interpret the logo string as a package-relative path to an image resource file. If index is supplied, we will interpret the logo string as a binary filepath, and the index as the resource index in that binary.
**supportedVerbs**: optional - zero or more app-defined verbs. Each verb is added to the File Explorer context menu when a registered file is right-clicked; and the selected verb is passed to the app as the FileActivatedEventArgs::Verb property. | | static void RegisterForProtocolActivation(
string name
); | **name**: the protocol identifier, eg "foo" or "https". | | static void RegisterForStartupActivation(
string taskId,
bool isEnabled,
string displayName
); | **taskId**: a string identifier which the app can use in the StartupTask API to request enabling or disabling of the startup behavior.
**isEnabled**: enables the startup behavior without a user prompt, so long as the user has activated the app at least once. Consistent with existing Desktop Bridge behavior.
**displayName**: used in the Settings - Apps - Startup page. | -| static void RegisterForToastActivation(
string displayName
); | **displayName**: used in the toast header, and in the Action Center. | ### Activation unregistration The new API will include UnregisterForXXXActivation methods for each of the supported activation kinds. @@ -238,7 +224,6 @@ The new API will include UnregisterForXXXActivation methods for each of the supp | static void UnregisterForFileTypeActivation(
string fileTypes[]
); | **fileTypes**: one or more filetypes that the caller wants to unregister. | | static void UnregisterForProtocolActivation(
string name
); | **name**: the previously-registered protocol identifier, eg "foo" or "https". | | static void UnregisterForStartupActivation(); | | -| static void UnregisterForToastActivation(); | |