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## Usage 10 11An **AbilityDelegator** object is obtained by calling [getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator) in **AbilityDelegatorRegistry**. 12```ts 13import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'; 14``` 15 16## AbilityDelegator 17 18### addAbilityMonitor<sup>9+</sup> 19 20addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void; 21 22Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 23 24**System capability**: SystemCapability.Ability.AbilityRuntime.Core 25 26**Parameters** 27 28| Name | Type | Mandatory| Description | 29| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 30| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 31| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 32 33**Example** 34 35```ts 36let abilityDelegator; 37 38function onAbilityCreateCallback(data) { 39 console.info('onAbilityCreateCallback'); 40} 41 42let monitor = { 43 abilityName: 'abilityname', 44 onAbilityCreate: onAbilityCreateCallback 45}; 46 47abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 48abilityDelegator.addAbilityMonitor(monitor, (err : any) => { 49 console.info('addAbilityMonitor callback'); 50}); 51``` 52 53### addAbilityMonitor<sup>9+</sup> 54 55addAbilityMonitor(monitor: AbilityMonitor): Promise\<void>; 56 57Adds an **AbilityMonitor** instance. This API uses a promise to return the result. 58 59**System capability**: SystemCapability.Ability.AbilityRuntime.Core 60 61**Parameters** 62 63| Name | Type | Mandatory| Description | 64| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 65| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 66 67**Return value** 68 69| Type | Description | 70| -------------- | ------------------- | 71| Promise\<void> | Promise used to return the result.| 72 73**Example** 74 75```ts 76let abilityDelegator; 77 78function onAbilityCreateCallback(data) { 79 console.info('onAbilityCreateCallback'); 80} 81 82let monitor = { 83 abilityName: 'abilityname', 84 onAbilityCreate: onAbilityCreateCallback 85}; 86 87abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 88abilityDelegator.addAbilityMonitor(monitor).then(() => { 89 console.info('addAbilityMonitor promise'); 90}); 91``` 92 93 94 95### removeAbilityMonitor<sup>9+</sup> 96 97removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<void>): void; 98 99Removes an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. 100 101**System capability**: SystemCapability.Ability.AbilityRuntime.Core 102 103**Parameters** 104 105| Name | Type | Mandatory| Description | 106| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 107| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 108| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 109 110**Example** 111 112```ts 113let abilityDelegator; 114 115function onAbilityCreateCallback(data) { 116 console.info('onAbilityCreateCallback'); 117} 118 119let monitor = { 120 abilityName: 'abilityname', 121 onAbilityCreate: onAbilityCreateCallback 122}; 123 124abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 125abilityDelegator.removeAbilityMonitor(monitor, (err : any) => { 126 console.info('removeAbilityMonitor callback'); 127}); 128``` 129 130 131 132### removeAbilityMonitor<sup>9+</sup> 133 134removeAbilityMonitor(monitor: AbilityMonitor): Promise\<void>; 135 136Removes an **AbilityMonitor** instance. This API uses a promise to return the result. 137 138**System capability**: SystemCapability.Ability.AbilityRuntime.Core 139 140**Parameters** 141 142| Name | Type | Mandatory| Description | 143| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 144| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 145 146**Return value** 147 148| Type | Description | 149| -------------- | ------------------- | 150| Promise\<void> | Promise used to return the result.| 151 152- Example 153 154```ts 155let abilityDelegator; 156 157function onAbilityCreateCallback(data) { 158 console.info('onAbilityCreateCallback'); 159} 160 161let monitor = { 162 abilityName: 'abilityname', 163 onAbilityCreate: onAbilityCreateCallback 164}; 165 166abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 167abilityDelegator.removeAbilityMonitor(monitor).then(() => { 168 console.info('removeAbilityMonitor promise'); 169}); 170``` 171 172 173 174### waitAbilityMonitor<sup>9+</sup> 175 176waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\<UIAbility>): void; 177 178Waits 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. 179 180**System capability**: SystemCapability.Ability.AbilityRuntime.Core 181 182**Parameters** 183 184| Name | Type | Mandatory| Description | 185| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 186| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 187| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 188 189**Example** 190 191```ts 192let abilityDelegator; 193 194function onAbilityCreateCallback(data) { 195 console.info('onAbilityCreateCallback'); 196} 197 198let monitor = { 199 abilityName: 'abilityname', 200 onAbilityCreate: onAbilityCreateCallback 201}; 202 203abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 204abilityDelegator.waitAbilityMonitor(monitor, (err : any, data : any) => { 205 console.info('waitAbilityMonitor callback'); 206}); 207``` 208 209### waitAbilityMonitor<sup>9+</sup> 210 211waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\<UIAbility>): void; 212 213Waits 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. 214 215**System capability**: SystemCapability.Ability.AbilityRuntime.Core 216 217**Parameters** 218 219| Name | Type | Mandatory| Description | 220| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 221| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 222| timeout | number | No | Maximum waiting time, in milliseconds. | 223| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | 224 225**Example** 226 227```ts 228let abilityDelegator; 229let timeout = 100; 230 231function onAbilityCreateCallback(data) { 232 console.info('onAbilityCreateCallback'); 233} 234 235let monitor = { 236 abilityName: 'abilityname', 237 onAbilityCreate: onAbilityCreateCallback 238}; 239 240abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 241abilityDelegator.waitAbilityMonitor(monitor, timeout, (err : any, data : any) => { 242 console.info('waitAbilityMonitor callback'); 243}); 244``` 245 246 247 248### waitAbilityMonitor<sup>9+</sup> 249 250waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\<UIAbility>; 251 252Waits 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. 253 254**System capability**: SystemCapability.Ability.AbilityRuntime.Core 255 256**Parameters** 257 258| Name | Type | Mandatory| Description | 259| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 260| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| 261| timeout | number | No | Maximum waiting time, in milliseconds. | 262 263**Return value** 264 265| Type | Description | 266| ----------------------------------------------------------- | -------------------------- | 267| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the **Ability** instance.| 268 269**Example** 270 271```ts 272let abilityDelegator; 273 274function onAbilityCreateCallback(data) { 275 console.info('onAbilityCreateCallback'); 276} 277 278let monitor = { 279 abilityName: 'abilityname', 280 onAbilityCreate: onAbilityCreateCallback 281}; 282 283abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 284abilityDelegator.waitAbilityMonitor(monitor).then((data : any) => { 285 console.info('waitAbilityMonitor promise'); 286}); 287``` 288 289 290 291### getAppContext<sup>9+</sup> 292 293getAppContext(): Context; 294 295Obtains the application context. 296 297**System capability**: SystemCapability.Ability.AbilityRuntime.Core 298 299**Return value** 300 301| Type | Description | 302| ------------------------------------- | ------------------------------------------- | 303| [Context](js-apis-inner-application-context.md) | Application [context](js-apis-inner-application-context.md).| 304 305**Example** 306 307```ts 308let abilityDelegator; 309 310abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 311let context = abilityDelegator.getAppContext(); 312``` 313 314 315 316### getAbilityState<sup>9+</sup> 317 318getAbilityState(ability: UIAbility): number; 319 320Obtains the lifecycle state of an ability. 321 322**System capability**: SystemCapability.Ability.AbilityRuntime.Core 323 324**Parameters** 325 326| Name | Type | Mandatory| Description | 327| ------- | ------------------------------------------------- | ---- | --------------- | 328| ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes | Target ability.| 329 330**Return value** 331 332| Type | Description | 333| ------ | ------------------------------------------------------------ | 334| number | Lifecycle state of the ability. For details about the available enumerated values, see [AbilityLifecycleState](js-apis-application-abilityDelegatorRegistry.md#AbilityLifecycleState).| 335 336**Example** 337 338```ts 339let abilityDelegator; 340let ability; 341 342abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 343abilityDelegator.getCurrentTopAbility((err : any, data : any) => { 344 console.info('getCurrentTopAbility callback'); 345 ability = data; 346 let state = abilityDelegator.getAbilityState(ability); 347 console.info('getAbilityState' + state); 348}); 349``` 350 351 352 353### getCurrentTopAbility<sup>9+</sup> 354 355getCurrentTopAbility(callback: AsyncCallback\<UIAbility>): void; 356 357Obtains the top ability of this application. This API uses an asynchronous callback to return the result. 358 359**System capability**: SystemCapability.Ability.AbilityRuntime.Core 360 361**Parameters** 362 363| Name | Type | Mandatory| Description | 364| -------- | ------------------------------------------------------------ | ---- | ------------------ | 365| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result.| 366 367**Example** 368 369```ts 370let abilityDelegator; 371let ability; 372 373abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 374abilityDelegator.getCurrentTopAbility((err : any, data : any) => { 375 console.info('getCurrentTopAbility callback'); 376 ability = data; 377}); 378``` 379 380 381 382### getCurrentTopAbility<sup>9+</sup> 383 384getCurrentTopAbility(): Promise\<UIAbility>; 385 386Obtains the top ability of this application. This API uses a promise to return the result. 387 388**System capability**: SystemCapability.Ability.AbilityRuntime.Core 389 390**Return value** 391 392| Type | Description | 393| ----------------------------------------------------------- | -------------------------------------- | 394| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| 395 396**Example** 397 398```ts 399let abilityDelegator; 400let ability; 401 402abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 403abilityDelegator.getCurrentTopAbility().then((data : any) => { 404 console.info('getCurrentTopAbility promise'); 405 ability = data; 406}); 407``` 408 409 410 411### startAbility<sup>9+</sup> 412 413startAbility(want: Want, callback: AsyncCallback\<void>): void; 414 415Starts an ability. This API uses an asynchronous callback to return the result. 416 417**System capability**: SystemCapability.Ability.AbilityRuntime.Core 418 419**Parameters** 420 421| Name | Type | Mandatory| Description | 422| -------- | -------------------------------------- | ---- | ------------------ | 423| want | [Want](js-apis-application-want.md) | Yes | **Want** parameter for starting the ability. | 424| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 425 426**Example** 427 428```ts 429let abilityDelegator; 430let want = { 431 bundleName: 'bundleName', 432 abilityName: 'abilityName' 433}; 434 435abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 436abilityDelegator.startAbility(want, (err : any, data : any) => { 437 console.info('startAbility callback'); 438}); 439``` 440 441 442 443### startAbility<sup>9+</sup> 444 445startAbility(want: Want): Promise\<void>; 446 447Starts an ability. This API uses a promise to return the result. 448 449**System capability**: SystemCapability.Ability.AbilityRuntime.Core 450 451**Parameters** 452 453| Name| Type | Mandatory| Description | 454| ------ | -------------------------------------- | ---- | --------------- | 455| want | [Want](js-apis-application-want.md) | Yes | **Want** parameter for starting the ability.| 456 457**Return value** 458 459| Type | Description | 460| -------------- | ------------------- | 461| Promise\<void> | Promise used to return the result.| 462 463**Example** 464 465```ts 466let abilityDelegator; 467let want = { 468 bundleName: 'bundleName', 469 abilityName: 'abilityName' 470}; 471 472abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 473abilityDelegator.startAbility(want).then((data: any) => { 474 console.info('startAbility promise'); 475}); 476``` 477 478 479 480### doAbilityForeground<sup>9+</sup> 481 482doAbilityForeground(ability: UIAbility, callback: AsyncCallback\<void>): void; 483 484Schedules the lifecycle state of an ability to **Foreground**. This API uses an asynchronous callback to return the result. 485 486**System capability**: SystemCapability.Ability.AbilityRuntime.Core 487 488**Parameters** 489 490| Name | Type | Mandatory| Description | 491| -------- | ----------------------- | ---- | ------------------------------------------------------- | 492| ability | UIAbility | Yes | Target ability. | 493| callback | AsyncCallback\<void> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 494 495**Example** 496 497```ts 498let abilityDelegator; 499let ability; 500 501abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 502abilityDelegator.getCurrentTopAbility((err : any, data : any) => { 503 console.info('getCurrentTopAbility callback'); 504 ability = data; 505 abilityDelegator.doAbilityForeground(ability, (err : any) => { 506 console.info("doAbilityForeground callback"); 507 }); 508}); 509``` 510 511 512 513### doAbilityForeground<sup>9+</sup> 514 515doAbilityForeground(ability: UIAbility): Promise\<void>; 516 517Schedules the lifecycle state of an ability to **Foreground**. This API uses a promise to return the result. 518 519**System capability**: SystemCapability.Ability.AbilityRuntime.Core 520 521**Parameters** 522 523| Name | Type | Mandatory| Description | 524| ------- | ------- | ---- | --------------- | 525| ability | UIAbility | Yes | Target ability.| 526 527**Return value** 528 529| Type | Description | 530| ----------------- | ------------------------------------------------------------ | 531| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 532 533**Example** 534 535```ts 536let abilityDelegator; 537let ability; 538 539abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 540abilityDelegator.getCurrentTopAbility((err : any, data : any) => { 541 console.info('getCurrentTopAbility callback'); 542 ability = data; 543 abilityDelegator.doAbilityForeground(ability).then(() => { 544 console.info("doAbilityForeground promise"); 545 }); 546}); 547``` 548 549 550 551### doAbilityBackground<sup>9+</sup> 552 553doAbilityBackground(ability: UIAbility, callback: AsyncCallback\<void>): void; 554 555Schedules the lifecycle state of an ability to **Background**. This API uses an asynchronous callback to return the result. 556 557**System capability**: SystemCapability.Ability.AbilityRuntime.Core 558 559**Parameters** 560 561| Name | Type | Mandatory| Description | 562| -------- | ----------------------- | ---- | ------------------------------------------------------- | 563| ability | UIAbility | Yes | Target ability. | 564| callback | AsyncCallback\<void> | Yes | Callback used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 565 566**Example** 567 568```ts 569let abilityDelegator; 570let ability; 571 572abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 573abilityDelegator.getCurrentTopAbility((err : any, data : any) => { 574 console.info('getCurrentTopAbility callback'); 575 ability = data; 576 abilityDelegator.doAbilityBackground(ability, (err : any) => { 577 console.info("doAbilityBackground callback"); 578 }); 579}); 580``` 581 582 583 584### doAbilityBackground<sup>9+</sup> 585 586doAbilityBackground(ability: UIAbility): Promise\<void>; 587 588Schedules the lifecycle state of an ability to **Background**. This API uses a promise to return the result. 589 590**System capability**: SystemCapability.Ability.AbilityRuntime.Core 591 592**Parameters** 593 594| Name | Type | Mandatory| Description | 595| ------- | ------- | ---- | --------------- | 596| ability | UIAbility | Yes | Target ability.| 597 598**Return value** 599 600| Type | Description | 601| ----------------- | ------------------------------------------------------------ | 602| Promise\<boolean> | Promise used to return the result.<br>\- **true**: The operation is successful.<br>\- **false**: The operation failed.| 603 604**Example** 605 606```ts 607let abilityDelegator; 608let ability; 609 610abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 611abilityDelegator.getCurrentTopAbility((err : any, data : any) => { 612 console.info('getCurrentTopAbility callback'); 613 ability = data; 614 abilityDelegator.doAbilityBackground(ability).then(() => { 615 console.info("doAbilityBackground promise"); 616 }); 617}); 618``` 619 620 621 622### printSync<sup>9+</sup> 623 624printSync(msg: string): void; 625 626Prints log information to the unit test console. 627 628**System capability**: SystemCapability.Ability.AbilityRuntime.Core 629 630**Parameters** 631 632| Name| Type | Mandatory| Description | 633| ------ | ------ | ---- | ---------- | 634| msg | string | Yes | Log string.| 635 636**Example** 637 638```ts 639let abilityDelegator; 640let msg = 'msg'; 641 642abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 643abilityDelegator.printSync(msg); 644``` 645 646 647 648### print 649 650print(msg: string, callback: AsyncCallback\<void>): void; 651 652Prints log information to the unit test console. This API uses an asynchronous callback to return the result. 653 654**System capability**: SystemCapability.Ability.AbilityRuntime.Core 655 656**Parameters** 657 658| Name | Type | Mandatory| Description | 659| -------- | -------------------- | ---- | ------------------ | 660| msg | string | Yes | Log string. | 661| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 662 663**Example** 664 665```ts 666let abilityDelegator; 667let msg = 'msg'; 668 669abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 670abilityDelegator.print(msg, (err : any) => { 671 console.info('print callback'); 672}); 673``` 674 675 676 677### print 678 679print(msg: string): Promise\<void>; 680 681Prints log information to the unit test console. This API uses a promise to return the result. 682 683**System capability**: SystemCapability.Ability.AbilityRuntime.Core 684 685**Parameters** 686 687| Name| Type | Mandatory| Description | 688| ------ | ------ | ---- | ---------- | 689| msg | string | Yes | Log string.| 690 691**Return value** 692 693| Type | Description | 694| -------------- | ------------------- | 695| Promise\<void> | Promise used to return the result.| 696 697**Example** 698 699```ts 700let abilityDelegator; 701let msg = 'msg'; 702 703abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 704abilityDelegator.print(msg).then(() => { 705 console.info('print promise'); 706}); 707``` 708 709 710 711### executeShellCommand 712 713executeShellCommand(cmd: string, callback: AsyncCallback\<ShellCmdResult>): void; 714 715Executes a shell command. This API uses an asynchronous callback to return the result. 716 717**System capability**: SystemCapability.Ability.AbilityRuntime.Core 718 719**Parameters** 720 721| Name | Type | Mandatory| Description | 722| -------- | ------------------------------------------------------------ | ---- | ------------------ | 723| cmd | string | Yes | Shell command string. | 724| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result.| 725 726**Example** 727 728```ts 729let abilityDelegator; 730let cmd = 'cmd'; 731 732abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 733abilityDelegator.executeShellCommand(cmd, (err : any, data : any) => { 734 console.info('executeShellCommand callback'); 735}); 736``` 737 738 739 740### executeShellCommand 741 742executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\<ShellCmdResult>): void; 743 744Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result. 745 746**System capability**: SystemCapability.Ability.AbilityRuntime.Core 747 748**Parameters** 749 750| Name | Type | Mandatory| Description | 751| ----------- | ------------------------------------------------------------ | ---- | ----------------------------- | 752| cmd | string | Yes | Shell command string. | 753| timeoutSecs | number | No | Command timeout period, in seconds.| 754| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result. | 755 756**Example** 757 758```ts 759let abilityDelegator; 760let cmd = 'cmd'; 761let timeout = 100; 762 763abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 764abilityDelegator.executeShellCommand(cmd, timeout, (err : any, data : any) => { 765 console.info('executeShellCommand callback'); 766}); 767``` 768 769 770 771### executeShellCommand 772 773executeShellCommand(cmd: string, timeoutSecs?: number): Promise\<ShellCmdResult>; 774 775Executes a shell command with the timeout period specified. This API uses a promise to return the result. 776 777**System capability**: SystemCapability.Ability.AbilityRuntime.Core 778 779**Parameters** 780 781| Name | Type | Mandatory| Description | 782| ----------- | ------ | ---- | ----------------------------- | 783| cmd | string | Yes | Shell command string. | 784| timeoutSecs | number | No | Command timeout period, in seconds.| 785 786**Return value** 787 788| Type | Description | 789| ------------------------------------------------------------ | ------------------------------------------------------------ | 790| Promise\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Promise used to return a [ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult) object.| 791 792**Example** 793 794```ts 795let abilityDelegator; 796let cmd = 'cmd'; 797let timeout = 100; 798 799abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 800abilityDelegator.executeShellCommand(cmd, timeout).then((data : any) => { 801 console.info('executeShellCommand promise'); 802}); 803``` 804 805 806 807### finishTest<sup>9+</sup> 808 809finishTest(msg: string, code: number, callback: AsyncCallback\<void>): void; 810 811Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result. 812 813**System capability**: SystemCapability.Ability.AbilityRuntime.Core 814 815**Parameters** 816 817| Name | Type | Mandatory| Description | 818| -------- | -------------------- | ---- | ------------------ | 819| msg | string | Yes | Log string. | 820| code | number | Yes | Log code. | 821| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 822 823**Example** 824 825```ts 826let abilityDelegator; 827let msg = 'msg'; 828 829abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 830abilityDelegator.finishTest(msg, 0, (err : any) => { 831 console.info('finishTest callback'); 832}); 833``` 834 835 836 837### finishTest<sup>9+</sup> 838 839finishTest(msg: string, code: number): Promise\<void>; 840 841Finishes the test and prints log information to the unit test console. This API uses a promise to return the result. 842 843**System capability**: SystemCapability.Ability.AbilityRuntime.Core 844 845**Parameters** 846 847| Name| Type | Mandatory| Description | 848| ------ | ------ | ---- | ---------- | 849| msg | string | Yes | Log string.| 850| code | number | Yes | Log code. | 851 852**Return value** 853 854| Type | Description | 855| -------------- | ------------------- | 856| Promise\<void> | Promise used to return the result.| 857 858**Example** 859 860```ts 861let abilityDelegator; 862let msg = 'msg'; 863 864abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 865abilityDelegator.finishTest(msg, 0).then(() => { 866 console.info('finishTest promise'); 867}); 868``` 869 870### addAbilityStageMonitor<sup>9+</sup> 871 872addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void; 873 874Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses an asynchronous callback to return the result. 875 876**System capability**: SystemCapability.Ability.AbilityRuntime.Core 877 878**Parameters** 879 880| Name | Type | Mandatory| Description | 881| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 882| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 883| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 884 885**Example** 886 887```ts 888let abilityDelegator; 889 890let monitor = { 891 moduleName: 'moduleName', 892 srcEntrance: 'srcEntrance', 893}; 894 895abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 896abilityDelegator.addAbilityStageMonitor(monitor, (err : any) => { 897 console.info('addAbilityStageMonitor callback'); 898}); 899``` 900 901 902 903### addAbilityStageMonitor<sup>9+</sup> 904 905addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void>; 906 907Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes of an ability stage. This API uses a promise to return the result. 908 909**System capability**: SystemCapability.Ability.AbilityRuntime.Core 910 911**Parameters** 912 913| Name | Type | Mandatory| Description | 914| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 915| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 916 917**Return value** 918 919| Type | Description | 920| -------------- | ------------------- | 921| Promise\<void> | Promise used to return the result.| 922 923**Example** 924 925```ts 926let abilityDelegator; 927 928let monitor = { 929 moduleName: 'moduleName', 930 srcEntrance: 'srcEntrance', 931}; 932 933abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 934abilityDelegator.addAbilityStageMonitor(monitor).then(() => { 935 console.info('addAbilityStageMonitor promise'); 936}); 937``` 938 939### removeAbilityStageMonitor<sup>9+</sup> 940 941removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<void>): void; 942 943Removes an **AbilityStageMonitor** instance from the application memory. This API uses an asynchronous callback to return the result. 944 945**System capability**: SystemCapability.Ability.AbilityRuntime.Core 946 947**Parameters** 948 949| Name | Type | Mandatory| Description | 950| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 951| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 952| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 953 954**Example** 955 956```ts 957let abilityDelegator; 958 959let monitor = { 960 moduleName: 'moduleName', 961 srcEntrance: 'srcEntrance', 962}; 963 964abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 965abilityDelegator.removeAbilityStageMonitor(monitor, (err : any) => { 966 console.info('removeAbilityStageMonitor callback'); 967}); 968``` 969 970 971 972### removeAbilityStageMonitor<sup>9+</sup> 973 974removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise\<void>; 975 976Removes an **AbilityStageMonitor** object from the application memory. This API uses a promise to return the result. 977 978**System capability**: SystemCapability.Ability.AbilityRuntime.Core 979 980**Parameters** 981 982| Name | Type | Mandatory| Description | 983| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 984| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 985 986**Return value** 987 988| Type | Description | 989| -------------- | ------------------- | 990| Promise\<void> | Promise used to return the result.| 991 992**Example** 993 994```ts 995let abilityDelegator; 996 997let monitor = { 998 moduleName: 'moduleName', 999 srcEntrance: 'srcEntrance', 1000}; 1001 1002abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1003abilityDelegator.removeAbilityStageMonitor(monitor).then(() => { 1004 console.info('removeAbilityStageMonitor promise'); 1005}); 1006``` 1007 1008### waitAbilityStageMonitor<sup>9+</sup> 1009 1010waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\<AbilityStage>): void; 1011 1012Waits 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. 1013 1014**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1015 1016**Parameters** 1017 1018| Name | Type | Mandatory| Description | 1019| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 1020| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1021| 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. | 1022 1023**Example** 1024 1025```ts 1026let abilityDelegator; 1027 1028function onAbilityCreateCallback(data) { 1029 console.info('onAbilityCreateCallback'); 1030} 1031 1032let monitor = { 1033 moduleName: 'moduleName', 1034 srcEntrance: 'srcEntrance', 1035}; 1036 1037abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1038abilityDelegator.waitAbilityStageMonitor(monitor, (err : any, data : any) => { 1039 console.info('waitAbilityStageMonitor callback'); 1040}); 1041``` 1042 1043### waitAbilityStageMonitor<sup>9+</sup> 1044 1045waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise\<AbilityStage>; 1046 1047Waits 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. 1048 1049**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1050 1051**Parameters** 1052 1053| Name | Type | Mandatory| Description | 1054| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1055| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1056| timeout | number | No | Maximum waiting time, in milliseconds.| 1057 1058**Return value** 1059 1060| Type | Description | 1061| -------------- | ------------------- | 1062| Promise\<AbilityStage> | Promise used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned.| 1063 1064**Example** 1065 1066```ts 1067let abilityDelegator; 1068 1069function onAbilityCreateCallback(data) { 1070 console.info('onAbilityCreateCallback'); 1071} 1072 1073let monitor = { 1074 moduleName: 'moduleName', 1075 srcEntrance: 'srcEntrance', 1076}; 1077 1078abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1079abilityDelegator.waitAbilityStageMonitor(monitor).then((data : any) => { 1080 console.info('waitAbilityStageMonitor promise'); 1081}); 1082``` 1083 1084### waitAbilityStageMonitor<sup>9+</sup> 1085 1086waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback\<AbilityStage>): void; 1087 1088Waits 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. 1089 1090**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1091 1092**Parameters** 1093 1094| Name | Type | Mandatory| Description | 1095| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1096| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| 1097| timeout | number | No | Maximum waiting time, in milliseconds.| 1098| 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. | 1099 1100**Example** 1101 1102```ts 1103let abilityDelegator; 1104let timeout = 100; 1105 1106function onAbilityCreateCallback(data) { 1107 console.info('onAbilityCreateCallback'); 1108} 1109 1110let monitor = { 1111 moduleName: 'moduleName', 1112 srcEntrance: 'srcEntrance', 1113}; 1114 1115abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); 1116abilityDelegator.waitAbilityStageMonitor(monitor, timeout, (err : any, data : any) => { 1117 console.info('waitAbilityStageMonitor callback'); 1118}); 1119``` 1120