1# @ohos.abilityAccessCtrl (Application Access Control) (System API) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @xia-bubai--> 6<!--SE: @linshuqing; @hehehe-li--> 7<!--TSE: @leiyuqian--> 8 9The **abilityAccessCtrl** module provides APIs for application permission management, including authentication, authorization, and revocation. 10 11> **NOTE** 12> 13> - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.abilityAccessCtrl (Application Access Control)](js-apis-abilityAccessCtrl.md). 15 16## Modules to Import 17 18```ts 19import { abilityAccessCtrl } from '@kit.AbilityKit'; 20``` 21 22## AtManager 23 24Provides APIs for application access control. 25 26### grantUserGrantedPermission 27 28grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 29 30Grants a user_grant permission to an application. This API uses a promise to return the result. 31 32**System API**: This is a system API. 33 34**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications) 35 36**System capability**: SystemCapability.Security.AccessToken 37 38**Parameters** 39 40| Name | Type | Mandatory| Description | 41| --------- | ------------------- | ---- | ------------------------------------------------------------ | 42| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 43| permissionName | Permissions | Yes | Permission to grant. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 44| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **2**: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in **Settings**.<br>- **64**: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.| 45 46**Return value** 47 48| Type | Description | 49| :------------ | :---------------------------------- | 50| Promise<void> | Promise that returns no value.| 51 52**Error codes** 53 54For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 55 56| ID| Error Message| 57| -------- | -------- | 58| 201 | Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS". | 59| 202 | Not System App. Interface caller is not a system app. | 60| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 61| 12100001 | Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid. | 62| 12100002 | The specified tokenID does not exist. | 63| 12100003 | The specified permission does not exist or is not a user_grant permission. | 64| 12100006 | The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. | 65| 12100007 | The service is abnormal. | 66 67**Example** 68 69```ts 70import { abilityAccessCtrl } from '@kit.AbilityKit'; 71import { BusinessError } from '@kit.BasicServicesKit'; 72 73let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 74let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application. 75let permissionFlags: number = 1; 76atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 77 console.log('grantUserGrantedPermission success'); 78}).catch((err: BusinessError) => { 79 console.error(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 80}); 81``` 82 83### grantUserGrantedPermission 84 85grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 86 87Grants a user_grant permission to an application. This API uses an asynchronous callback to return the result. 88 89**System API**: This is a system API. 90 91**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications) 92 93**System capability**: SystemCapability.Security.AccessToken 94 95**Parameters** 96 97| Name | Type | Mandatory| Description | 98| --------- | ------------------- | ---- | ------------------------------------------------------------ | 99| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 100| permissionName | Permissions | Yes | Permission to grant. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 101| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **2**: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in **Settings**.<br>- **64**: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.| 102| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the permission is granted, **err** is **undefined**. Otherwise, **err** is an error object.| 103 104**Error codes** 105 106For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 107 108| ID| Error Message| 109| -------- | -------- | 110| 201 | Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS". | 111| 202 | Not System App. Interface caller is not a system app. | 112| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 113| 12100001 | Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid. | 114| 12100002 | The specified tokenID does not exist. | 115| 12100003 | The specified permission does not exist or is not a user_grant permission. | 116| 12100006 | The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. | 117| 12100007 | The service is abnormal. | 118 119**Example** 120 121```ts 122import { abilityAccessCtrl } from '@kit.AbilityKit'; 123import { BusinessError } from '@kit.BasicServicesKit'; 124 125let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 126let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application. 127let permissionFlags: number = 1; 128atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 129 if (err) { 130 console.error(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 131 } else { 132 console.log('grantUserGrantedPermission success'); 133 } 134}); 135``` 136 137### revokeUserGrantedPermission 138 139revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 140 141Revokes a user_grant permission from an application. This API uses a promise to return the result. 142 143**System API**: This is a system API. 144 145**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) 146 147**System capability**: SystemCapability.Security.AccessToken 148 149**Parameters** 150 151| Name | Type | Mandatory| Description | 152| --------- | ------------------- | ---- | ------------------------------------------------------------ | 153| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 154| permissionName | Permissions | Yes | Permission to revoke. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 155| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **2**: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in **Settings**.<br>- **64**: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.| 156 157**Return value** 158 159| Type | Description | 160| :------------ | :---------------------------------- | 161| Promise<void> | Promise that returns no value.| 162 163**Error codes** 164 165For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 166 167| ID| Error Message| 168| -------- | -------- | 169| 201 | Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS". | 170| 202 | Not System App. Interface caller is not a system app. | 171| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 172| 12100001 | Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid. | 173| 12100002 | The specified tokenID does not exist. | 174| 12100003 | The specified permission does not exist or is not a user_grant permission. | 175| 12100006 | The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. | 176| 12100007 | The service is abnormal. | 177 178**Example** 179 180```ts 181import { abilityAccessCtrl } from '@kit.AbilityKit'; 182import { BusinessError } from '@kit.BasicServicesKit'; 183 184let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 185let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application. 186let permissionFlags: number = 1; 187atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 188 console.log('revokeUserGrantedPermission success'); 189}).catch((err: BusinessError) => { 190 console.error(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 191}); 192``` 193 194### revokeUserGrantedPermission 195 196revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 197 198Revokes a user_grant permission from an application. This API uses an asynchronous callback to return the result. 199 200**System API**: This is a system API. 201 202**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) 203 204**System capability**: SystemCapability.Security.AccessToken 205 206**Parameters** 207 208| Name | Type | Mandatory| Description | 209| --------- | ------------------- | ---- | ------------------------------------------------------------ | 210| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 211| permissionName | Permissions | Yes | Permission to revoke. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 212| permissionFlags | number | Yes | Permission flag.<br>- **1**: A dialog box for user authorization will be displayed the next time if the user denies authorization for the permission.<br>- **2**: No dialog box will be displayed the next time if the user denies authorization for the permission. The permission must be granted by the user in **Settings**.<br>- **64**: The permission is given just once if the user allows the permission only this time. The authorization is canceled after the application is switched to the background or exits.| 213| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the permission is successfully revoked, **err** is **undefined**. Otherwise, **err** is an error object.| 214 215**Error codes** 216 217For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 218 219| ID| Error Message| 220| -------- | -------- | 221| 201 | Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS". | 222| 202 | Not System App. Interface caller is not a system app. | 223| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 224| 12100001 | Invalid parameter. The tokenID is 0, the permissionName exceeds 256 characters or is not declared in the module.json file, or the flags value is invalid. | 225| 12100002 | The specified tokenID does not exist. | 226| 12100003 | The specified permission does not exist or is not a user_grant permission. | 227| 12100006 | The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. | 228| 12100007 | The service is abnormal. | 229 230**Example** 231 232```ts 233import { abilityAccessCtrl } from '@kit.AbilityKit'; 234import { BusinessError } from '@kit.BasicServicesKit'; 235 236let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 237let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application. 238let permissionFlags: number = 1; 239atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 240 if (err) { 241 console.error(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 242 } else { 243 console.log('revokeUserGrantedPermission success'); 244 } 245}); 246``` 247 248### getPermissionFlags 249 250getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number> 251 252Obtains the flag of the specified permission of an application. This API uses a promise to return the result. 253 254**System API**: This is a system API. 255 256**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS, ohos.permission.GRANT_SENSITIVE_PERMISSIONS, or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) 257 258**System capability**: SystemCapability.Security.AccessToken 259 260**Parameters** 261 262| Name | Type | Mandatory| Description | 263| --------- | ------------------- | ---- | ------------------------------------------------------------ | 264| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 265| permissionName | Permissions | Yes | Target permission. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 266 267**Return value** 268 269| Type | Description | 270| :------------ | :---------------------------------- | 271| Promise<number> | Promise used to return the flag obtained.| 272 273**Error codes** 274 275For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 276 277| ID| Error Message| 278| -------- | -------- | 279| 201 | Permission denied. Interface caller does not have permission specified below. | 280| 202 | Not System App. Interface caller is not a system app. | 281| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 282| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 283| 12100002 | The specified tokenID does not exist. | 284| 12100003 | The specified permission does not exist or is not declared in the module.json file. | 285| 12100006 | The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. | 286| 12100007 | The service is abnormal. | 287 288**Example** 289 290```ts 291import { abilityAccessCtrl } from '@kit.AbilityKit'; 292import { BusinessError } from '@kit.BasicServicesKit'; 293 294let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 295let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application. 296atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => { 297 console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`); 298}).catch((err: BusinessError) => { 299 console.error(`getPermissionFlags fail, err->${JSON.stringify(err)}`); 300}); 301``` 302 303### setPermissionRequestToggleStatus<sup>12+</sup> 304 305setPermissionRequestToggleStatus(permissionName: Permissions, status: PermissionRequestToggleStatus): Promise<void> 306 307Sets the toggle state of a permission. This API uses a promise to return the result. 308 309**System API**: This is a system API. 310 311**Required permissions**: ohos.permission.DISABLE_PERMISSION_DIALOG 312 313**System capability**: SystemCapability.Security.AccessToken 314 315**Parameters** 316 317| Name | Type | Mandatory| Description | 318| --------- | ------------------- | ---- | ------------------------------------------------------------ | 319| permissionName | Permissions | Yes | Permission to be set with the toggle state. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 320| status | [PermissionRequestToggleStatus](#permissionrequesttogglestatus12) | Yes | Toggle state to set. | 321 322**Return value** 323 324| Type | Description | 325| :------------ | :---------------------------------- | 326| Promise<void> | Promise that returns no value.| 327 328**Error codes** 329 330For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 331 332| ID| Error Message| 333| -------- | -------- | 334| 201 | Permission denied. Interface caller does not have permission specified below. | 335| 202 | Not System App. Interface caller is not a system app. | 336| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 337| 12100001 | Invalid parameter. The permissionName exceeds 256 characters, the specified permission is not a user_grant permission, or the status value is invalid. | 338| 12100003 | The specified permission does not exist. | 339| 12100007 | The service is abnormal. | 340 341**Example** 342 343```ts 344import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 345import { BusinessError } from '@kit.BasicServicesKit'; 346 347let atManager = abilityAccessCtrl.createAtManager(); 348let permission: Permissions = 'ohos.permission.CAMERA'; 349 350atManager.setPermissionRequestToggleStatus(permission, abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED).then((err) => { 351 console.info('toggle_status: Set closed successful'); 352}).catch((err: BusinessError) => { 353 console.error(`toggle_status: Code is ${err.code}, message is ${err.message}`); 354}); 355``` 356 357### getPermissionRequestToggleStatus<sup>12+</sup> 358 359getPermissionRequestToggleStatus(permissionName: Permissions): Promise<PermissionRequestToggleStatus> 360 361Obtains the toggle state of a permission. This API uses a promise to return the result. 362 363**System API**: This is a system API. 364 365**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS 366 367**System capability**: SystemCapability.Security.AccessToken 368 369**Parameters** 370 371| Name | Type | Mandatory| Description | 372| --------- | ------------------- | ---- | ------------------------------------------------------------ | 373| permissionName | Permissions | Yes | Permission whose toggle state is to be obtained. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 374 375**Return value** 376 377| Type | Description | 378| :------------ | :---------------------------------- | 379| Promise<[PermissionRequestToggleStatus](#permissionrequesttogglestatus12)> | Promise used to return the toggle state obtained.| 380 381**Error codes** 382 383For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 384 385| ID| Error Message| 386| -------- | -------- | 387| 201 | Permission denied. Interface caller does not have permission specified below. | 388| 202 | Not System App. Interface caller is not a system app. | 389| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 390| 12100001 | Invalid parameter. The permissionName exceeds 256 characters, or the specified permission is not a user_grant permission. | 391| 12100003 | The specified permission does not exist. | 392| 12100007 | The service is abnormal. | 393 394**Example** 395 396```ts 397import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 398import { BusinessError } from '@kit.BasicServicesKit'; 399 400let atManager = abilityAccessCtrl.createAtManager(); 401let permission: Permissions = 'ohos.permission.CAMERA'; 402 403atManager.getPermissionRequestToggleStatus(permission).then((res) => { 404 if (res == abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED) { 405 console.info('toggle_status: The toggle status is close'); 406 } else { 407 console.info('toggle_status: The toggle status is open'); 408 } 409}).catch((err: BusinessError) => { 410console.error(`toggle_status: Code is ${err.code}, message is ${err.message}`); 411}); 412``` 413 414### getVersion<sup>9+</sup> 415 416getVersion(): Promise<number> 417 418Obtains the data version of the permission management. This API uses a promise to return the result. 419 420**System API**: This is a system API. 421 422**System capability**: SystemCapability.Security.AccessToken 423 424**Return value** 425 426| Type | Description | 427| :------------ | :---------------------------------- | 428| Promise<number> | Promise used to return the version number obtained.| 429 430| ID| Error Message| 431| -------- | -------- | 432| 202 | Not System App. Interface caller is not a system app. | 433 434**Example** 435 436```ts 437import { abilityAccessCtrl } from '@kit.AbilityKit'; 438 439let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 440let promise = atManager.getVersion(); 441promise.then((data: number) => { 442 console.log(`promise: data->${JSON.stringify(data)}`); 443}); 444``` 445 446### getPermissionsStatus<sup>12+</sup> 447 448getPermissionsStatus(tokenID: number, permissionList: Array<Permissions>): Promise<Array<PermissionStatus>> 449 450Obtains the status of the specified permissions. This API uses a promise to return the result. 451 452**System API**: This is a system API. 453 454**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) 455 456**System capability**: SystemCapability.Security.AccessToken 457 458**Parameters** 459 460| Name | Type | Mandatory| Description | 461| --------- | ------------------- | ---- | ------------------------------------------------------------ | 462| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 463| permissionList | Array<Permissions> | Yes | Permissions whose status is to be obtained. For details, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 464 465**Return value** 466 467| Type | Description | 468| :------------ | :---------------------------------- | 469| Promise<Array<[PermissionStatus](js-apis-abilityAccessCtrl.md#permissionstatus20)>> | Promise used to return the permission statuses obtained.| 470 471**Error codes** 472 473For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 474 475| ID| Error Message| 476| -------- | -------- | 477| 201 | Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". | 478| 202 | Not System App. Interface caller is not a system app. | 479| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 480| 12100001 | Invalid parameter. The tokenID is 0 or the permissionList is empty or exceeds the size limit. | 481| 12100002 | The specified tokenID does not exist. | 482| 12100007 | The service is abnormal. | 483 484**Example** 485 486```ts 487import { abilityAccessCtrl } from '@kit.AbilityKit'; 488import { BusinessError } from '@kit.BasicServicesKit'; 489 490let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 491let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application. 492atManager.getPermissionsStatus(tokenID, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.PermissionStatus>) => { 493 console.log(`getPermissionsStatus success, data->${JSON.stringify(data)}`); 494}).catch((err: BusinessError) => { 495 console.error(`getPermissionsStatus fail, err->${JSON.stringify(err)}`); 496}); 497``` 498 499### on<sup>9+</sup> 500 501on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void 502 503Subscribes to changes in the state of specified permissions for the given applications. 504 505Multiple callbacks can be registered for the specified **tokenIDList** and **permissionList**. 506 507If **tokenIDList** and **permissionList** have common values with the **tokenIDList** and **permissionList** of a callback registered, **callback** must be different. 508 509**System API**: This is a system API. 510 511**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) 512 513**System capability**: SystemCapability.Security.AccessToken 514 515**Parameters** 516 517| Name | Type | Mandatory| Description | 518| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 519| type | string | Yes | Event type. The value is **'permissionStateChange'**, which indicates the permission state changes. | 520| tokenIDList | Array<number> | Yes | List of application token IDs. If this parameter is not specified, this API will subscribe to the permission state changes of all applications.| 521| permissionList | Array<Permissions> | Yes | List of target permissions. If this parameter is not specified, this API will subscribe to state changes of all permissions. For details about the permissions, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 522| callback | Callback<[PermissionStateChangeInfo](js-apis-abilityAccessCtrl.md#permissionstatechangeinfo18)> | Yes| Callback invoked to return the permission state change.| 523 524**Error codes** 525 526For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 527 528| ID| Error Message| 529| -------- | -------- | 530| 201 | Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". | 531| 202 | Not System App. Interface caller is not a system app. | 532| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 533| 12100001 | Invalid parameter. Possible causes: 1. The tokenIDList or permissionList exceeds the size limit; 2. The tokenIDs or permissionNames in the list are all invalid. | 534| 12100004 | The API is used repeatedly with the same input. | 535| 12100005 | The registration time has exceeded the limit. | 536| 12100007 | The service is abnormal. | 537| 12100008 | Out of memory. | 538 539**Example** 540 541```ts 542import { abilityAccessCtrl, Permissions, bundleManager } from '@kit.AbilityKit'; 543 544let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 545let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 546let tokenIDList: Array<number> = [appInfo.accessTokenId]; 547let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 548try { 549 atManager.on('permissionStateChange', tokenIDList, permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => { 550 console.debug('receive permission state change, data:' + JSON.stringify(data)); 551 }); 552} catch(err) { 553 console.error(`catch err->${JSON.stringify(err)}`); 554} 555``` 556 557### off<sup>9+</sup> 558 559off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void 560 561Unsubscribes from changes in the state of specified permissions for the given applications. This API uses an asynchronous callback to return the result. 562 563During unsubscribing, if no callback is passed, all callbacks in **tokenIDList** and **permissionList** are deleted in batches. 564 565**System API**: This is a system API. 566 567**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) 568 569**System capability**: SystemCapability.Security.AccessToken 570 571**Parameters** 572 573| Name | Type | Mandatory| Description | 574| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 575| type | string | Yes | Event type. The value is **'permissionStateChange'**, which indicates the permission state changes. | 576| tokenIDList | Array<number> | Yes | List of application token IDs. The value must be the same as that in **on()**. If this parameter is not specified, this API will unsubscribe from the permission state changes of all applications.| 577| permissionList | Array<Permissions> | Yes | List of target permissions. The value must be the same as that in **on()**. If this parameter is not specified, this API will unsubscribe from state changes for all permissions. For details about the permissions, see [Application Permissions](../../security/AccessToken/app-permissions.md).| 578| callback | Callback<[PermissionStateChangeInfo](js-apis-abilityAccessCtrl.md#permissionstatechangeinfo18)> | No| Callback to unregister.| 579 580**Error codes** 581 582For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 583 584| ID| Error Message| 585| -------- | -------- | 586| 201 | Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". | 587| 202 | Not System App. Interface caller is not a system app. | 588| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 589| 12100001 | Invalid parameter. The tokenIDList or permissionList is not in the listening list. | 590| 12100004 | The API is not used in pair with 'on'. | 591| 12100007 | The service is abnormal. | 592| 12100008 | Out of memory. | 593 594**Example** 595 596```ts 597import { abilityAccessCtrl, Permissions, bundleManager } from '@kit.AbilityKit'; 598 599let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 600let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 601let tokenIDList: Array<number> = [appInfo.accessTokenId]; 602let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 603try { 604 atManager.off('permissionStateChange', tokenIDList, permissionList); 605} catch(err) { 606 console.error(`catch err->${JSON.stringify(err)}`); 607} 608``` 609 610### requestPermissionOnApplicationSetting<sup>18+</sup> 611 612requestPermissionOnApplicationSetting(tokenID: number): Promise<void> 613 614Starts the permission settings page for an application. This API uses a promise to return the result. 615 616**System API**: This is a system API. 617 618**Model restriction**: This API can be used only in the stage model. 619 620**System capability**: SystemCapability.Security.AccessToken 621 622**Parameters** 623 624| Name | Type | Mandatory| Description | 625| --------- | ------------------- | ---- | ------------------------------------------------------------ | 626| tokenID | number | Yes | Identifier of the target application, which is the value of **accessTokenId** contained in [ApplicationInfo](js-apis-bundleManager-applicationInfo.md).| 627 628**Return value** 629 630| Type | Description | 631| :------------ | :---------------------------------- | 632| Promise<void> | Promise that returns no value.| 633 634**Error codes** 635 636For details about the error codes, see [Access Control Error Codes](errorcode-access-token.md). 637 638| ID| Error Message| 639| -------- | -------- | 640| 202 | Not System App. Interface caller is not a system app. | 641| 12100002 | The specified tokenID does not exist. | 642| 12100007 | The service is abnormal. | 643 644**Example** 645 646```ts 647import { abilityAccessCtrl } from '@kit.AbilityKit'; 648import { BusinessError } from '@kit.BasicServicesKit'; 649 650let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 651let tokenID: number = 0; // System applications can obtain the token ID using bundleManager.getApplicationInfo. 652atManager.requestPermissionOnApplicationSetting(tokenID).then(() => { 653 console.log('requestPermissionOnApplicationSetting success'); 654}).catch((err: BusinessError) => { 655 console.error(`requestPermissionOnApplicationSetting fail, err->${JSON.stringify(err)}`); 656}); 657``` 658 659### PermissionRequestToggleStatus<sup>12+</sup> 660 661Enumerates the permission toggle states. 662 663**System capability**: SystemCapability.Security.AccessToken 664 665| Name | Value| Description | 666| ------------------ | ----- | ----------- | 667| CLOSED | 0 | The permission is toggled off.| 668| OPEN | 1 | The permission is toggled on.| 669