1# @ohos.app.ability.abilityManager (AbilityManager) (System API) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @duan-sizhao; @Luobniz21--> 6<!--Designer: @ccllee1--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10The AbilityManager module provides APIs for obtaining, adding, and updating ability information and running status information. 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15> The APIs of this module are system APIs and cannot be called by third-party applications. 16 17## Modules to Import 18 19```ts 20import { abilityManager } from '@kit.AbilityKit'; 21``` 22 23## UserStatus<sup>12+</sup> 24 25Enumerates the assertion result for different user operations. 26 27**System API**: This is a system API. 28 29**System capability**: SystemCapability.Ability.AbilityRuntime.Core 30 31| Name| Value| Description| 32| -------- | -------- | -------- | 33| ASSERT_TERMINATE | 0 | Assertion result of the terminate operation.| 34| ASSERT_CONTINUE | 1 | Assertion result of the continue operation.| 35| ASSERT_RETRY | 2 | Assertion result of the retry operation.| 36 37## updateConfiguration 38 39updateConfiguration(config: Configuration, callback: AsyncCallback\<void>): void 40 41Updates the configuration. This API uses an asynchronous callback to return the result. 42 43**System API**: This is a system API. 44 45**Permission required**: ohos.permission.UPDATE_CONFIGURATION 46 47**System capability**: SystemCapability.Ability.AbilityRuntime.Core 48 49**Parameters** 50 51| Name | Type | Mandatory | Description | 52| --------- | ---------------------------------------- | ---- | -------------- | 53| config | [Configuration](js-apis-app-ability-configuration.md) | Yes | New configuration. You only need to configure the items to be updated.| 54| callback | AsyncCallback\<void> | Yes | Callback used to return the API call result. You can perform error handling or custom processing in it. | 55 56**Error codes** 57 58For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 59 60| ID| Error Message| 61| ------- | -------- | 62| 201 | Permission denied. | 63| 202 | Not System App. Interface caller is not a system app. | 64| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 65| 16000050 | Internal error. | 66 67**Example** 68 69```ts 70import { abilityManager, Configuration, ConfigurationConstant } from '@kit.AbilityKit'; 71import { BusinessError } from '@kit.BasicServicesKit'; 72 73const config: Configuration = { 74 language: 'Zh-Hans', // Simplified Chinese. 75 colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT, // Light theme. 76 direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL, // Vertical direction. 77 screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI, // The screen pixel density is 'sdpi'. 78 displayId: 1, // The application is displayed on the display with ID 1. 79 hasPointerDevice: true, // A pointer device is connected. 80}; 81 82try { 83 abilityManager.updateConfiguration(config, (err: BusinessError) => { 84 if (err) { 85 console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`); 86 } else { 87 console.info('updateConfiguration success.'); 88 } 89 }); 90} catch (paramError) { 91 let code: number = (paramError as BusinessError).code; 92 let message: string = (paramError as BusinessError).message; 93 console.error(`error.code: ${code}, error.message: ${message}`); 94} 95``` 96 97## updateConfiguration 98 99updateConfiguration(config: Configuration): Promise\<void> 100 101Updates the configuration. This API uses a promise to return the result. 102 103**System API**: This is a system API. 104 105**Permission required**: ohos.permission.UPDATE_CONFIGURATION 106 107**System capability**: SystemCapability.Ability.AbilityRuntime.Core 108 109**Parameters** 110 111| Name | Type | Mandatory | Description | 112| --------- | ---------------------------------------- | ---- | -------------- | 113| config | [Configuration](js-apis-app-ability-configuration.md) | Yes | New configuration. You only need to configure the items to be updated.| 114 115**Return value** 116 117| Type | Description | 118| ---------------------------------------- | ------- | 119| Promise\<void> | Promise used to return the API call result. You can perform error handling or custom processing in it.| 120 121**Error codes** 122 123For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 124 125| ID| Error Message| 126| ------- | -------- | 127| 201 | Permission denied. | 128| 202 | Not System App. Interface caller is not a system app. | 129| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 130| 16000050 | Internal error. | 131 132**Example** 133 134```ts 135import { abilityManager, Configuration, ConfigurationConstant } from '@kit.AbilityKit'; 136import { BusinessError } from '@kit.BasicServicesKit'; 137 138const config: Configuration = { 139 language: 'Zh-Hans', // Simplified Chinese. 140 colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT, // Light theme. 141 direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL, // Vertical direction. 142 screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI, // The screen pixel density is 'sdpi'. 143 displayId: 1, // The application is displayed on the display with ID 1. 144 hasPointerDevice: true, // A pointer device is connected. 145}; 146 147try { 148 abilityManager.updateConfiguration(config).then(() => { 149 console.info('updateConfiguration success.'); 150 }).catch((err: BusinessError) => { 151 console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`); 152 }); 153} catch (paramError) { 154 let code: number = (paramError as BusinessError).code; 155 let message: string = (paramError as BusinessError).message; 156 console.error(`error.code: ${code}, error.message: ${message}`); 157} 158``` 159 160## getAbilityRunningInfos 161 162getAbilityRunningInfos(callback: AsyncCallback\<Array\<AbilityRunningInfo>>): void 163 164Obtains the UIAbility running information. This API uses an asynchronous callback to return the result. 165 166**System API**: This is a system API. 167 168**Required permissions**: ohos.permission.GET_RUNNING_INFO 169 170**System capability**: SystemCapability.Ability.AbilityRuntime.Core 171 172**Parameters** 173 174| Name | Type | Mandatory | Description | 175| --------- | ---------------------------------------- | ---- | -------------- | 176| callback | AsyncCallback\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>> | Yes | Callback used to return the API call result and the ability running information. You can perform error handling or custom processing in it. | 177 178**Error codes** 179 180For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 181 182| ID| Error Message| 183| ------- | -------- | 184| 202 | Not System App. Interface caller is not a system app. | 185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 186| 16000050 | Internal error. | 187 188**Example** 189 190```ts 191import { abilityManager } from '@kit.AbilityKit'; 192import { BusinessError } from '@kit.BasicServicesKit'; 193 194try { 195 abilityManager.getAbilityRunningInfos((err: BusinessError, data: Array<abilityManager.AbilityRunningInfo>) => { 196 if (err) { 197 console.error(`getAbilityRunningInfos fail, error: ${JSON.stringify(err)}`); 198 } else { 199 console.info(`getAbilityRunningInfos success, data: ${JSON.stringify(data)}`); 200 } 201 }); 202} catch (paramError) { 203 let code: number = (paramError as BusinessError).code; 204 let message: string = (paramError as BusinessError).message; 205 console.error(`error.code: ${code}, error.message: ${message}`); 206} 207``` 208 209## getExtensionRunningInfos 210 211getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\<Array\<ExtensionRunningInfo>>): void 212 213Obtains the ExtensionAbility running information. This API uses an asynchronous callback to return the result. 214 215**System API**: This is a system API. 216 217**Required permissions**: ohos.permission.GET_RUNNING_INFO 218 219**System capability**: SystemCapability.Ability.AbilityRuntime.Core 220 221**Parameters** 222 223| Name | Type | Mandatory | Description | 224| --------- | ---------------------------------------- | ---- | -------------- | 225| upperLimit | number | Yes| Maximum number of messages that can be obtained. The maximum value is 2<sup>31</sup>-1.| 226| callback | AsyncCallback\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo-sys.md)>> | Yes | Callback used to return the API call result and the ExtensionAbility running information. You can perform error handling or custom processing in it. | 227 228**Error codes** 229 230For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 231 232| ID| Error Message| 233| ------- | -------- | 234| 202 | Not System App. Interface caller is not a system app. | 235| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 236| 16000050 | Internal error. | 237 238**Example** 239 240```ts 241import { abilityManager } from '@kit.AbilityKit'; 242import { BusinessError } from '@kit.BasicServicesKit'; 243 244let upperLimit = 10; 245 246try { 247 abilityManager.getExtensionRunningInfos(upperLimit, (err: BusinessError, data: Array<abilityManager.ExtensionRunningInfo>) => { 248 if (err) { 249 console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`); 250 } else { 251 console.info(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`); 252 } 253 }); 254} catch (paramError) { 255 let code: number = (paramError as BusinessError).code; 256 let message: string = (paramError as BusinessError).message; 257 console.error(`error.code: ${code}, error.message: ${message}`); 258} 259``` 260 261## getExtensionRunningInfos 262 263getExtensionRunningInfos(upperLimit: number): Promise\<Array\<ExtensionRunningInfo>> 264 265Obtains the ExtensionAbility running information. This API uses a promise to return the result. 266 267**System API**: This is a system API. 268 269**Required permissions**: ohos.permission.GET_RUNNING_INFO 270 271**System capability**: SystemCapability.Ability.AbilityRuntime.Core 272 273**Parameters** 274 275| Name | Type | Mandatory | Description | 276| --------- | ---------------------------------------- | ---- | -------------- | 277| upperLimit | number | Yes| Maximum number of messages that can be obtained. The maximum value is 2<sup>31</sup>-1.| 278 279**Return value** 280 281| Type | Description | 282| ---------------------------------------- | ------- | 283| Promise\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo-sys.md)>> | Promise used to return the API call result and the ExtensionAbility running information. You can perform error handling or custom processing in it.| 284 285**Error codes** 286 287For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 288 289| ID| Error Message| 290| ------- | -------- | 291| 202 | Not System App. Interface caller is not a system app. | 292| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 293| 16000050 | Internal error. | 294 295**Example** 296 297```ts 298import { abilityManager } from '@kit.AbilityKit'; 299import { BusinessError } from '@kit.BasicServicesKit'; 300 301let upperLimit = 10; 302 303try { 304 abilityManager.getExtensionRunningInfos(upperLimit).then((data: Array<abilityManager.ExtensionRunningInfo>) => { 305 console.info(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`); 306 }).catch((err: BusinessError) => { 307 console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`); 308 }); 309} catch (paramError) { 310 let code: number = (paramError as BusinessError).code; 311 let message: string = (paramError as BusinessError).message; 312 console.error(`error.code: ${code}, error.message: ${message}`); 313} 314``` 315 316## getTopAbility 317 318getTopAbility(callback: AsyncCallback\<ElementName>): void 319 320Obtains the top ability, which is the ability that has the window focus. This API uses an asynchronous callback to return the result. 321 322**System API**: This is a system API. 323 324**System capability**: SystemCapability.Ability.AbilityRuntime.Core 325 326**Parameters** 327 328| Name | Type | Mandatory | Description | 329| --------- | ---------------------------------------- | ---- | -------------- | 330| callback | AsyncCallback\<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | Callback used to return the API call result and the element name of the top ability. You can perform error handling or custom processing in it. | 331 332**Error codes** 333 334For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 335 336| ID| Error Message| 337| ------- | -------- | 338| 202 | Not System App. Interface caller is not a system app. | 339| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 340| 16000050 | Internal error. | 341 342**Example** 343 344```ts 345import { abilityManager } from '@kit.AbilityKit'; 346import { BusinessError } from '@kit.BasicServicesKit'; 347 348abilityManager.getTopAbility((err: BusinessError, data) => { 349 if (err) { 350 console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`); 351 } else { 352 console.info(`getTopAbility success, data: ${JSON.stringify(data)}`); 353 } 354}); 355``` 356 357## getTopAbility 358 359getTopAbility(): Promise\<ElementName> 360 361Obtains the top ability, which is the ability that has the window focus. This API uses a promise to return the result. 362 363**System API**: This is a system API. 364 365**System capability**: SystemCapability.Ability.AbilityRuntime.Core 366 367**Return value** 368 369| Type | Description | 370| ---------------------------------------- | ------- | 371| Promise\<[ElementName](js-apis-bundleManager-elementName.md)>| Promise used to return the API call result and the element name of the top ability. You can perform error handling or custom processing in it.| 372 373**Error codes** 374 375For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 376 377| ID| Error Message| 378| ------- | -------- | 379| 202 | Not System App. Interface caller is not a system app. | 380| 16000050 | Internal error. | 381 382**Example** 383 384```ts 385import { abilityManager } from '@kit.AbilityKit'; 386import { BusinessError } from '@kit.BasicServicesKit'; 387 388abilityManager.getTopAbility().then((data) => { 389 console.info(`getTopAbility success, data: ${JSON.stringify(data)}`); 390}).catch((err: BusinessError) => { 391 console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`); 392}); 393``` 394 395## acquireShareData<sup>10+</sup> 396 397acquireShareData(missionId: number, callback: AsyncCallback\<Record\<string, Object>>): void 398 399Called by a system dialog box to obtain shared data, which is set by the target UIAbility through **onShare()**. This API uses an asynchronous callback to return the result. 400 401**System API**: This is a system API. 402 403**System capability**: SystemCapability.Ability.AbilityRuntime.Core 404 405**Parameters** 406 407| Name | Type | Mandatory | Description | 408| --------- | ---------------------------------------- | ---- | -------------- | 409| missionId | number | Yes| Mission ID on the target application. The maximum value is 2<sup>31</sup>-1.| 410| callback | AsyncCallback\<Record\<string, Object>> | Yes | Callback used to return the API call result and the shared data. You can perform error handling or custom processing in it. | 411 412**Error codes** 413 414For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 415 416| ID| Error Message| 417| ------- | -------- | 418| 202 | Not System App. Interface caller is not a system app. | 419| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 420| 16000050 | Internal error. | 421 422**Example** 423 424```ts 425import { abilityManager } from '@kit.AbilityKit'; 426import { BusinessError } from '@kit.BasicServicesKit'; 427 428try { 429 abilityManager.acquireShareData(1, (err: BusinessError, wantParam: Record<string, Object>) => { 430 if (err) { 431 console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`); 432 } else { 433 console.info(`acquireShareData success, data: ${JSON.stringify(wantParam)}`); 434 } 435 }); 436} catch (paramError) { 437 let code: number = (paramError as BusinessError).code; 438 let message: string = (paramError as BusinessError).message; 439 console.error(`error.code: ${code}, error.message: ${message}`); 440} 441``` 442 443## acquireShareData<sup>10+</sup> 444 445acquireShareData(missionId: number): Promise\<Record\<string, Object>> 446 447Called by a system dialog box to obtain shared data, which is set by the target UIAbility through **onShare()**. This API uses a promise to return the result. 448 449**System API**: This is a system API. 450 451**System capability**: SystemCapability.Ability.AbilityRuntime.Core 452 453**Parameters** 454 455| Name | Type | Mandatory | Description | 456| --------- | ---------------------------------------- | ---- | -------------- | 457| missionId | number | Yes| Mission ID on the target application. The maximum value is 2<sup>31</sup>-1.| 458 459**Return value** 460 461| Type | Description | 462| ---------------------------------------- | ------- | 463| Promise\<Record\<string, Object>>| Promise used to return the API call result and the shared data. You can perform error handling or custom processing in it.| 464 465**Error codes** 466 467For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 468 469| ID| Error Message| 470| ------- | -------- | 471| 202 | Not System App. Interface caller is not a system app. | 472| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 473| 16000050 | Internal error. | 474 475**Example** 476 477```ts 478import { abilityManager } from '@kit.AbilityKit'; 479import { BusinessError } from '@kit.BasicServicesKit'; 480 481try { 482 abilityManager.acquireShareData(1).then((wantParam: Record<string, Object>) => { 483 console.info(`acquireShareData success, data: ${JSON.stringify(wantParam)}`); 484 }).catch((err: BusinessError) => { 485 console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`); 486 }); 487} catch (paramError) { 488 let code: number = (paramError as BusinessError).code; 489 let message: string = (paramError as BusinessError).message; 490 console.error(`error.code: ${code}, error.message: ${message}`); 491} 492``` 493 494## notifySaveAsResult<sup>10+</sup> 495 496notifySaveAsResult(parameter: AbilityResult, requestCode: number, callback: AsyncCallback\<void>): void 497 498Used by the [Data Loss Prevention (DLP)](../apis-data-protection-kit/js-apis-dlppermission.md) management application to notify a sandbox application of the data saving result. This API uses an asynchronous callback to return the result. 499 500**Model restriction**: This API can be used only in the stage model. 501 502**System API**: This is a system API. 503 504**System capability**: SystemCapability.Ability.AbilityRuntime.Core 505 506**Parameters** 507 508| Name | Type | Mandatory | Description | 509| --------- | ---------------------------------------- | ---- | -------------- | 510| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the initiator UIAbility.| 511| requestCode | number | Yes| Request code passed in by the DLP management application. | 512| callback | AsyncCallback<void\> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 513 514**Error codes** 515 516For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 517 518| ID| Error Message| 519| ------- | -------- | 520| 201 | Permission denied. | 521| 202 | Not System App. Interface caller is not a system app. | 522| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 523| 16000050 | Internal error. | 524 525**Example** 526 527```ts 528import { abilityManager, Want, common } from '@kit.AbilityKit'; 529import { BusinessError } from '@kit.BasicServicesKit'; 530 531let want: Want = { 532 bundleName: 'com.example.myapplication', 533 abilityName: 'EntryAbility' 534}; 535let resultCode = 100; 536// AbilityResult information returned to the initiator of the save-as behavior. 537let abilityResult: common.AbilityResult = { 538 want, 539 resultCode 540}; 541let requestCode = 1; 542try { 543 abilityManager.notifySaveAsResult(abilityResult, requestCode, (err: BusinessError) => { 544 if (err && err.code != 0) { 545 console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`); 546 } else { 547 console.info(`notifySaveAsResult success`); 548 } 549 }); 550} catch (paramError) { 551 let code: number = (paramError as BusinessError).code; 552 let message: string = (paramError as BusinessError).message; 553 console.error(`error.code: ${code}, error.message: ${message}`); 554} 555``` 556 557## notifySaveAsResult<sup>10+</sup> 558 559notifySaveAsResult(parameter: AbilityResult, requestCode: number): Promise\<void> 560 561Used by the [Data Loss Prevention (DLP)](../apis-data-protection-kit/js-apis-dlppermission.md) management application to notify a sandbox application of the data saving result. This API uses a promise to return the result. 562 563**Model restriction**: This API can be used only in the stage model. 564 565**System API**: This is a system API. 566 567**System capability**: SystemCapability.Ability.AbilityRuntime.Core 568 569**Parameters** 570 571| Name | Type | Mandatory | Description | 572| --------- | ---------------------------------------- | ---- | -------------- | 573| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the initiator UIAbility.| 574| requestCode | number | Yes| Request code passed in by the DLP management application. | 575 576**Return value** 577 578| Type | Description | 579| ---------------------------------------- | ------- | 580| Promise<void\>| Promise that returns no value.| 581 582**Error codes** 583 584For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 585 586| ID| Error Message| 587| ------- | -------- | 588| 201 | Permission denied. | 589| 202 | Not System App. Interface caller is not a system app. | 590| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 591| 16000050 | Internal error. | 592 593**Example** 594 595```ts 596import { abilityManager, Want, common } from '@kit.AbilityKit'; 597import { BusinessError } from '@kit.BasicServicesKit'; 598 599let want: Want = { 600 bundleName: 'com.example.myapplication', 601 abilityName: 'EntryAbility' 602}; 603let resultCode = 100; 604// AbilityResult information returned to the initiator of the save-as behavior. 605let abilityResult: common.AbilityResult = { 606 want, 607 resultCode 608}; 609let requestCode = 1; 610try { 611 abilityManager.notifySaveAsResult(abilityResult, requestCode).then(() => { 612 console.info(`notifySaveAsResult success`); 613 }).catch((err: BusinessError) => { 614 console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`); 615 }); 616} catch (paramError) { 617 let code: number = (paramError as BusinessError).code; 618 let message: string = (paramError as BusinessError).message; 619 console.error(`error.code: ${code}, error.message: ${message}`); 620} 621``` 622 623## abilityManager.on('abilityForegroundState')<sup>11+</sup> 624 625on(type: 'abilityForegroundState', observer: AbilityForegroundStateObserver): void 626 627Registers an observer to listen for ability start or exit events. 628 629**System API**: This is a system API. 630 631**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER 632 633**System capability**: SystemCapability.Ability.AbilityRuntime.Core 634 635**Parameters** 636 637| Name| Type| Mandatory| Description| 638| -------- | -------- | -------- | -------- | 639| type | string | Yes| Event type. It is fixed at **'abilityForegroundState'**.| 640| observer | [AbilityForegroundStateObserver](js-apis-inner-application-abilityForegroundStateObserver-sys.md) | Yes| Observer used to listen for ability start or exit events.| 641 642**Error codes** 643 644For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 645 646| ID| Error Message| 647| ------- | -------- | 648| 201 | Permission denied. | 649| 202 | Not System App. Interface caller is not a system app. | 650| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 651| 16000050 | Internal error. | 652 653**Example** 654 655```ts 656import { abilityManager } from '@kit.AbilityKit'; 657import { BusinessError } from '@kit.BasicServicesKit'; 658 659let observer: abilityManager.AbilityForegroundStateObserver = { 660 onAbilityStateChanged(abilityStateData) { 661 console.info(`onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); 662 }, 663}; 664try { 665 abilityManager.on('abilityForegroundState', observer); 666} catch (paramError) { 667 let code = (paramError as BusinessError).code; 668 let message = (paramError as BusinessError).message; 669 console.error(`error: ${code}, ${message} `); 670} 671``` 672 673## abilityManager.off('abilityForegroundState')<sup>11+</sup> 674 675off(type: 'abilityForegroundState', observer?: AbilityForegroundStateObserver): void 676 677Unregisters the observer used to listen for ability start or exit events. 678 679**System API**: This is a system API. 680 681**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER 682 683**System capability**: SystemCapability.Ability.AbilityRuntime.Core 684 685**Parameters** 686 687| Name| Type| Mandatory| Description| 688| -------- | -------- | -------- | -------- | 689| type | string | Yes| Event type. It is fixed at **'abilityForegroundState'**.| 690| observer | [AbilityForegroundStateObserver](js-apis-inner-application-abilityForegroundStateObserver-sys.md) | No| Observer used to listen for ability start or exit events. If this parameter is not set, all observers associated with the specified event are deregistered. If this parameter is set, only the specified observer is deregistered.| 691 692**Error codes** 693 694For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 695 696| ID| Error Message| 697| ------- | -------- | 698| 201 | Permission denied. | 699| 202 | Not System App. Interface caller is not a system app. | 700| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 701| 16000050 | Internal error. | 702 703**Example** 704 705```ts 706import { abilityManager } from '@kit.AbilityKit'; 707import { BusinessError } from '@kit.BasicServicesKit'; 708 709let observer_: abilityManager.AbilityForegroundStateObserver | undefined; 710// 1. Register an observer to listen for ability start or exit events. 711let observer: abilityManager.AbilityForegroundStateObserver = { 712 onAbilityStateChanged(abilityStateData: abilityManager.AbilityStateData) { 713 console.info(`onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`); 714 }, 715}; 716try { 717 abilityManager.on('abilityForegroundState', observer); 718 observer_ = observer; 719} catch (paramError) { 720 let code = (paramError as BusinessError).code; 721 let message = (paramError as BusinessError).message; 722 console.error(`error: ${code}, ${message} `); 723} 724 725// 2. Deregister the observer. 726try { 727 abilityManager.off('abilityForegroundState', observer_); 728} catch (paramError) { 729 let code = (paramError as BusinessError).code; 730 let message = (paramError as BusinessError).message; 731 console.error(`error: ${code}, ${message} `); 732} 733``` 734 735## abilityManager.getForegroundUIAbilities<sup>11+</sup> 736 737getForegroundUIAbilities(callback: AsyncCallback\<Array\<AbilityStateData>>): void 738 739Obtains the information about the UIAbilities of an application that is running in the foreground. This API uses an asynchronous callback to return the result. 740 741**System API**: This is a system API. 742 743**Required permissions**: ohos.permission.GET_RUNNING_INFO 744 745**System capability**: SystemCapability.Ability.AbilityRuntime.Core 746 747**Parameters** 748 749 | Name| Type| Mandatory| Description| 750 | -------- | -------- | -------- | -------- | 751 | callback | AsyncCallback\<Array\<[AbilityStateData](js-apis-inner-application-abilityStateData.md)>> | Yes|Callback used to return the API call result and the UIAbility information. You can perform error handling or custom processing in it.| 752 753**Error codes** 754 755For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 756 757| ID| Error Message| 758| ------- | -------- | 759| 201 | Permission denied. | 760| 202 | Not System App. Interface caller is not a system app. | 761| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 762| 16000050 | Internal error. | 763 764**Example** 765 766```ts 767import { abilityManager } from '@kit.AbilityKit'; 768import { BusinessError } from '@kit.BasicServicesKit'; 769 770abilityManager.getForegroundUIAbilities((err: BusinessError, data: Array<abilityManager.AbilityStateData>) => { 771 if (err) { 772 console.error(`Get foreground ui abilities failed, error: ${JSON.stringify(err)}`); 773 } else { 774 console.info(`Get foreground ui abilities data is: ${JSON.stringify(data)}`); 775 } 776}); 777``` 778 779## abilityManager.getForegroundUIAbilities<sup>11+</sup> 780 781getForegroundUIAbilities(): Promise\<Array\<AbilityStateData>> 782 783Obtains the information about the UIAbilities of an application that is running in the foreground. This API uses a promise to return the result. 784 785**System API**: This is a system API. 786 787**Required permissions**: ohos.permission.GET_RUNNING_INFO 788 789**System capability**: SystemCapability.Ability.AbilityRuntime.Core 790 791**Return value** 792 793| Type| Description| 794| -------- | -------- | 795| Promise\<Array\<[AbilityStateData](js-apis-inner-application-abilityStateData.md)>> | Promise used to return the API call result and the UIAbility information. You can perform error handling or custom processing in it.| 796 797**Error codes** 798 799For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 800 801| ID| Error Message| 802| ------- | -------- | 803| 201 | Permission denied. | 804| 202 | Not System App. Interface caller is not a system app. | 805| 16000050 | Internal error. | 806 807**Example** 808 809```ts 810import { abilityManager } from '@kit.AbilityKit'; 811import { BusinessError } from '@kit.BasicServicesKit'; 812 813abilityManager.getForegroundUIAbilities().then((data: Array<abilityManager.AbilityStateData>) => { 814 console.info(`Get foreground ui abilities data is: ${JSON.stringify(data)}`); 815}).catch((error: BusinessError) => { 816 console.error(`Get foreground ui abilities failed, error: ${JSON.stringify(error)}`); 817}); 818``` 819 820## abilityManager.notifyDebugAssertResult<sup>12+</sup> 821 822notifyDebugAssertResult(sessionId: string, status: UserStatus): Promise\<void> 823 824Notifies the application of the assertion result. This API uses a promise to return the result. 825 826**System API**: This is a system API. 827 828**Required permissions**: ohos.permission.NOTIFY_DEBUG_ASSERT_RESULT 829 830**System capability**: SystemCapability.Ability.AbilityRuntime.Core 831 832**Parameters** 833 834| Name| Type| Mandatory| Description| 835| ------- | -------- | -------- | -------- | 836| sessionId | string | Yes| Session ID of the AssertFault.| 837| status | [UserStatus](#userstatus12) | Yes| Assertion result of the user operation.| 838 839**Return value** 840 841| Type| Description| 842| -------- | -------- | 843| Promise\<void> | Promise that returns no value.| 844 845**Error codes** 846 847For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 848 849| ID| Error Message| 850| ------- | -------- | 851| 201 | Permission denied. | 852| 202 | Not System App. Interface caller is not a system app. | 853| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 854| 16000050 | Internal error. | 855 856**Example** 857 858```ts 859import { abilityManager, UIExtensionAbility, wantConstant, Want, UIExtensionContentSession } from '@kit.AbilityKit'; 860import { BusinessError } from '@kit.BasicServicesKit'; 861 862export default class UiExtAbility extends UIExtensionAbility { 863 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 864 let sessionId: string = ''; 865 if (want.parameters) { 866 sessionId = want.parameters[wantConstant.Params.ASSERT_FAULT_SESSION_ID] as string; 867 } 868 let status = abilityManager.UserStatus.ASSERT_TERMINATE; 869 abilityManager.notifyDebugAssertResult(sessionId, status).then(() => { 870 console.info('notifyDebugAssertResult success.'); 871 }).catch((err: BusinessError) => { 872 console.error(`notifyDebugAssertResult failed, error: ${JSON.stringify(err)}`); 873 }); 874 } 875} 876``` 877 878## abilityManager.isEmbeddedOpenAllowed<sup>12+</sup> 879 880isEmbeddedOpenAllowed(context: Context, appId: string): Promise\<boolean> 881 882Checks whether the [EmbeddableUIAbility](js-apis-app-ability-embeddableUIAbility.md) can be started in embedded mode. This API uses a promise to return the result. 883 884**System API**: This is a system API. 885 886**System capability**: SystemCapability.Ability.AbilityRuntime.Core 887 888**Parameters** 889 890| Name| Type| Mandatory| Description| 891| ------- | -------- | -------- | -------- | 892| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the caller.| 893| appId | string | Yes| Unique ID of the application, which is allocated by the cloud.| 894 895**Return value** 896 897| Type| Description| 898| -------- | -------- | 899| Promise\<boolean> | Promise used to return the result. **true** if embedded startup is allowed, **false** otherwise.| 900 901**Error codes** 902 903For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 904 905| ID| Error Message| 906| ------- | -------- | 907| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 908| 16000050 | Internal error. | 909 910**Example** 911 912```ts 913import { abilityManager, UIAbility } from '@kit.AbilityKit'; 914import { BusinessError } from '@kit.BasicServicesKit'; 915 916export default class EntryAbility extends UIAbility { 917 onForeground() { 918 let appId: string = '6918661953712445909'; 919 try { 920 abilityManager.isEmbeddedOpenAllowed(this.context, appId).then((data) => { 921 console.info(`isEmbeddedOpenAllowed data: ${JSON.stringify(data)}`); 922 }).catch((err: BusinessError) => { 923 console.error(`isEmbeddedOpenAllowed failed, code is ${err.code}, message is ${err.message}`); 924 }); 925 } catch (err) { 926 // Process input parameter errors. 927 console.error(`param is invalid, code is ${err.code}, message is ${err.message}`); 928 } 929 } 930} 931``` 932 933## abilityManager.setResidentProcessEnabled<sup>12+</sup> 934 935setResidentProcessEnabled(bundleName: string, enable: boolean): Promise\<void> 936 937Enables or disables the resident process of an application. 938 939**System API**: This is a system API. 940 941**System capability**: SystemCapability.Ability.AbilityRuntime.Core 942 943**Parameters** 944 945| Name| Type| Mandatory| Description| 946| ------- | -------- | -------- | -------- | 947| bundleName | string | Yes| Bundle name of the resident process.| 948| enable | boolean | Yes| Whether to enable or disable the resident process. **true** to enable, **false** otherwise.| 949 950**Return value** 951 952| Type| Description| 953| -------- | -------- | 954| Promise\<void> | Promise that returns no value.| 955 956**Error codes** 957 958For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 959 960| ID| Error Message| 961| ------- | -------- | 962| 202 | Not a system application. | 963| 401 | Parameter error. Possible cause: 1.Non empty package name needs to be provided, 2.The second parameter needs to provide a Boolean type setting value | 964| 16000050 | Internal error. | 965| 16200006 | The caller application can only set the resident status of the configured process. | 966 967**Example** 968 969```ts 970import { abilityManager } from '@kit.AbilityKit'; 971import { BusinessError } from '@kit.BasicServicesKit'; 972 973try { 974 let residentProcessBundleName: string = 'com.xxx.xxxxxx'; 975 let enable: boolean = false; 976 abilityManager.setResidentProcessEnabled(residentProcessBundleName, enable) 977 .then(() => { 978 console.info('setResidentProcessEnabled success.'); 979 }) 980 .catch((err: BusinessError) => { 981 console.error(`setResidentProcessEnabled fail, err: ${JSON.stringify(err)}`); 982 }); 983} catch (err) { 984 let code = (err as BusinessError).code; 985 let message = (err as BusinessError).message; 986 console.error(`setResidentProcessEnabled failed, code is ${code}, message is ${message}`); 987} 988``` 989 990## AtomicServiceStartupRule<sup>18+</sup> 991 992Describes the rule for launching an embedded atomic service. 993 994**System API**: This is a system API. 995 996**System capability**: SystemCapability.Ability.AbilityRuntime.Core 997 998| Name| Type| Read-Only| Optional| Description| 999| -------- | ---------| ---- | ---- | --------- | 1000| isOpenAllowed | boolean | No | No | Whether launching the atomic service is allowed. **true** if allowed, **false** otherwise.| 1001| isEmbeddedAllowed | boolean | No | No | Whether launching the embedded atomic service is allowed. **true** if allowed, **false** otherwise.| 1002 1003## abilityManager.queryAtomicServiceStartupRule<sup>18+</sup> 1004 1005queryAtomicServiceStartupRule(context: Context, appId: string): Promise\<AtomicServiceStartupRule> 1006 1007Obtains the rule for launching an [EmbeddableUIAbility](js-apis-app-ability-embeddableUIAbility.md) in embedded mode. This API uses a promise to return the result. 1008 1009**System API**: This is a system API. 1010 1011**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1012 1013**Parameters** 1014 1015| Name| Type| Mandatory| Description| 1016| ------- | -------- | -------- | -------- | 1017| context | [Context](js-apis-inner-application-context.md) | Yes| Context of the caller.<br>Note: Currently, only [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) is supported.| 1018| appId | string | Yes| Unique ID of the application, which is allocated by the cloud.| 1019 1020**Return value** 1021 1022| Type| Description| 1023| -------- | -------- | 1024| Promise\<[AtomicServiceStartupRule](#atomicservicestartuprule18)> | Promise used to return the rule for launching the embedded atomic service.| 1025 1026**Error codes** 1027 1028For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1029 1030| ID| Error Message| 1031| ------- | -------- | 1032| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1033| 801 | Capability not support. | 1034| 16000050 | Internal error. | 1035 1036**Example** 1037 1038```ts 1039import { abilityManager, UIAbility } from '@kit.AbilityKit'; 1040import { BusinessError } from '@kit.BasicServicesKit'; 1041 1042export default class EntryAbility extends UIAbility { 1043 onForeground() { 1044 let appId: string = '6918661953712445909'; 1045 try { 1046 abilityManager.queryAtomicServiceStartupRule(this.context, appId).then((data: abilityManager.AtomicServiceStartupRule) => { 1047 console.info(`queryAtomicServiceStartupRule data: ${JSON.stringify(data)}`); 1048 }).catch((err: BusinessError) => { 1049 console.error(`queryAtomicServiceStartupRule failed, code is ${err.code}, message is ${err.message}`); 1050 }); 1051 } catch (err) { 1052 // Process input parameter errors. 1053 console.error(`param is invalid, code is ${err.code}, message is ${err.message}`); 1054 } 1055 } 1056} 1057``` 1058 1059## ExtensionRunningInfo 1060 1061type ExtensionRunningInfo = _ExtensionRunningInfo 1062 1063Defines the level-2 module ExtensionRunningInfo. 1064 1065**System API**: This is a system API. 1066 1067**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1068 1069| Type| Description| 1070| --- | --- | 1071| [_ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo-sys.md) | ExtensionRunningInfo, a level-2 module that provides running information of an ExtensionAbility.| 1072 1073## AbilityForegroundStateObserver<sup>11+</sup> 1074 1075type AbilityForegroundStateObserver = _AbilityForegroundStateObserver.default 1076 1077Defines the level-2 module AbilityForegroundStateObserver. 1078 1079**System API**: This is a system API. 1080 1081**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1082 1083| Type| Description| 1084| --- | --- | 1085| [_AbilityForegroundStateObserver.default](js-apis-inner-application-abilityForegroundStateObserver-sys.md) | AbilityForegroundStateObserver, a level-2 module that defines a listener to observe application foreground and background state changes.| 1086