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