1# AbilityDelegator 2 3The **AbilityDelegator** module provides APIs for managing **AbilityMonitor** instances that are used to monitor the lifecycle state changes of a specified ability. You can use the APIs to add and remove **AbilityMonitor** instances, wait for an ability to reach the **onCreate** lifecycle state, set the waiting time, obtain the lifecycle state of an ability, obtain the top ability of the current application, and start an ability. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 13``` 14 15## Usage 16 17An **AbilityDelegator** object is obtained by calling [getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator) in **AbilityDelegatorRegistry**. This API can be used only in the test environment. 18```ts 19import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 20``` 21 22## AbilityDelegator 23 24### addAbilityMonitor<sup>9+</sup> 25 26addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void; 27 28Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 29 30**System capability**: SystemCapability.Ability.AbilityRuntime.Core 31 32**Parameters** 33 34| Name | Type | Mandatory| Description | 35| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 36| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 37| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 38 39**Error codes** 40 41| ID| Error Message| 42| ------- | -------- | 43| 16000100 | AddAbilityMonitor failed. | 44 45For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 46 47**Example** 48 49```ts 50import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 51import UIAbility from '@ohos.app.ability.UIAbility'; 52import { BusinessError } from '@ohos.base'; 53 54let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 55 56function onAbilityCreateCallback(data: UIAbility) { 57 console.info(`onAbilityCreateCallback, data: ${JSON.stringify(data)}`); 58} 59 60let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 61 abilityName: 'abilityname', 62 onAbilityCreate: onAbilityCreateCallback 63}; 64abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 65abilityDelegator.addAbilityMonitor(monitor, (error: BusinessError) => { 66 console.error(`addAbilityMonitor fail, error: ${JSON.stringify(error)}`); 67}); 68``` 69 70### addAbilityMonitor<sup>9+</sup> 71 72addAbilityMonitor(monitor: AbilityMonitor): Promise\<void>; 73 74Adds an **AbilityMonitor** instance. This API uses a promise to return the result. 75 76**System capability**: SystemCapability.Ability.AbilityRuntime.Core 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 82| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 83 84**Return value** 85 86| Type | Description | 87| -------------- | ------------------- | 88| Promise\<void> | Promise used to return the result.| 89 90**Error codes** 91 92| ID| Error Message| 93| ------- | -------- | 94| 16000100 | AddAbilityMonitor failed. | 95 96For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 97 98**Example** 99 100```ts 101import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 102import UIAbility from '@ohos.app.ability.UIAbility'; 103 104let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 105 106function onAbilityCreateCallback(data: UIAbility) { 107 console.info('onAbilityCreateCallback'); 108} 109 110let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 111 abilityName: 'abilityname', 112 onAbilityCreate: onAbilityCreateCallback 113}; 114abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 115abilityDelegator.addAbilityMonitor(monitor).then(() => { 116 console.info('addAbilityMonitor promise'); 117}); 118``` 119 120### addAbilityMonitorSync<sup>10+</sup> 121 122addAbilityMonitorSync(monitor: AbilityMonitor): void; 123 124Adds an **AbilityMonitor** instance. This API is a synchronous API. 125 126**System capability**: SystemCapability.Ability.AbilityRuntime.Core 127 128**Parameters** 129 130| Name | Type | Mandatory| Description | 131| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 132| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 133 134**Error codes** 135 136| ID| Error Message| 137| ------- | -------- | 138| 16000100 | AddAbilityMonitor failed. | 139| 401 | If the input parameter is not valid parameter. | 140 141For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 142 143**Example** 144 145```ts 146let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 147 148let monitor = { 149 abilityName: 'abilityname', 150 onAbilityCreate: onAbilityCreateCallback 151}; 152 153abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 154abilityDelegator.addAbilityMonitorSync(monitor); 155``` 156 157### removeAbilityMonitor<sup>9+</sup> 158 159removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void; 160 161Removes an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 162 163**System capability**: SystemCapability.Ability.AbilityRuntime.Core 164 165**Parameters** 166 167| Name | Type | Mandatory| Description | 168| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 169| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 170| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 171 172**Error codes** 173 174| ID| Error Message| 175| ------- | -------- | 176| 16000100 | RemoveAbilityMonitor failed. | 177 178For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 179 180**Example** 181 182```ts 183import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 184import UIAbility from '@ohos.app.ability.UIAbility'; 185import { BusinessError } from '@ohos.base'; 186 187let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 188 189function onAbilityCreateCallback(data: UIAbility) { 190 console.info('onAbilityCreateCallback'); 191} 192 193let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 194 abilityName: 'abilityname', 195 onAbilityCreate: onAbilityCreateCallback 196}; 197 198abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 199abilityDelegator.removeAbilityMonitor(monitor, (error: BusinessError) => { 200 console.error(`removeAbilityMonitor fail, error: ${JSON.stringify(error)}`); 201}); 202``` 203 204### removeAbilityMonitor<sup>9+</sup> 205 206removeAbilityMonitor(monitor: AbilityMonitor): Promise\<void>; 207 208Removes an **AbilityMonitor** instance. This API uses a promise to return the result. 209 210**System capability**: SystemCapability.Ability.AbilityRuntime.Core 211 212**Parameters** 213 214| Name | Type | Mandatory| Description | 215| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 216| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 217 218**Return value** 219 220| Type | Description | 221| -------------- | ------------------- | 222| Promise\<void> | Promise used to return the result.| 223 224**Error codes** 225 226| ID| Error Message| 227| ------- | -------- | 228| 16000100 | RemoveAbilityMonitor failed. | 229 230For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 231 232- Example 233 234```ts 235import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 236import UIAbility from '@ohos.app.ability.UIAbility'; 237 238let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 239 240function onAbilityCreateCallback(data: UIAbility) { 241 console.info('onAbilityCreateCallback'); 242} 243 244let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 245 abilityName: 'abilityname', 246 onAbilityCreate: onAbilityCreateCallback 247}; 248 249abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 250abilityDelegator.removeAbilityMonitor(monitor).then(() => { 251 console.info('removeAbilityMonitor promise'); 252}); 253``` 254 255### removeAbilityMonitorSync<sup>10+</sup> 256 257removeAbilityMonitorSync(monitor: AbilityMonitor): void; 258 259Deletes an **AbilityMonitor** instance. This API is a synchronous API. 260 261**System capability**: SystemCapability.Ability.AbilityRuntime.Core 262 263**Parameters** 264 265| Name | Type | Mandatory| Description | 266| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 267| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 268 269**Error codes** 270 271| ID| Error Message| 272| ------- | -------- | 273| 16000100 | RemoveAbilityMonitor failed. | 274| 401 | If the input parameter is not valid parameter. | 275 276For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 277 278**Example** 279 280```ts 281let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 282 283let monitor = { 284 abilityName: 'abilityname', 285 onAbilityCreate: onAbilityCreateCallback 286}; 287 288abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 289abilityDelegator.removeAbilityMonitorSync(monitor); 290``` 291 292### waitAbilityMonitor<sup>9+</sup> 293 294waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<UIAbility>): void; 295 296Waits for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. 297 298**System capability**: SystemCapability.Ability.AbilityRuntime.Core 299 300**Parameters** 301 302| Name | Type | Mandatory| Description | 303| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 304| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 305| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 306 307**Error codes** 308 309| ID| Error Message| 310| ------- | -------- | 311| 16000100 | WaitAbilityMonitor failed. | 312 313For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 314 315**Example** 316 317```ts 318import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 319import UIAbility from '@ohos.app.ability.UIAbility'; 320import { BusinessError } from '@ohos.base'; 321 322let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 323 324function onAbilityCreateCallback(data: UIAbility) { 325 console.info('onAbilityCreateCallback'); 326} 327 328let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 329 abilityName: 'abilityname', 330 onAbilityCreate: onAbilityCreateCallback 331}; 332 333abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 334abilityDelegator.waitAbilityMonitor(monitor, (error : BusinessError, data : UIAbility) => { 335 if (error) { 336 console.error(`waitAbilityMonitor fail, error: ${JSON.stringify(error)}`); 337 } else { 338 console.log(`waitAbilityMonitor success, data: ${JSON.stringify(data)}`); 339 } 340}); 341``` 342 343### waitAbilityMonitor<sup>9+</sup> 344 345waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\<UIAbility>): void; 346 347Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. 348 349**System capability**: SystemCapability.Ability.AbilityRuntime.Core 350 351**Parameters** 352 353| Name | Type | Mandatory| Description | 354| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 355| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 356| timeout | number | Yes | Maximum waiting time, in milliseconds. | 357| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 358 359**Error codes** 360 361| ID| Error Message| 362| ------- | -------- | 363| 16000100 | WaitAbilityMonitor failed. | 364 365For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 366 367**Example** 368 369```ts 370import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 371import UIAbility from '@ohos.app.ability.UIAbility'; 372import { BusinessError } from '@ohos.base'; 373 374let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 375let timeout = 100; 376 377function onAbilityCreateCallback(data: UIAbility) { 378 console.info('onAbilityCreateCallback'); 379} 380 381let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 382 abilityName: 'abilityname', 383 onAbilityCreate: onAbilityCreateCallback 384}; 385 386abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 387abilityDelegator.waitAbilityMonitor(monitor, timeout, (error : BusinessError, data : UIAbility) => { 388 if (error && error.code !== 0) { 389 console.error(`waitAbilityMonitor fail, error: ${JSON.stringify(error)}`); 390 } else { 391 console.log(`waitAbilityMonitor success, data: ${JSON.stringify(data)}`); 392 } 393}); 394``` 395 396 397 398### waitAbilityMonitor<sup>9+</sup> 399 400waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\<UIAbility>; 401 402Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **onCreate** lifecycle state and returns the **Ability** instance. This API uses a promise to return the result. 403 404**System capability**: SystemCapability.Ability.AbilityRuntime.Core 405 406**Parameters** 407 408| Name | Type | Mandatory| Description | 409| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 410| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 411| timeout | number | No | Maximum waiting time, in milliseconds. | 412 413**Return value** 414 415| Type | Description | 416| ----------------------------------------------------------- | -------------------------- | 417| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the **Ability** instance.| 418 419**Error codes** 420 421| ID| Error Message| 422| ------- | -------- | 423| 16000100 | WaitAbilityMonitor failed. | 424 425For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 426 427**Example** 428 429```ts 430import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 431import UIAbility from '@ohos.app.ability.UIAbility'; 432 433let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 434 435function onAbilityCreateCallback(data: UIAbility) { 436 console.info('onAbilityCreateCallback'); 437} 438 439let monitor: AbilityDelegatorRegistry.AbilityMonitor = { 440 abilityName: 'abilityname', 441 onAbilityCreate: onAbilityCreateCallback 442}; 443 444abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 445abilityDelegator.waitAbilityMonitor(monitor).then((data : BusinessError) => { 446 console.info('waitAbilityMonitor promise'); 447}); 448``` 449 450### getAppContext<sup>9+</sup> 451 452getAppContext(): Context; 453 454Obtains the application context. 455 456**System capability**: SystemCapability.Ability.AbilityRuntime.Core 457 458**Return value** 459 460| Type | Description | 461| ------------------------------------- | ------------------------------------------- | 462| [Context](js-apis-inner-application-context.md) | Application [context](js-apis-inner-application-context.md).| 463 464**Example** 465 466```ts 467import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 468 469let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 470 471abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 472let context = abilityDelegator.getAppContext(); 473``` 474 475### getAbilityState<sup>9+</sup> 476 477getAbilityState(ability: UIAbility): number; 478 479Obtains the lifecycle state of an ability. 480 481**System capability**: SystemCapability.Ability.AbilityRuntime.Core 482 483**Parameters** 484 485| Name | Type | Mandatory| Description | 486| ------- | ------------------------------------------------- | ---- | --------------- | 487| ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes | Target ability.| 488 489**Return value** 490 491| Type | Description | 492| ------ | ------------------------------------------------------------ | 493| number | Lifecycle state of the ability. For details about the available enumerated values, see [AbilityLifecycleState](js-apis-application-abilityDelegatorRegistry.md#AbilityLifecycleState).| 494 495**Example** 496 497```ts 498import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 499import UIAbility from '@ohos.app.ability.UIAbility'; 500import { BusinessError } from '@ohos.base'; 501 502let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 503let ability: UIAbility; 504 505abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 506abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 507 console.info('getCurrentTopAbility callback'); 508 ability = data; 509 let state = abilityDelegator.getAbilityState(ability); 510 console.info('getAbilityState ${state}'); 511}); 512``` 513 514### getCurrentTopAbility<sup>9+</sup> 515 516getCurrentTopAbility(callback: AsyncCallback\<UIAbility>): void; 517 518Obtains the top ability of this application. This API uses an asynchronous callback to return the result. 519 520**System capability**: SystemCapability.Ability.AbilityRuntime.Core 521 522**Parameters** 523 524| Name | Type | Mandatory| Description | 525| -------- | ------------------------------------------------------------ | ---- | ------------------ | 526| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result.| 527 528**Error codes** 529 530| ID| Error Message| 531| ------- | -------- | 532| 16000100 | GetCurrentTopAbility failed. | 533 534For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 535 536**Example** 537 538```ts 539import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 540import UIAbility from '@ohos.app.ability.UIAbility'; 541import { BusinessError } from '@ohos.base'; 542 543let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 544let ability: UIAbility; 545 546abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 547abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 548 console.info('getCurrentTopAbility callback'); 549 ability = data; 550}); 551``` 552 553### getCurrentTopAbility<sup>9+</sup> 554 555getCurrentTopAbility(): Promise\<UIAbility>; 556 557Obtains the top ability of this application. This API uses a promise to return the result. 558 559**System capability**: SystemCapability.Ability.AbilityRuntime.Core 560 561**Return value** 562 563| Type | Description | 564| ----------------------------------------------------------- | -------------------------------------- | 565| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| 566 567**Error codes** 568 569| ID| Error Message| 570| ------- | -------- | 571| 16000100 | GetCurrentTopAbility failed. | 572 573For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 574 575**Example** 576 577```ts 578import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 579import UIAbility from '@ohos.app.ability.UIAbility'; 580 581let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 582let ability: UIAbility; 583 584abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 585abilityDelegator.getCurrentTopAbility().then((data : UIAbility) => { 586 console.info('getCurrentTopAbility promise'); 587 ability = data; 588}); 589``` 590 591### startAbility<sup>9+</sup> 592 593startAbility(want: Want, callback: AsyncCallback\<void>): void; 594 595Starts an ability. This API uses an asynchronous callback to return the result. 596 597**System capability**: SystemCapability.Ability.AbilityRuntime.Core 598 599**Parameters** 600 601| Name | Type | Mandatory| Description | 602| -------- | -------------------------------------- | ---- | ------------------ | 603| want | [Want](js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability. | 604| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 605 606**Error codes** 607 608| ID| Error Message| 609| ------- | -------- | 610| 16000001 | The specified ability does not exist. | 611| 16000002 | Incorrect ability type. | 612| 16000004 | Can not start invisible component. | 613| 16000005 | The specified process does not have the permission. | 614| 16000006 | Cross-user operations are not allowed. | 615| 16000008 | The crowdtesting application expires. | 616| 16000009 | An ability cannot be started or stopped in Wukong mode. | 617| 16000010 | The call with the continuation flag is forbidden. | 618| 16000011 | The context does not exist. | 619| 16000012 | The application is controlled. | 620| 16000013 | The application is controlled by EDM. | 621| 16000050 | Internal error. | 622| 16000053 | The ability is not on the top of the UI. | 623| 16000055 | Installation-free timed out. | 624| 16200001 | The caller has been released. | 625 626For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 627 628**Example** 629 630```ts 631import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 632import Want from '@ohos.app.ability.Want'; 633import { BusinessError } from '@ohos.base'; 634 635let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 636let want: Want = { 637 bundleName: 'bundleName', 638 abilityName: 'abilityName' 639}; 640 641abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 642abilityDelegator.startAbility(want, (err : BusinessError, data : void) => { 643 console.info('startAbility callback'); 644}); 645``` 646 647### startAbility<sup>9+</sup> 648 649startAbility(want: Want): Promise\<void>; 650 651Starts an ability. This API uses a promise to return the result. 652 653**System capability**: SystemCapability.Ability.AbilityRuntime.Core 654 655**Parameters** 656 657| Name| Type | Mandatory| Description | 658| ------ | -------------------------------------- | ---- | --------------- | 659| want | [Want](js-apis-app-ability-want.md) | Yes | **Want** parameter for starting the ability.| 660 661**Return value** 662 663| Type | Description | 664| -------------- | ------------------- | 665| Promise\<void> | Promise used to return the result.| 666 667**Error codes** 668 669| ID| Error Message| 670| ------- | -------- | 671| 16000001 | The specified ability does not exist. | 672| 16000002 | Incorrect ability type. | 673| 16000004 | Can not start invisible component. | 674| 16000005 | The specified process does not have the permission. | 675| 16000006 | Cross-user operations are not allowed. | 676| 16000008 | The crowdtesting application expires. | 677| 16000009 | An ability cannot be started or stopped in Wukong mode. | 678| 16000010 | The call with the continuation flag is forbidden. | 679| 16000011 | The context does not exist. | 680| 16000012 | The application is controlled. | 681| 16000013 | The application is controlled by EDM. | 682| 16000050 | Internal error. | 683| 16000053 | The ability is not on the top of the UI. | 684| 16000055 | Installation-free timed out. | 685| 16200001 | The caller has been released. | 686 687For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 688 689**Example** 690 691```ts 692import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 693import UIAbility from '@ohos.app.ability.UIAbility'; 694import Want from '@ohos.app.ability.Want'; 695 696let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 697let want: Want = { 698 bundleName: 'bundleName', 699 abilityName: 'abilityName' 700}; 701 702abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 703abilityDelegator.startAbility(want).then((data: void) => { 704 console.info('startAbility promise'); 705}); 706``` 707 708### doAbilityForeground<sup>9+</sup> 709 710doAbilityForeground(ability: UIAbility, callback: AsyncCallback\<void>): void; 711 712Schedules the lifecycle state of an ability to **Foreground**. This API uses an asynchronous callback to return the result. 713 714**System capability**: SystemCapability.Ability.AbilityRuntime.Core 715 716**Parameters** 717 718| Name | Type | Mandatory| Description | 719| -------- | ----------------------- | ---- | ------------------------------------------------------- | 720| ability | UIAbility | Yes | Target ability. | 721| callback | AsyncCallback\<void> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 722 723**Error codes** 724 725| ID| Error Message| 726| ------- | -------- | 727| 16000100 | DoAbilityForeground failed. | 728 729For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 730 731**Example** 732 733```ts 734import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 735import UIAbility from '@ohos.app.ability.UIAbility'; 736import { BusinessError } from '@ohos.base'; 737 738let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 739let ability: UIAbility; 740 741abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 742abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 743 console.info('getCurrentTopAbility callback'); 744 ability = data; 745 abilityDelegator.doAbilityForeground(ability, (err : BusinessError) => { 746 console.info("doAbilityForeground callback"); 747 }); 748}); 749``` 750 751### doAbilityForeground<sup>9+</sup> 752 753doAbilityForeground(ability: UIAbility): Promise\<void>; 754 755Schedules the lifecycle state of an ability to **Foreground**. This API uses a promise to return the result. 756 757**System capability**: SystemCapability.Ability.AbilityRuntime.Core 758 759**Parameters** 760 761| Name | Type | Mandatory| Description | 762| ------- | ------- | ---- | --------------- | 763| ability | UIAbility | Yes | Target ability.| 764 765**Return value** 766 767| Type | Description | 768| ----------------- | ------------------------------------------------------------ | 769| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 770 771**Error codes** 772 773| ID| Error Message| 774| ------- | -------- | 775| 16000100 | DoAbilityForeground failed. | 776 777For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 778 779**Example** 780 781```ts 782import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 783import UIAbility from '@ohos.app.ability.UIAbility'; 784import { BusinessError } from '@ohos.base'; 785 786let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 787let ability: UIAbility; 788 789abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 790abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 791 console.info('getCurrentTopAbility callback'); 792 ability = data; 793 abilityDelegator.doAbilityForeground(ability).then(() => { 794 console.info("doAbilityForeground promise"); 795 }); 796}); 797``` 798 799### doAbilityBackground<sup>9+</sup> 800 801doAbilityBackground(ability: UIAbility, callback: AsyncCallback\<void>): void; 802 803Schedules the lifecycle state of an ability to **Background**. This API uses an asynchronous callback to return the result. 804 805**System capability**: SystemCapability.Ability.AbilityRuntime.Core 806 807**Parameters** 808 809| Name | Type | Mandatory| Description | 810| -------- | ----------------------- | ---- | ------------------------------------------------------- | 811| ability | UIAbility | Yes | Target ability. | 812| callback | AsyncCallback\<void> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 813 814**Error codes** 815 816| ID| Error Message| 817| ------- | -------- | 818| 16000100 | DoAbilityBackground failed. | 819 820For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 821 822**Example** 823 824```ts 825import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 826import UIAbility from '@ohos.app.ability.UIAbility'; 827import { BusinessError } from '@ohos.base'; 828 829let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 830let ability: UIAbility; 831 832abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 833abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 834 console.info('getCurrentTopAbility callback'); 835 ability = data; 836 abilityDelegator.doAbilityBackground(ability, (err : BusinessError) => { 837 console.info("doAbilityBackground callback"); 838 }); 839}); 840``` 841 842### doAbilityBackground<sup>9+</sup> 843 844doAbilityBackground(ability: UIAbility): Promise\<void>; 845 846Schedules the lifecycle state of an ability to **Background**. This API uses a promise to return the result. 847 848**System capability**: SystemCapability.Ability.AbilityRuntime.Core 849 850**Parameters** 851 852| Name | Type | Mandatory| Description | 853| ------- | ------- | ---- | --------------- | 854| ability | UIAbility | Yes | Target ability.| 855 856**Return value** 857 858| Type | Description | 859| ----------------- | ------------------------------------------------------------ | 860| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 861 862**Error codes** 863 864| ID| Error Message| 865| ------- | -------- | 866| 16000100 | DoAbilityBackground failed. | 867 868For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 869 870**Example** 871 872```ts 873import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 874import UIAbility from '@ohos.app.ability.UIAbility'; 875import { BusinessError } from '@ohos.base'; 876 877let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 878let ability: UIAbility; 879 880abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 881abilityDelegator.getCurrentTopAbility((err : BusinessError, data : UIAbility) => { 882 console.info('getCurrentTopAbility callback'); 883 ability = data; 884 abilityDelegator.doAbilityBackground(ability).then(() => { 885 console.info("doAbilityBackground promise"); 886 }); 887}); 888``` 889 890### printSync<sup>9+</sup> 891 892printSync(msg: string): void; 893 894Prints log information to the unit test console. 895 896**System capability**: SystemCapability.Ability.AbilityRuntime.Core 897 898**Parameters** 899 900| Name| Type | Mandatory| Description | 901| ------ | ------ | ---- | ---------- | 902| msg | string | Yes | Log string.| 903 904**Example** 905 906```ts 907import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 908 909let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 910let msg = 'msg'; 911 912abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 913abilityDelegator.printSync(msg); 914``` 915 916### print 917 918print(msg: string, callback: AsyncCallback\<void>): void; 919 920Prints log information to the unit test console. This API uses an asynchronous callback to return the result. 921 922**System capability**: SystemCapability.Ability.AbilityRuntime.Core 923 924**Parameters** 925 926| Name | Type | Mandatory| Description | 927| -------- | -------------------- | ---- | ------------------ | 928| msg | string | Yes | Log string. | 929| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 930 931**Example** 932 933```ts 934import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 935import { BusinessError } from '@ohos.base'; 936 937let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 938let msg = 'msg'; 939 940abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 941abilityDelegator.print(msg, (err : BusinessError) => { 942 console.info('print callback'); 943}); 944``` 945 946### print 947 948print(msg: string): Promise\<void>; 949 950Prints log information to the unit test console. This API uses a promise to return the result. 951 952**System capability**: SystemCapability.Ability.AbilityRuntime.Core 953 954**Parameters** 955 956| Name| Type | Mandatory| Description | 957| ------ | ------ | ---- | ---------- | 958| msg | string | Yes | Log string.| 959 960**Return value** 961 962| Type | Description | 963| -------------- | ------------------- | 964| Promise\<void> | Promise used to return the result.| 965 966**Example** 967 968```ts 969import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 970 971let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 972let msg = 'msg'; 973 974abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 975abilityDelegator.print(msg).then(() => { 976 console.info('print promise'); 977}); 978``` 979 980### executeShellCommand 981 982executeShellCommand(cmd: string, callback: AsyncCallback\<ShellCmdResult>): void; 983 984Executes a shell command. This API uses an asynchronous callback to return the result. 985 986Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 987 988**System capability**: SystemCapability.Ability.AbilityRuntime.Core 989 990**Parameters** 991 992| Name | Type | Mandatory| Description | 993| -------- | ------------------------------------------------------------ | ---- | ------------------ | 994| cmd | string | Yes | Shell command string. | 995| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result.| 996 997**Example** 998 999```ts 1000import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1001import { BusinessError } from '@ohos.base'; 1002 1003let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1004let cmd = 'cmd'; 1005 1006abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1007abilityDelegator.executeShellCommand(cmd, (err : BusinessError, data: AbilityDelegatorRegistry.ShellCmdResult) => { 1008 console.info('executeShellCommand callback'); 1009}); 1010``` 1011 1012### executeShellCommand 1013 1014executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\<ShellCmdResult>): void; 1015 1016Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result. 1017 1018Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1019 1020**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1021 1022**Parameters** 1023 1024| Name | Type | Mandatory| Description | 1025| ----------- | ------------------------------------------------------------ | ---- | ----------------------------- | 1026| cmd | string | Yes | Shell command string. | 1027| timeoutSecs | number | Yes | Command timeout period, in seconds.| 1028| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result. | 1029 1030**Example** 1031 1032```ts 1033import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1034import { BusinessError } from '@ohos.base'; 1035 1036let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1037let cmd = 'cmd'; 1038let timeout = 100; 1039 1040abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1041abilityDelegator.executeShellCommand(cmd, timeout, (err : BusinessError, data: AbilityDelegatorRegistry.ShellCmdResult) => { 1042 console.info('executeShellCommand callback'); 1043}); 1044``` 1045 1046### executeShellCommand 1047 1048executeShellCommand(cmd: string, timeoutSecs?: number): Promise\<ShellCmdResult>; 1049 1050Executes a shell command with the timeout period specified. This API uses a promise to return the result. 1051 1052Only the following shell commands are supported: aa, bm, cp, mkdir, rm, uinput, hilog, ppwd, echo, uitest, acm, hidumper, wukong, pkill, ps, and pidof. 1053 1054**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1055 1056**Parameters** 1057 1058| Name | Type | Mandatory| Description | 1059| ----------- | ------ | ---- | ----------------------------- | 1060| cmd | string | Yes | Shell command string. | 1061| timeoutSecs | number | No | Command timeout period, in seconds.| 1062 1063**Return value** 1064 1065| Type | Description | 1066| ------------------------------------------------------------ | ------------------------------------------------------------ | 1067| Promise\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Promise used to return a [ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult) object.| 1068 1069**Example** 1070 1071```ts 1072import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1073 1074let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1075let cmd = 'cmd'; 1076let timeout = 100; 1077 1078abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1079abilityDelegator.executeShellCommand(cmd, timeout).then((data) => { 1080 console.info('executeShellCommand promise'); 1081}); 1082``` 1083 1084### finishTest<sup>9+</sup> 1085 1086finishTest(msg: string, code: number, callback: AsyncCallback\<void>): void; 1087 1088Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result. 1089 1090**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1091 1092**Parameters** 1093 1094| Name | Type | Mandatory| Description | 1095| -------- | -------------------- | ---- | ------------------ | 1096| msg | string | Yes | Log string. | 1097| code | number | Yes | Log code. | 1098| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 1099 1100**Error codes** 1101 1102| ID| Error Message| 1103| ------- | -------- | 1104| 16000100 | FinishTest failed. | 1105 1106For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1107 1108**Example** 1109 1110```ts 1111import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1112import { BusinessError } from '@ohos.base'; 1113 1114let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1115let msg = 'msg'; 1116 1117abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1118abilityDelegator.finishTest(msg, 0, (err : BusinessError) => { 1119 console.info('finishTest callback'); 1120}); 1121``` 1122 1123### finishTest<sup>9+</sup> 1124 1125finishTest(msg: string, code: number): Promise\<void>; 1126 1127Finishes the test and prints log information to the unit test console. This API uses a promise to return the result. 1128 1129**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1130 1131**Parameters** 1132 1133| Name| Type | Mandatory| Description | 1134| ------ | ------ | ---- | ---------- | 1135| msg | string | Yes | Log string.| 1136| code | number | Yes | Log code. | 1137 1138**Return value** 1139 1140| Type | Description | 1141| -------------- | ------------------- | 1142| Promise\<void> | Promise used to return the result.| 1143 1144**Error codes** 1145 1146| ID| Error Message| 1147| ------- | -------- | 1148| 16000100 | FinishTest failed. | 1149 1150For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1151 1152**Example** 1153 1154```ts 1155import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1156 1157let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1158let msg = 'msg'; 1159 1160abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1161abilityDelegator.finishTest(msg, 0).then(() => { 1162 console.info('finishTest promise'); 1163}); 1164``` 1165 1166### addAbilityStageMonitor<sup>9+</sup> 1167 1168addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void; 1169 1170Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses an asynchronous callback to return the result. 1171 1172**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1173 1174**Parameters** 1175 1176| Name | Type | Mandatory| Description | 1177| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1178| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1179| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 1180 1181**Error codes** 1182 1183| ID| Error Message| 1184| ------- | -------- | 1185| 16000100 | AddAbilityStageMonitor failed. | 1186 1187For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1188 1189**Example** 1190 1191```ts 1192import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1193import { BusinessError } from '@ohos.base'; 1194 1195let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1196 1197abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1198abilityDelegator.addAbilityStageMonitor({ 1199 moduleName: 'moduleName', 1200 srcEntrance: 'srcEntrance', 1201}, (err : BusinessError) => { 1202 console.info('addAbilityStageMonitor callback'); 1203}); 1204``` 1205 1206### addAbilityStageMonitor<sup>9+</sup> 1207 1208addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void>; 1209 1210Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses a promise to return the result. 1211 1212**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1213 1214**Parameters** 1215 1216| Name | Type | Mandatory| Description | 1217| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1218| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1219 1220**Return value** 1221 1222| Type | Description | 1223| -------------- | ------------------- | 1224| Promise\<void> | Promise used to return the result.| 1225 1226**Error codes** 1227 1228| ID| Error Message| 1229| ------- | -------- | 1230| 16000100 | AddAbilityStageMonitor failed. | 1231 1232For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1233 1234**Example** 1235 1236```ts 1237import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1238 1239let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1240 1241abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1242abilityDelegator.addAbilityStageMonitor({ 1243 moduleName: 'moduleName', 1244 srcEntrance: 'srcEntrance', 1245}).then(() => { 1246 console.info('addAbilityStageMonitor promise'); 1247}); 1248``` 1249 1250### addAbilityStageMonitorSync<sup>10+</sup> 1251 1252addAbilityStageMonitorSync(monitor: AbilityStageMonitor): void; 1253 1254Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API is a synchronous API. 1255 1256**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1257 1258**Parameters** 1259 1260| Name | Type | Mandatory| Description | 1261| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1262| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1263| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 1264 1265**Error codes** 1266 1267| ID| Error Message| 1268| ------- | -------- | 1269| 16000100 | AddAbilityStageMonitor failed. | 1270| 401 | If the input parameter is not valid parameter. | 1271 1272For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1273 1274**Example** 1275 1276```ts 1277let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1278 1279let monitor = { 1280 moduleName: 'moduleName', 1281 srcEntrance: 'srcEntrance', 1282}; 1283 1284abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1285abilityDelegator.addAbilityStageMonitorSync(monitor); 1286``` 1287 1288### removeAbilityStageMonitor<sup>9+</sup> 1289 1290removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void; 1291 1292Removes an **AbilityStageMonitor** instance from the application memory. This API uses an asynchronous callback to return the result. 1293 1294**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1295 1296**Parameters** 1297 1298| Name | Type | Mandatory| Description | 1299| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1300| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1301| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 1302 1303**Error codes** 1304 1305| ID| Error Message| 1306| ------- | -------- | 1307| 16000100 | RemoveAbilityStageMonitor failed. | 1308 1309For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1310 1311**Example** 1312 1313```ts 1314import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1315import { BusinessError } from '@ohos.base'; 1316 1317let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1318 1319abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1320abilityDelegator.removeAbilityStageMonitor({ 1321 moduleName: 'moduleName', 1322 srcEntrance: 'srcEntrance', 1323}, (err : BusinessError) => { 1324 console.info('removeAbilityStageMonitor callback'); 1325}); 1326``` 1327 1328### removeAbilityStageMonitor<sup>9+</sup> 1329 1330removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void>; 1331 1332Removes an **AbilityStageMonitor** object from the application memory. This API uses a promise to return the result. 1333 1334**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1335 1336**Parameters** 1337 1338| Name | Type | Mandatory| Description | 1339| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1340| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1341 1342**Return value** 1343 1344| Type | Description | 1345| -------------- | ------------------- | 1346| Promise\<void> | Promise used to return the result.| 1347 1348**Error codes** 1349 1350| ID| Error Message| 1351| ------- | -------- | 1352| 16000100 | RemoveAbilityStageMonitor failed. | 1353 1354For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1355 1356**Example** 1357 1358```ts 1359import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1360 1361let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1362 1363abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1364abilityDelegator.removeAbilityStageMonitor({ 1365 moduleName: 'moduleName', 1366 srcEntrance: 'srcEntrance', 1367}).then(() => { 1368 console.info('removeAbilityStageMonitor promise'); 1369}); 1370``` 1371 1372### removeAbilityStageMonitorSync<sup>10+</sup> 1373 1374removeAbilityStageMonitorSync(monitor: AbilityStageMonitor): void; 1375 1376Removes an **AbilityStageMonitor** instance from the application memory. This API is a synchronous API. 1377 1378**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1379 1380**Parameters** 1381 1382| Name | Type | Mandatory| Description | 1383| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1384| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1385 1386**Error codes** 1387 1388| ID| Error Message| 1389| ------- | -------- | 1390| 16000100 | RemoveAbilityStageMonitor failed. | 1391| 401 | If the input parameter is not valid parameter. | 1392 1393For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1394 1395**Example** 1396 1397```ts 1398let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1399 1400let monitor = { 1401 moduleName: 'moduleName', 1402 srcEntrance: 'srcEntrance', 1403}; 1404 1405abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1406abilityDelegator.removeAbilityStageMonitorSync(monitor); 1407``` 1408 1409### waitAbilityStageMonitor<sup>9+</sup> 1410 1411waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<AbilityStage>): void; 1412 1413Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses an asynchronous callback to return the result. 1414 1415**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1416 1417**Parameters** 1418 1419| Name | Type | Mandatory| Description | 1420| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1421| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1422| callback | AsyncCallback\<AbilityStage> | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | 1423 1424**Error codes** 1425 1426| ID| Error Message| 1427| ------- | -------- | 1428| 16000100 | WaitAbilityStageMonitor failed. | 1429 1430For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1431 1432**Example** 1433 1434```ts 1435import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1436import AbilityStage from '@ohos.app.ability.AbilityStage'; 1437 1438let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1439 1440abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1441abilityDelegator.waitAbilityStageMonitor({ 1442 moduleName: 'moduleName', 1443 srcEntrance: 'srcEntrance', 1444}, (err : BusinessError, data : AbilityStage) => { 1445 console.info('waitAbilityStageMonitor callback'); 1446}); 1447``` 1448 1449### waitAbilityStageMonitor<sup>9+</sup> 1450 1451waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise\<AbilityStage>; 1452 1453Waits for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses a promise to return the result. 1454 1455**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1456 1457**Parameters** 1458 1459| Name | Type | Mandatory| Description | 1460| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1461| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1462| timeout | number | No | Maximum waiting time, in milliseconds.| 1463 1464**Return value** 1465 1466| Type | Description | 1467| -------------- | ------------------- | 1468| Promise\<AbilityStage> | Promise used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned.| 1469 1470**Error codes** 1471 1472| ID| Error Message| 1473| ------- | -------- | 1474| 16000100 | WaitAbilityStageMonitor failed. | 1475 1476For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1477 1478**Example** 1479 1480```ts 1481import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1482import AbilityStage from '@ohos.app.ability.AbilityStage'; 1483 1484let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1485 1486abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1487abilityDelegator.waitAbilityStageMonitor({ 1488 moduleName: 'moduleName', 1489 srcEntrance: 'srcEntrance', 1490}).then((data : AbilityStage) => { 1491 console.info('waitAbilityStageMonitor promise'); 1492}); 1493``` 1494 1495### waitAbilityStageMonitor<sup>9+</sup> 1496 1497waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback\<AbilityStage>): void; 1498 1499Waits a period of time for an **AbilityStage** instance that matches the conditions set in an **AbilityStageMonitor** instance and returns the **AbilityStage** instance. This API uses an asynchronous callback to return the result. 1500 1501**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1502 1503**Parameters** 1504 1505| Name | Type | Mandatory| Description | 1506| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1507| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1508| timeout | number | Yes | Maximum waiting time, in milliseconds.| 1509| callback | AsyncCallback\<AbilityStage> | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | 1510 1511**Error codes** 1512 1513| ID| Error Message| 1514| ------- | -------- | 1515| 16000100 | WaitAbilityStageMonitor failed. | 1516 1517For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). 1518 1519**Example** 1520 1521```ts 1522import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; 1523import AbilityStage from '@ohos.app.ability.AbilityStage'; 1524import { BusinessError } from '@ohos.base'; 1525 1526let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; 1527let timeout = 100; 1528 1529abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1530abilityDelegator.waitAbilityStageMonitor({ 1531 moduleName: 'moduleName', 1532 srcEntrance: 'srcEntrance', 1533}, timeout, (err : BusinessError, data : AbilityStage) => { 1534 console.info('waitAbilityStageMonitor callback'); 1535}); 1536``` 1537