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