1# @ohos.bundle.appControl (appControl) (System API) 2<!--Kit: Ability Kit--> 3<!--Subsystem: BundleManager--> 4<!--Owner: @wanghang904--> 5<!--Designer: @hanfeng6--> 6<!--Tester: @kongjing2--> 7<!--Adviser: @Brilliantry_Rui--> 8 9The module provides APIs for setting, obtaining, and deleting the disposed status of an application. An application in the disposed status is forbidden to run. When a user clicks the application icon on the home screen, the corresponding page is displayed based on the disposal intent. 10 11> **NOTE** 12> 13> 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. 14> 15> The APIs provided by this module are system APIs. 16 17## Modules to Import 18 19``` ts 20import appControl from '@ohos.bundle.appControl'; 21``` 22 23## appControl.setDisposedStatus 24 25setDisposedStatus(appId: string, disposedWant: Want): Promise\<void> 26 27Sets the disposed status for an application. This API uses a promise to return the result. If the operation is successful, **null** is returned. If the operation fails, an error message is returned. 28 29**System API**: This is a system API. 30 31**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 32 33**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 34 35**Parameters** 36 37| Name | Type | Mandatory | Description | 38| ----------- | ------ | ---- | --------------------------------------- | 39| appId | string | Yes | ID of the target application.<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 40| disposedWant | Want | Yes| Disposal intent of the application.| 41 42**Return value** 43 44| Type | Description | 45| ------------------------- | ------------------ | 46| Promise\<void> | Promise that returns no value.| 47 48**Error codes** 49 50For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 51 52| ID| Error Message | 53| ------ | -------------------------------------- | 54| 201 | Permission denied. | 55| 202 | Permission denied, non-system app called system api. | 56| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 57| 801 | Capability not supported. | 58| 17700005 | The specified app ID is an empty string. | 59 60**Example** 61 62```ts 63import { BusinessError } from '@ohos.base'; 64import Want from '@ohos.app.ability.Want'; 65import appControl from '@ohos.bundle.appControl'; 66 67let appId = "com.example.myapplication_xxxxx"; 68let want:Want = {bundleName: 'com.example.myapplication'}; 69 70try { 71 appControl.setDisposedStatus(appId, want) 72 .then(() => { 73 console.info('setDisposedStatus success'); 74 }).catch((error: BusinessError) => { 75 let message = (error as BusinessError).message; 76 console.error('setDisposedStatus failed ' + message); 77 }); 78} catch (error) { 79 let message = (error as BusinessError).message; 80 console.error('setDisposedStatus failed ' + message); 81} 82``` 83 84## appControl.setDisposedStatus 85 86setDisposedStatus(appId: string, disposedWant: Want, callback: AsyncCallback\<void>): void; 87 88Sets the disposed status for an application. This API uses an asynchronous callback to return the result. If the operation is successful, **null** is returned. If the operation fails, an error message is returned. 89 90**System API**: This is a system API. 91 92**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 93 94**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 95 96**Parameters** 97 98| Name | Type | Mandatory | Description | 99| ----------- | ------------------------------- | ---- | --------------------------------------- | 100| appId | string | Yes | ID of the target application.<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 101| disposedWant | Want | Yes| Disposal intent of the application.| 102| callback | AsyncCallback\<void> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) used to return the result. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.| 103 104**Error codes** 105 106For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 107 108| ID| Error Message | 109| ------ | -------------------------------------- | 110| 201 | Permission denied. | 111| 202 | Permission denied, non-system app called system api. | 112| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 113| 801 | Capability not supported. | 114| 17700005 | The specified app ID is an empty string. | 115 116**Example** 117 118```ts 119import appControl from '@ohos.bundle.appControl'; 120import { BusinessError } from '@ohos.base'; 121import Want from '@ohos.app.ability.Want'; 122 123let appId = "com.example.myapplication_xxxxx"; 124let want: Want = {bundleName: 'com.example.myapplication'}; 125 126try { 127 appControl.setDisposedStatus(appId, want, (error: BusinessError, data) => { 128 if (error) { 129 let message = (error as BusinessError).message; 130 console.error('setDisposedStatus failed ' + message); 131 return; 132 } 133 console.info('setDisposedStatus success'); 134 }); 135} catch (error) { 136 let message = (error as BusinessError).message; 137 console.error('setDisposedStatus failed ' + message); 138} 139``` 140 141## appControl.setDisposedStatusSync<sup>10+</sup> 142 143setDisposedStatusSync(appId: string, disposedWant: Want): void; 144 145Sets the disposed status for an application. This API returns the result synchronously. If the operation is successful, **null** is returned. If the operation fails, an error message is returned. 146 147**System API**: This is a system API. 148 149**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 150 151**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 152 153 154**Parameters** 155 156| Name | Type | Mandatory | Description | 157| ----------- | ------------------------------- | ---- | --------------------------------------- | 158| appId | string | Yes | ID of the target application.<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 159| disposedWant | Want | Yes| Disposal intent of the application.| 160 161**Error codes** 162 163For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 164 165| ID| Error Message | 166| ------ | -------------------------------------- | 167| 201 | Permission denied. | 168| 202 | Permission denied, non-system app called system api. | 169| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 170| 801 | Capability not supported. | 171| 17700005 | The specified app ID is an empty string. | 172 173**Example** 174 175```ts 176import appControl from '@ohos.bundle.appControl'; 177import { BusinessError } from '@ohos.base'; 178import Want from '@ohos.app.ability.Want'; 179 180let appId: string = "com.example.myapplication_xxxxx"; 181let want: Want = {bundleName: 'com.example.myapplication'}; 182 183try { 184 appControl.setDisposedStatusSync(appId, want); 185} catch (error) { 186 let message = (error as BusinessError).message; 187 console.error('setDisposedStatusSync failed ' + message); 188} 189``` 190 191## appControl.getDisposedStatus 192 193getDisposedStatus(appId: string): Promise\<Want>; 194 195Obtains the disposed status of an application. This API uses a promise to return the result. If the operation is successful, the disposed status of the application is returned. If the operation fails, an error message is returned. 196 197**System API**: This is a system API. 198 199**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 200 201**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 202 203**Parameters** 204 205| Name | Type | Mandatory | Description | 206| ----------- | ------ | ---- | --------------------------------------- | 207| appId | string | Yes | ID of the target application.<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 208 209**Return value** 210 211| Type | Description | 212| ------------------------- | ------------------ | 213| Promise\<Want> | Promise used to return the disposed status.| 214 215**Error codes** 216 217For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 218 219| ID| Error Message | 220| ------ | -------------------------------------- | 221| 201 | Permission denied. | 222| 202 | Permission denied, non-system app called system api. | 223| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 224| 801 | Capability not supported. | 225| 17700005 | The specified app ID is an empty string. | 226 227**Example** 228 229```ts 230import appControl from '@ohos.bundle.appControl'; 231import { BusinessError } from '@ohos.base'; 232 233let appId = "com.example.myapplication_xxxxx"; 234 235try { 236 appControl.getDisposedStatus(appId) 237 .then((data) => { 238 console.info('getDisposedStatus success. DisposedStatus: ' + JSON.stringify(data)); 239 }).catch((error: BusinessError) => { 240 let message = (error as BusinessError).message; 241 console.error('getDisposedStatus failed ' + message); 242 }); 243} catch (error) { 244 let message = (error as BusinessError).message; 245 console.error('getDisposedStatus failed ' + message); 246} 247``` 248 249## appControl.getDisposedStatus 250 251getDisposedStatus(appId: string, callback: AsyncCallback\<Want>): void; 252 253Obtains the disposed status of an application. This API uses an asynchronous callback to return the result. If the operation is successful, the disposed status of the application is returned. If the operation fails, an error message is returned. 254 255**System API**: This is a system API. 256 257**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 258 259**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 260 261**Parameters** 262 263| Name | Type | Mandatory | Description | 264| ----------- | ------ | ---- | --------------------------------------- | 265| appId | string | Yes | ID of the target application.<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 266| callback | AsyncCallback\<Want> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) used to return the result. If the operation is successful, **err** is **null** and **data** is the disposed status obtained; otherwise, **err** is an error object. | 267 268**Error codes** 269 270For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 271 272| ID| Error Message | 273| ------ | -------------------------------------- | 274| 201 | Permission denied. | 275| 202 | Permission denied, non-system app called system api. | 276| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 277| 801 | Capability not supported. | 278| 17700005 | The specified app ID is an empty string. | 279 280**Example** 281 282```ts 283import appControl from '@ohos.bundle.appControl'; 284import { BusinessError } from '@ohos.base'; 285 286let appId = "com.example.myapplication_xxxxx"; 287 288try { 289 appControl.getDisposedStatus(appId, (error, data) => { 290 if (error) { 291 let message = (error as BusinessError).message; 292 console.error('getDisposedStatus failed ' + message); 293 return; 294 } 295 console.info('getDisposedStatus success. DisposedStatus: ' + JSON.stringify(data)); 296 }); 297} catch (error) { 298 let message = (error as BusinessError).message; 299 console.error('getDisposedStatus failed ' + message); 300} 301``` 302 303## appControl.getDisposedStatusSync<sup>10+</sup> 304 305getDisposedStatusSync(appId: string): Want; 306 307Obtains the disposed status of an application. This API returns the result synchronously. If the operation is successful, the disposed status of the application is returned. If the operation fails, an error message is returned. 308 309**System API**: This is a system API. 310 311**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 312 313**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 314 315**Parameters** 316 317| Name | Type | Mandatory | Description | 318| ----------- | ------ | ---- | --------------------------------------- | 319| appId | string | Yes | ID of the target application.<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 320 321**Return value** 322 323| Type | Description | 324| ------------------------- | ------------------ | 325| Want | Disposed status.| 326 327**Error codes** 328 329For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 330 331| ID| Error Message | 332| ------ | -------------------------------------- | 333| 201 | Permission denied. | 334| 202 | Permission denied, non-system app called system api. | 335| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 336| 801 | Capability not supported. | 337| 17700005 | The specified app ID is an empty string. | 338 339**Example** 340 341```ts 342import appControl from '@ohos.bundle.appControl'; 343import { BusinessError } from '@ohos.base'; 344import Want from '@ohos.app.ability.Want'; 345 346let appId: string = "com.example.myapplication_xxxxx"; 347let want: Want; 348 349try { 350 want = appControl.getDisposedStatusSync(appId); 351} catch (error) { 352 let message = (error as BusinessError).message; 353 console.error('getDisposedStatusSync failed ' + message); 354} 355``` 356 357## appControl.deleteDisposedStatus 358 359deleteDisposedStatus(appId: string): Promise\<void> 360 361Deletes the disposed status for an application. This API uses a promise to return the result. If the operation is successful, **null** is returned. If the operation fails, an error message is returned. 362 363**System API**: This is a system API. 364 365**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 366 367**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 368 369**Parameters** 370 371| Name | Type | Mandatory | Description | 372| ----------- | ------ | ---- | --------------------------------------- | 373| appId | string | Yes | appId or appIdentifier of the target application. If a rule is set using appId, it must be deleted using appId; the same principle applies to appIdentifier.<br>**NOTE**<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application).<br>[appIdentifier](js-apis-bundleManager-bundleInfo.md#signatureinfo) is also the unique identifier of an application. It is a random string allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. For details about how to obtain the value, see [Obtaining appIdentifier of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 374 375**Return value** 376 377| Type | Description | 378| ------------------------- | ------------------ | 379| Promise\<void> | Promise that returns no value.| 380 381**Error codes** 382 383For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 384 385| ID| Error Message | 386| ------ | -------------------------------------- | 387| 201 | Permission denied. | 388| 202 | Permission denied, non-system app called system api. | 389| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 390| 801 | Capability not supported. | 391| 17700005 | The specified app ID is an empty string. | 392 393**Example** 394 395```ts 396import appControl from '@ohos.bundle.appControl'; 397import { BusinessError } from '@ohos.base'; 398 399let appId = "com.example.myapplication_xxxxx"; 400 401try { 402 appControl.deleteDisposedStatus(appId) 403 .then(() => { 404 console.info('deleteDisposedStatus success'); 405 }).catch((error: BusinessError) => { 406 let message = (error as BusinessError).message; 407 console.error('deleteDisposedStatus failed ' + message); 408 }); 409} catch (error) { 410 let message = (error as BusinessError).message; 411 console.error('deleteDisposedStatus failed ' + message); 412} 413``` 414 415## appControl.deleteDisposedStatus 416 417deleteDisposedStatus(appId: string, callback: AsyncCallback\<void>) : void 418 419Deletes the disposed status for an application. This API uses an asynchronous callback to return the result. If the operation is successful, **null** is returned. If the operation fails, an error message is returned. 420 421**System API**: This is a system API. 422 423**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 424 425**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 426 427**Parameters** 428 429| Name | Type | Mandatory | Description | 430| ----------- | ------ | ---- | --------------------------------------- | 431| appId | string | Yes | appId or appIdentifier of the target application. If a rule is set using appId, it must be deleted using appId; the same principle applies to appIdentifier.<br>**NOTE**<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application).<br>[appIdentifier](js-apis-bundleManager-bundleInfo.md#signatureinfo) is also the unique identifier of an application. It is a random string allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. For details about how to obtain the value, see [Obtaining appIdentifier of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 432| callback | AsyncCallback\<void> | Yes | [Callback](../apis-basic-services-kit/js-apis-base.md#asynccallback) used to return the result. If the operation is successful, **err** is **null**. otherwise, **err** is an error object. | 433 434**Error codes** 435 436For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 437 438| ID| Error Message | 439| ------ | -------------------------------------- | 440| 201 | Permission denied. | 441| 202 | Permission denied, non-system app called system api. | 442| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 443| 801 | Capability not supported. | 444| 17700005 | The specified app ID is an empty string. | 445 446**Example** 447 448```ts 449import appControl from '@ohos.bundle.appControl'; 450import { BusinessError } from '@ohos.base'; 451 452let appId = "com.example.myapplication_xxxxx"; 453try { 454 appControl.deleteDisposedStatus(appId, (error: BusinessError, data) => { 455 if (error) { 456 console.error('deleteDisposedStatus failed ' + error.message); 457 return; 458 } 459 console.info('deleteDisposedStatus success'); 460 }); 461} catch (error) { 462 let message = (error as BusinessError).message; 463 console.error('deleteDisposedStatus failed ' + message); 464} 465``` 466 467## appControl.deleteDisposedStatusSync<sup>10+</sup> 468 469deleteDisposedStatusSync(appId: string, appIndex:? number) : void 470 471Deletes the disposed status for an application or an application clone. This API returns the result synchronously. If the operation is successful, **null** is returned. If the operation fails, an error message is returned. 472 473**System API**: This is a system API. 474 475**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 476 477**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 478 479**Parameters** 480 481| Name | Type | Mandatory | Description | 482| ----------- | ------ | ---- | --------------------------------------- | 483| appId | string | Yes | appId or appIdentifier of the target application. If a rule is set using appId, it must be deleted using appId; the same principle applies to appIdentifier.<br>**NOTE**<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application).<br>[appIdentifier](js-apis-bundleManager-bundleInfo.md#signatureinfo) is also the unique identifier of an application. It is a random string allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. For details about how to obtain the value, see [Obtaining appIdentifier of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 484| appIndex<sup>12+</sup> | number | No | Index of the application clone. The default value is **0**.<br>The value **0** means to delete the disposed status of the main application. A value greater than 0 means to delete the disposed status of the application clone. | 485 486**Error codes** 487 488For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 489 490| ID| Error Message | 491| ------ | -------------------------------------- | 492| 201 | Permission denied. | 493| 202 | Permission denied, non-system app called system api. | 494| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 495| 801 | Capability not supported. | 496| 17700005 | The specified app ID is an empty string. | 497| 17700061 | AppIndex is not in the valid range. | 498 499**Example** 500 501```ts 502import appControl from '@ohos.bundle.appControl'; 503import { BusinessError } from '@ohos.base'; 504 505let appId: string = "com.example.myapplication_xxxxx"; 506 507try { 508 appControl.deleteDisposedStatusSync(appId, 1); 509} catch (error) { 510 let message = (error as BusinessError).message; 511 console.error('deleteDisposedStatusSync failed ' + message); 512} 513``` 514 515## Obtaining appId and appIdentifier of an Application 516 517**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. It can be obtained by calling [getBundleInfo](js-apis-bundleManager.md#bundlemanagergetbundleinfo14).<br> 518[appIdentifier](js-apis-bundleManager-bundleInfo.md#signatureinfo) is also the unique identifier of an application. It is a random string allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. 519 520**Example** 521 522```ts 523import bundleManager from '@ohos.bundle.bundleManager'; 524import { BusinessError } from '@ohos.base'; 525 526let bundleName = 'com.example.myapplication'; 527let appId: string; 528let appIdentifier: string; 529try { 530 bundleManager.getBundleInfo(bundleName, bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO) 531 .then((data) => { 532 appId = data.signatureInfo.appId; 533 appIdentifier = data.signatureInfo.appIdentifier; 534 console.info("appId is " + appId); 535 console.info("appIdentifier is " + appIdentifier); 536 }).catch((error: BusinessError) => { 537 let message = (error as BusinessError).message; 538 console.error("getBundleInfo failed " + message); 539 }); 540} catch (error) { 541 let message = (error as BusinessError).message; 542 console.error("getBundleInfo failed " + message); 543} 544``` 545 546## appControl.getDisposedRule<sup>11+</sup> 547 548getDisposedRule(appId: string, appIndex:? number): DisposedRule 549 550Obtains the disposed rule of an application or an application clone. 551 552**System API**: This is a system API. 553 554**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 555 556**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 557 558**Parameters** 559 560| Name | Type | Mandatory | Description | 561| ----------- | ------ | ---- | --------------------------------------- | 562| appId | string | Yes | appId or appIdentifier of the target application. If a rule is set using appId, it must be obtained using appId; the same principle applies to appIdentifier.<br>**NOTE**<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application).<br>[appIdentifier](js-apis-bundleManager-bundleInfo.md#signatureinfo) is also the unique identifier of an application. It is a random string allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. For details about how to obtain the value, see [Obtaining appIdentifier of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 563| appIndex<sup>12+</sup> | number | No | Index of the application clone. The default value is **0**.<br>The value **0** means to obtain the disposed rule of the main application. A value greater than 0 means to obtain the disposed rule of the application clone with the specified index. | 564 565**Return value** 566 567| Type | Description | 568| ------------------------- | ------------------ | 569| [DisposedRule](#disposedrule11) | Disposed rule of the application.| 570 571**Error codes** 572 573For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 574 575| ID| Error Message | 576| ------ | -------------------------------------- | 577| 201 | Permission denied. | 578| 202 | Permission denied, non-system app called system api. | 579| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 580| 801 | Capability not supported. | 581| 17700005 | The specified app ID is an empty string. | 582| 17700061 | AppIndex is not in the valid range. | 583 584**Example** 585 586```ts 587import appControl from '@ohos.bundle.appControl'; 588import { BusinessError } from '@ohos.base'; 589import Want from '@ohos.app.ability.Want'; 590 591let appId = "com.example.myapplication_xxxxx"; 592 593try { 594 let data = appControl.getDisposedRule(appId, 1); 595 console.info('getDisposedRule successfully. Data: ' + JSON.stringify(data)); 596} catch (error) { 597 let message = (error as BusinessError).message; 598 console.error('getDisposedRule failed ' + message); 599} 600``` 601 602## appControl.setDisposedRule<sup>11+</sup> 603 604setDisposedRule(appId: string, rule: DisposedRule, appIndex:? number): void 605 606Sets the disposed rule for an application or an application clone. 607 608**System API**: This is a system API. 609 610**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 611 612**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 613 614**Parameters** 615 616| Name | Type | Mandatory | Description | 617| ----------- | ------ | ---- | --------------------------------------- | 618| appId | string | Yes | appId or appIdentifier of the target application. If a rule is set using appId, it overwrites the one set with appIdentifier, and the reverse is also true.<br>**NOTE**<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application).<br>[appIdentifier](js-apis-bundleManager-bundleInfo.md#signatureinfo) is also the unique identifier of an application. It is a random string allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. For details about how to obtain the value, see [Obtaining appIdentifier of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 619| rule | [DisposedRule](#disposedrule11) | Yes| Disposed rule to set.| 620| appIndex<sup>12+</sup> | number | No | Index of the application clone. The default value is **0**.<br>The value **0** means to set the disposed rule for the main application. A value greater than 0 means to set the disposed rule for the application clone with the specified index. | 621 622**Error codes** 623 624For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 625 626| ID| Error Message | 627| ------ | -------------------------------------- | 628| 201 | Permission denied. | 629| 202 | Permission denied, non-system app called system api. | 630| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 631| 801 | Capability not supported. | 632| 17700005 | The specified app ID is an empty string. | 633| 17700061 | AppIndex is not in the valid range. | 634 635**Example** 636 637```ts 638import appControl from '@ohos.bundle.appControl'; 639import { BusinessError } from '@ohos.base'; 640import Want from '@ohos.app.ability.Want'; 641import bundleManager from '@ohos.bundle.bundleManager'; 642 643let appId = "com.example.myapplication_xxxxx"; 644let want: Want = { 645 bundleName: "com.example.myapplication", 646 moduleName: "entry", 647 abilityName: "EntryAbility" 648}; 649let elementName: bundleManager.ElementName = { 650 bundleName: "com.example.myapplication", 651 moduleName: "entry", 652 abilityName: "EntryAbility" 653}; 654let rule: appControl.DisposedRule = { 655 want: want, 656 componentType: appControl.ComponentType.UI_ABILITY, 657 disposedType: appControl.DisposedType.BLOCK_APPLICATION, 658 controlType: appControl.ControlType.ALLOWED_LIST, 659 elementList: [ 660 elementName 661 ], 662 priority: 100 663}; 664 665try { 666 appControl.setDisposedRule(appId, rule, 1); 667} catch (error) { 668 let message = (error as BusinessError).message; 669 console.error('setDisposedRule failed ' + message); 670} 671``` 672 673## appControl.setDisposedRules<sup>20+</sup> 674 675setDisposedRules(disposedRuleConfigurations: Array\<DisposedRuleConfiguration\>): void 676 677Sets disposed rules in batches for an application or an application clone. 678 679**System API**: This is a system API. 680 681**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 682 683**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 684 685**Parameters** 686 687| Name | Type | Mandatory| Description | 688| -------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 689| disposedRuleConfigurations | Array<[DisposedRuleConfiguration](#disposedruleconfiguration20)> | Yes | Configuration for the disposed rules in batches, including the appId of the target application, the index of the application clone, and the rules themselves. The maximum number of disposed rules in an array is 1000.<br>**NOTE**<br>1. If multiple **DisposedRuleConfiguration** entries in the array have the same appId and appIndex, the later entry will overwrite the earlier one.<br>2. If an application has already set disposed rules, re-setting the rules will replace the existing ones. Identical appId and appIndex values indicate the same application instance.| 690 691**Error codes** 692 693For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 694 695| ID| Error Message | 696| -------- | ------------------------------------------------------------ | 697| 201 | Permission denied. | 698| 202 | Permission denied. A non-system application is not allowed to call a system API. | 699| 801 | Capability not supported. | 700| 17700005 | The specified app ID is invalid. | 701| 17700061 | AppIndex is not in the valid range. | 702 703**Example** 704 705```ts 706import { BusinessError } from '@kit.BasicServicesKit'; 707import { appControl, Want, bundleManager } from '@kit.AbilityKit'; 708 709let want: Want = { 710 bundleName: 'com.example.myapplication', 711 moduleName: 'entry', 712 abilityName: 'EntryAbility' 713}; 714let elementName: bundleManager.ElementName = { 715 bundleName: 'com.example.myapplication', 716 moduleName: 'entry', 717 abilityName: 'EntryAbility' 718}; 719let rule: appControl.DisposedRule = { 720 want: want, 721 componentType: appControl.ComponentType.UI_ABILITY, 722 disposedType: appControl.DisposedType.BLOCK_APPLICATION, 723 controlType: appControl.ControlType.ALLOWED_LIST, 724 elementList: [ 725 elementName 726 ], 727 priority: 100 728}; 729 730let disposedRuleConfiguration: appControl.DisposedRuleConfiguration = { 731 appId: 'com.example.myapplication_BInGTMPMdc6v55s/UFIJHL5NLREXjOuxm/DsyMhlFmLAZC9/Gk+ruqS9OZr/dvFuaIaQQL1pKolvzK/zYNHvJ/I=', 732 appIndex: 0, 733 disposedRule: rule, 734}; 735 736let disposedRuleConfigurations: Array<appControl.DisposedRuleConfiguration> = []; 737disposedRuleConfigurations.push(disposedRuleConfiguration); 738@Entry 739@Component 740struct Index { 741 build() { 742 Row() { 743 Column() { 744 Button('setDisposedRules', { type: ButtonType.Normal }) 745 .onClick(() => { 746 try { 747 appControl.setDisposedRules(disposedRuleConfigurations); 748 console.info('setDisposedRules success'); 749 } catch (error) { 750 let err: BusinessError = error as BusinessError; 751 console.error(`setDisposedRules failed, errCode:${err.code}, message:${err.message}`); 752 } 753 }); 754 } 755 } 756 } 757} 758``` 759 760## appControl.setUninstallDisposedRule<sup>15+</sup> 761 762setUninstallDisposedRule(appIdentifier: string, rule: UninstallDisposedRule, appIndex:? number): void 763 764Sets an uninstallation disposed rule for an application or an application clone. 765 766**System API**: This is a system API. 767 768**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 769 770**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 771 772**Parameters** 773 774| Name | Type | Mandatory | Description | 775| ----------- | ------ | ---- | --------------------------------------- | 776| appIdentifier | string | Yes | appIdentifier of the target application.<br>If the application does not have an appIdentifier, use its appId instead. **appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 777| rule | [UninstallDisposedRule](#uninstalldisposedrule15) | Yes| Uninstallation disposed rule.| 778| appIndex | number | No | Index of the application clone. The default value is **0**.<br>The value **0** means to set the uninstallation disposed rule for the main application. A value greater than 0 means to set the uninstallation disposed rule for the application clone. | 779 780**Error codes** 781 782For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 783 784| ID| Error Message | 785| ------ | -------------------------------------- | 786| 201 | Permission denied. | 787| 202 | Permission denied. A non-system application is not allowed to call a system API. | 788| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 789| 801 | Capability not supported. | 790| 17700061 | AppIndex is not in the valid range. | 791| 17700074 | The specified appIdentifier is invalid. | 792| 17700075 | The specified bundleName of want is not the same with caller. | 793 794**Example** 795 796```ts 797import appControl from '@ohos.bundle.appControl'; 798import { BusinessError } from '@ohos.base'; 799import Want from '@ohos.app.ability.Want'; 800 801let appIdentifier = "com.example.myapplication_xxxxx"; 802let want: Want = { 803 bundleName: "com.example.myapplication", 804 moduleName: "entry", 805 abilityName: "EntryAbility" 806}; 807let rule: appControl.UninstallDisposedRule = { 808 want: want, 809 uninstallComponentType: appControl.UninstallComponentType.EXTENSION, 810 priority: 100 811}; 812 813try { 814 appControl.setUninstallDisposedRule(appIdentifier, rule, 1); 815} catch (error) { 816 let message = (error as BusinessError).message; 817 console.error('setUninstallDisposedRule failed ' + message); 818} 819``` 820 821## appControl.getUninstallDisposedRule<sup>15+</sup> 822 823getUninstallDisposedRule(appIdentifier: string, appIndex:? number): UninstallDisposedRule 824 825Obtains the uninstallation disposed rule of an application or an application clone. 826 827**System API**: This is a system API. 828 829**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS or ohos.permission.GET_DISPOSED_APP_STATUS 830 831**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 832 833**Parameters** 834 835| Name | Type | Mandatory | Description | 836| ----------- | ------ | ---- | --------------------------------------- | 837| appIdentifier | string | Yes | appIdentifier of the target application.<br>If the application does not have an appIdentifier, use its appId instead. **appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 838| appIndex | number | No | Index of the application clone. The default value is **0**.<br>The value **0** means to obtain the uninstallation disposed rule of the main application. A value greater than 0 means to obtain the uninstallation disposed rule of the application clone. | 839 840**Return value** 841 842| Type | Description | 843| ------------------------- | ------------------ | 844| [UninstallDisposedRule](#uninstalldisposedrule15) | Uninstallation disposed rule.| 845 846**Error codes** 847 848For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 849 850| ID| Error Message | 851| ------ | -------------------------------------- | 852| 201 | Permission denied. | 853| 202 | Permission denied. A non-system application is not allowed to call a system API. | 854| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 855| 801 | Capability not supported. | 856| 17700061 | AppIndex is not in the valid range. | 857| 17700074 | The specified appIdentifier is invalid. | 858 859**Example** 860 861```ts 862import appControl from '@ohos.bundle.appControl'; 863import { BusinessError } from '@ohos.base'; 864 865let appIdentifier = "com.example.myapplication_xxxxx"; 866 867try { 868 let data = appControl.getUninstallDisposedRule(appIdentifier, 1); 869 console.info('getUninstallDisposedRule successfully. Data: ' + JSON.stringify(data)); 870} catch (error) { 871 let message = (error as BusinessError).message; 872 console.error('getUninstallDisposedRule failed ' + message); 873} 874``` 875 876## appControl.deleteUninstallDisposedRule<sup>15+</sup> 877 878deleteUninstallDisposedRule(appIdentifier: string, appIndex:? number): void 879 880Deletes an uninstallation disposed rule for an application or an application clone. 881 882**System API**: This is a system API. 883 884**Required permissions**: ohos.permission.MANAGE_DISPOSED_APP_STATUS 885 886**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 887 888**Parameters** 889 890| Name | Type | Mandatory | Description | 891| ----------- | ------ | ---- | --------------------------------------- | 892| appIdentifier | string | Yes | appIdentifier of the target application.<br>If the application does not have an appIdentifier, use its appId instead. **appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain **appId**, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application). | 893| appIndex | number | No | Index of the application clone. The default value is **0**.<br>The value **0** means to delete the uninstallation disposed rule of the main application. A value greater than 0 means to delete the uninstallation disposed rule of the application clone. | 894 895**Error codes** 896 897For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 898 899| ID| Error Message | 900| ------ | -------------------------------------- | 901| 201 | Permission denied. | 902| 202 | Permission denied. A non-system application is not allowed to call a system API. | 903| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 904| 801 | Capability not supported. | 905| 17700061 | AppIndex is not in the valid range. | 906| 17700074 | The specified appIdentifier is invalid. | 907 908**Example** 909 910```ts 911import appControl from '@ohos.bundle.appControl'; 912import { BusinessError } from '@ohos.base'; 913 914let appIdentifier = "com.example.myapplication_xxxxx"; 915 916try { 917 appControl.deleteUninstallDisposedRule(appIdentifier, 1); 918} catch (error) { 919 let message = (error as BusinessError).message; 920 console.error('deleteUninstallDisposedRule failed ' + message); 921} 922``` 923 924## DisposedRule<sup>11+</sup> 925 926Defines a disposed rule. 927 928**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 929 930**System API**: This is a system API. 931 932| Name | Type | Read-Only| Optional| Description | 933| --------- | -------------- | ---- | ---- | --------------------------- | 934| want | [Want](js-apis-app-ability-want.md) | No | No | Page displayed when the application is disposed of.| 935| componentType | [ComponentType](#componenttype11) | No | No | Type of application component that functions as the displayed page.| 936| disposedType | [DisposedType](#disposedrule11) | No | No| Type of application disposal.| 937| controlType | [ControlType](#controltype11) | No | No| Control type of application disposal.| 938| elementList | Array\<[ElementName](js-apis-bundleManager-elementName.md)> | No | No| List of application components to be disposed of or exempted.| 939| priority | number | No | No| Priority of the disposed rule, which is used to sort the query results of the rule list. The value is an integer. A smaller value indicates a higher priority.| 940 941### ComponentType<sup>11+</sup> 942 943Enumerates the types of application components that function as the displayed page. 944 945**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 946 947**System API**: This is a system API. 948 949| Name | Value | Description | 950| ------- | ---- | -------------------- | 951| UI_ABILITY | 1 | UIAbility component.| 952| UI_EXTENSION | 2 | UIExtensionAbility component.| 953 954### DisposedType<sup>11+</sup> 955 956Enumerates the types of application disposals. 957 958**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 959 960**System API**: This is a system API. 961 962| Name | Value | Description | 963| ------- | ---- | -------------------- | 964| BLOCK_APPLICATION | 1 | All abilities of the application are blocked. That is, the entire application is blocked.| 965| BLOCK_ABILITY | 2 | A specific ability of the application is blocked.| 966| NON_BLOCK | 3 | The application is not blocked.| 967 968### ControlType<sup>11+</sup> 969 970Enumerates the control type of application disposal. 971 972**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 973 974**System API**: This is a system API. 975 976| Name | Value | Description | 977| ------- | ---- | -------------------- | 978| ALLOWED_LIST | 1 | A trustlist is used, which means that the application components in the list are allowed to run.| 979| DISALLOWED_LIST | 2 | A blocklist is used, which means that the application components in the list are forbidden to run.| 980 981## UninstallDisposedRule<sup>15+</sup> 982 983Describes an uninstallation disposed rule. 984 985**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 986 987 **System API**: This is a system API. 988 989| Name | Type | Read-Only| Optional| Description | 990| --------- | -------------- | ---- | ---- | --------------------------- | 991| want | [Want](js-apis-app-ability-want.md) | No | No | Page displayed when the application is disposed of.| 992| UninstallComponentType | [UninstallComponentType](#uninstallcomponenttype15) | No | No | Type of the ability to start during interception.| 993| priority | number | No| No| Priority of the disposed rule, which is used to sort the query results of the rule list. The value is an integer. A smaller value indicates a higher priority.| 994 995### UninstallComponentType<sup>15+</sup> 996 997Enumerates the types of abilities during uninstallation. 998 999**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 1000 1001 **System API**: This is a system API. 1002 1003| Name | Value | Description | 1004| ------- | ---- | -------------------- | 1005| EXTENSION | 1 | Extension ability.| 1006 1007## DisposedRuleConfiguration<sup>20+</sup> 1008 1009Describes the configurations for setting disposed rules in batches. 1010 1011**System capability**: SystemCapability.BundleManager.BundleFramework.AppControl 1012 1013 **System API**: This is a system API. 1014 1015| Name | Type | Read-Only| Optional| Description | 1016| ------------ | ------------------------------- | ---- | ---- | ------------------------------------------------------------ | 1017| appId | string | No | No | appId or appIdentifier of the target application. Identical appId and appIdentifier values indicate the same application instance. If a rule is set using appId, it overwrites the one set with appIdentifier, and the reverse is also true.<br>**NOTE**<br>**appId** is the unique identifier of an application and is determined by the bundle name and signature information of the application. For details about how to obtain appId, see [Obtaining appId of an Application](#obtaining-appid-and-appidentifier-of-an-application).<br>appIdentifier is the unique ID of the application. It is the [app ID](https://developer.huawei.com/consumer/en/doc/app/agc-help-createharmonyapp-0000001945392297), which is a random string, allocated by AppGallery Connect during the creation of the application. This ID does not change along the application lifecycle, including version updates, certificate changes, public and private key changes, and application transfers. For details about how to obtain appIdentifier, see [Obtaining appIdentifier of an application](#obtaining-appid-and-appidentifier-of-an-application).| 1018| appIndex | number | No | No | Index of the application clone. The default value is **0**.<br>The value **0** means to set the disposed rule for the main application. A value greater than 0 means to set the disposed rule for the application clone with the specified index.| 1019| disposedRule | [DisposedRule](#disposedrule11) | No | No | Disposal rule of the application, including the type of the ability to be started during disposal. | 1020