• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.ability.CompletionHandler (Application Launch Result Handler)
2<!--Kit: Ability Kit-->
3<!--Subsystem: Ability-->
4<!--Owner: @littlejerry1; @yangxuguang-huawei; @Luobniz21-->
5<!--Designer: @ccllee1-->
6<!--Tester: @lixueqing513-->
7<!--Adviser: @huipeizi-->
8
9**CompletionHandler** is an optional parameter of [StartOptions](js-apis-app-ability-startOptions.md) and is used to handle the result of an application launch request.
10
11
12> **NOTE**
13>
14> - The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.
15>
16> - The APIs of this module can be used only in the stage model.
17
18
19## Constraints
20
21Currently, this module can be used in the following APIs:
22- [startAbility](js-apis-inner-application-uiAbilityContext.md#startability-2)
23- [startAbilityForResult](js-apis-inner-application-uiAbilityContext.md#startabilityforresult-2)
24- [UIAbilityContext.openAtomicService](js-apis-inner-application-uiAbilityContext.md#openatomicservice12)
25- [UIExtensionContext.openAtomicService](js-apis-inner-application-uiExtensionContext.md#openatomicservice12)
26
27<!--Del-->
28- [startAbilityForResultWithAccount](js-apis-inner-application-uiAbilityContext-sys.md#startabilityforresultwithaccount-2)
29- [startAbilityWithAccount](js-apis-inner-application-uiAbilityContext-sys.md#startabilitywithaccount-2)
30- [startRecentAbility](js-apis-inner-application-uiAbilityContext-sys.md#startrecentability-2)
31- [startAbilityAsCaller](js-apis-inner-application-uiAbilityContext-sys.md#startabilityascaller10-2)
32- [ServiceExtensionContext.openAtomicService](js-apis-inner-application-serviceExtensionContext-sys.md#serviceextensioncontextopenatomicservice18)
33<!--DelEnd-->
34
35## Modules to Import
36
37```ts
38import { CompletionHandler } from '@kit.AbilityKit';
39```
40
41## CompletionHandler
42
43CompletionHandler provides two callback functions, [onRequestSuccess](#onrequestsuccess) and [onRequestFailure](#onrequestfailure), to handle the results of successful and failed application launch requests, respectively.
44
45### onRequestSuccess
46
47onRequestSuccess(elementName: ElementName, message: string): void
48
49Called when the application is successfully launched.
50
51**Atomic service API**: This API can be used in atomic services since API version 20.
52
53**System capability**: SystemCapability.Ability.AbilityRuntime.Core
54
55**Parameters**
56
57| Name| Type| Mandatory| Description|
58| -------- | -------- | -------- | -------- |
59| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes| **ElementName** information used to identify the target application. <br>- Typically, **ElementName** includes only **abilityName** and **bundleName**. The presence of **moduleName** and **deviceId** depends on whether the caller provides them. **shortName** and **uri** are empty.<br>- If the target being launched is an atomic service, **ElementName** contains only **bundleName**.|
60| message | string | Yes| Message displayed when the application is successfully launched. This message is in JSON format, as follows:<br>{<br>&emsp;"errMsg": "Succeeded."<br>}<br>|
61
62**Example**
63
64See [Usage of CompletionHandler](#usage-of-completionhandler).
65
66### onRequestFailure
67
68onRequestFailure(elementName: ElementName, message: string): void
69
70Called when the application fails to be launched.
71
72**Atomic service API**: This API can be used in atomic services since API version 20.
73
74**System capability**: SystemCapability.Ability.AbilityRuntime.Core
75
76**Parameters**
77
78| Name| Type| Mandatory| Description|
79| -------- | -------- | -------- | -------- |
80| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes| **ElementName** information used to identify the target application.<br>- Typically, **ElementName** includes only **abilityName** and **bundleName**. The presence of **moduleName** and **deviceId** depends on whether the caller provides them. **shortName** and **uri** are empty.<br>- If the target being launched is an atomic service, **ElementName** contains only **bundleName**.<br>- **ElementName** information cannot be obtained if the implicit startup fails.|
81| message | string | Yes| Message displayed when the application fails to be launched. This message is in JSON format, as follows:<br>{<br>&emsp;"errMsg": "xxx"<br>}<br>The value of *xxx* is described as follows:<br>Failed to call \<api-name\>: An error occurs when calling the API. \<api-name\> is the specific API name, for example, **startAbility** or **openAtomicService**.<br>User refused redirection: The user has closed the application redirection dialog box.<br>User closed the implicit startup picker: The user has closed the dialog box for selecting an application for implicit startup.<br>User closed the app clone picker: The user has closed the dialog box for selecting a cloned application.<br>Free installation failed: The free installation fails.<br>|
82
83**Example**
84
85See [Usage of CompletionHandler](#usage-of-completionhandler).
86
87### Usage of CompletionHandler
88
89  ```ts
90  import { UIAbility, Want, StartOptions, CompletionHandler, bundleManager } from '@kit.AbilityKit';
91  import { BusinessError } from '@kit.BasicServicesKit';
92
93  export default class EntryAbility extends UIAbility {
94    onForeground() {
95      let want: Want = {
96        deviceId: '',
97        bundleName: 'com.example.myapplication',
98        abilityName: 'EntryAbility'
99      };
100
101      let completionHandler: CompletionHandler = {
102        onRequestSuccess: (elementName: bundleManager.ElementName, message: string): void => {
103          console.info(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start succeeded: ${message}`);
104        },
105        onRequestFailure: (elementName: bundleManager.ElementName, message: string): void => {
106          console.error(`${elementName.bundleName}-${elementName.moduleName}-${elementName.abilityName} start failed: ${message}`);
107        }
108      };
109
110      let options: StartOptions = {
111        completionHandler: completionHandler
112      };
113
114      try {
115        this.context.startAbility(want, options, (err: BusinessError) => {
116          if (err.code) {
117            // Process service logic errors.
118            console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
119            return;
120          }
121          // Carry out normal service processing.
122          console.info('startAbility succeed');
123        });
124      } catch (err) {
125        // Process input parameter errors.
126        let code = (err as BusinessError).code;
127        let message = (err as BusinessError).message;
128        console.error(`startAbility failed, code is ${code}, message is ${message}`);
129      }
130    }
131  }
132  ```
133