1# @ohos.abilityAccessCtrl (程序访问控制管理) 2 3程序访问控制提供程序的权限管理能力，包括鉴权、授权和取消授权等。 4 5> **说明：** 6> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8## 导入模块 9 10```ts 11import abilityAccessCtrl from '@ohos.abilityAccessCtrl' 12``` 13 14## abilityAccessCtrl.createAtManager 15 16createAtManager(): AtManager 17 18访问控制管理：获取访问控制模块对象。 19 20**系统能力：** SystemCapability.Security.AccessToken 21 22 23**返回值：** 24 25| 类型 | 说明 | 26| -------- | -------- | 27| [AtManager](#atmanager) | 获取访问控制模块的实例。 | 28 29**示例：** 30 31```ts 32let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 33``` 34 35## AtManager 36 37管理访问控制模块的实例。 38 39### checkAccessToken<sup>9+</sup> 40 41checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 42 43校验应用是否授予权限。使用Promise异步回调。 44 45**系统能力：** SystemCapability.Security.AccessToken 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| -------- | ------------------- | ---- | ------------------------------------------ | 51| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 52| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 53 54**返回值：** 55 56| 类型 | 说明 | 57| :------------ | :---------------------------------- | 58| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 59 60**错误码：** 61 62以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 63 64| 错误码ID | 错误信息 | 65| -------- | -------- | 66| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 67 68**示例：** 69 70```ts 71import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 72import { BusinessError } from '@ohos.base'; 73 74let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 75let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 76try { 77 atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 78 console.log(`checkAccessToken success, data->${JSON.stringify(data)}`); 79 }).catch((err: BusinessError) => { 80 console.log(`checkAccessToken fail, err->${JSON.stringify(err)}`); 81 }); 82} catch(err) { 83 console.log(`catch err->${JSON.stringify(err)}`); 84} 85``` 86 87### verifyAccessTokenSync<sup>9+</sup> 88 89verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 90 91校验应用是否被授予权限，同步返回结果。 92 93**系统能力：** SystemCapability.Security.AccessToken 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| -------- | ------------------- | ---- | ------------------------------------------ | 99| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 100| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 101 102**返回值：** 103 104| 类型 | 说明 | 105| :------------ | :---------------------------------- | 106| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 107 108**错误码：** 109 110以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 111 112| 错误码ID | 错误信息 | 113| -------- | -------- | 114| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 115 116**示例：** 117 118```ts 119import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 120 121let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 122let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 123let data: abilityAccessCtrl.GrantStatus = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'); 124console.log(`data->${JSON.stringify(data)}`); 125``` 126 127### grantUserGrantedPermission 128 129grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 130 131授予应用user_grant权限。使用Promise异步回调。 132 133**系统接口：** 此接口为系统接口。 134 135**需要权限：** ohos.permission.GRANT_SENSITIVE_PERMISSIONS，仅系统应用可用。 136 137**系统能力：** SystemCapability.Security.AccessToken 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| --------- | ------------------- | ---- | ------------------------------------------------------------ | 143| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 144| permissionName | Permissions | 是 | 被授予的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 145| permissionFlags | number | 是 | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权，用户不可更改这个权限授权状态。 | 146 147**返回值：** 148 149| 类型 | 说明 | 150| :------------ | :---------------------------------- | 151| Promise<void> | Promise对象。无返回结果的Promise对象。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 156 157| 错误码ID | 错误信息 | 158| -------- | -------- | 159| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. | 160| 12100002 | The specified tokenID does not exist. | 161| 12100003 | The specified permission does not exist. | 162| 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. | 163| 12100007 | Service is abnormal. | 164 165**示例：** 166 167```ts 168import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 169import { BusinessError } from '@ohos.base'; 170 171let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 172let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 173let permissionFlags: number = 1; 174try { 175 atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 176 console.log('grantUserGrantedPermission success'); 177 }).catch((err: BusinessError) => { 178 console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 179 }); 180} catch(err) { 181 console.log(`catch err->${JSON.stringify(err)}`); 182} 183``` 184 185### grantUserGrantedPermission 186 187grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 188 189授予应用user_grant权限。使用callback异步回调。 190 191**系统接口：** 此接口为系统接口。 192 193**需要权限：** ohos.permission.GRANT_SENSITIVE_PERMISSIONS，仅系统应用可用。 194 195**系统能力：** SystemCapability.Security.AccessToken 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| --------- | ------------------- | ---- | ------------------------------------------------------------ | 201| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。| 202| permissionName | Permissions | 是 | 被授予的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 203| permissionFlags | number | 是 | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权，用户不可更改这个权限授权状态。 | 204| callback | AsyncCallback<void> | 是 | 授予应用user_grant权限。当授予权限成功时，err为undefined；否则为错误对象。 | 205 206**错误码：** 207 208以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 209 210| 错误码ID | 错误信息 | 211| -------- | -------- | 212| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. | 213| 12100002 | The specified tokenID does not exist. | 214| 12100003 | The specified permission does not exist. | 215| 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. | 216| 12100007 | Service is abnormal. | 217 218**示例：** 219 220```ts 221import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 222import { BusinessError } from '@ohos.base'; 223 224let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 225let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 226let permissionFlags: number = 1; 227try { 228 atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 229 if (err) { 230 console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 231 } else { 232 console.log('grantUserGrantedPermission success'); 233 } 234 }); 235} catch(err) { 236 console.log(`catch err->${JSON.stringify(err)}`); 237} 238``` 239 240### revokeUserGrantedPermission 241 242revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 243 244撤销应用user_grant权限。使用Promise异步回调。 245 246**系统接口：** 此接口为系统接口。 247 248**需要权限：** ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。 249 250**系统能力：** SystemCapability.Security.AccessToken 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| --------- | ------------------- | ---- | ------------------------------------------------------------ | 256| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 257| permissionName | Permissions | 是 | 被撤销的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 258| permissionFlags | number | 是 | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权，用户不可更改这个权限授权状态。 | 259 260**返回值：** 261 262| 类型 | 说明 | 263| :------------ | :---------------------------------- | 264| Promise<void> | Promise对象。无返回结果的Promise对象。 | 265 266**错误码：** 267 268以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 269 270| 错误码ID | 错误信息 | 271| -------- | -------- | 272| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. | 273| 12100002 | The specified tokenID does not exist. | 274| 12100003 | The specified permission does not exist. | 275| 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. | 276| 12100007 | Service is abnormal. | 277 278**示例：** 279 280```ts 281import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 282import { BusinessError } from '@ohos.base'; 283 284let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 285let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 286let permissionFlags: number = 1; 287try { 288 atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 289 console.log('revokeUserGrantedPermission success'); 290 }).catch((err: BusinessError) => { 291 console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 292 }); 293} catch(err) { 294 console.log(`catch err->${JSON.stringify(err)}`); 295} 296``` 297 298### revokeUserGrantedPermission 299 300revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 301 302撤销应用user_grant权限。使用callback异步回调。 303 304**系统接口：** 此接口为系统接口。 305 306**需要权限：** ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。 307 308**系统能力：** SystemCapability.Security.AccessToken 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| --------- | ------------------- | ---- | ------------------------------------------------------------ | 314| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 315| permissionName | Permissions | 是 | 被撤销的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 316| permissionFlags | number | 是 | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权，用户不可更改这个权限授权状态。 | 317| callback | AsyncCallback<void> | 是 | 撤销应用user_grant权限。当撤销权限成功时，err为undefined；否则为错误对象。 | 318 319**错误码：** 320 321以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 322 323| 错误码ID | 错误信息 | 324| -------- | -------- | 325| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. | 326| 12100002 | The specified tokenID does not exist. | 327| 12100003 | The specified permission does not exist. | 328| 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. | 329| 12100007 | Service is abnormal. | 330 331**示例：** 332 333```ts 334import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 335import { BusinessError } from '@ohos.base'; 336 337let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 338let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 339let permissionFlags: number = 1; 340try { 341 atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 342 if (err) { 343 console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 344 } else { 345 console.log('revokeUserGrantedPermission success'); 346 } 347 }); 348} catch(err) { 349 console.log(`catch err->${JSON.stringify(err)}`); 350} 351``` 352 353### getPermissionFlags 354 355getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number> 356 357获取指定应用的指定权限的flag。使用Promise异步回调。 358 359**系统接口：** 此接口为系统接口。 360 361**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。 362 363**系统能力：** SystemCapability.Security.AccessToken 364 365**参数：** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| --------- | ------------------- | ---- | ------------------------------------------------------------ | 369| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 370| permissionName | Permissions | 是 | 查询的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 371 372**返回值：** 373 374| 类型 | 说明 | 375| :------------ | :---------------------------------- | 376| Promise<number> | Promise对象。返回查询结果。 | 377 378**错误码：** 379 380以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 381 382| 错误码ID | 错误信息 | 383| -------- | -------- | 384| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 385| 12100002 | The specified tokenID does not exist. | 386| 12100003 | The specified permission does not exist. | 387| 12100006 | The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. | 388| 12100007 | Service is abnormal. | 389 390**示例：** 391 392```ts 393import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 394import { BusinessError } from '@ohos.base'; 395 396let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 397let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 398try { 399 atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => { 400 console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`); 401 }).catch((err: BusinessError) => { 402 console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`); 403 }); 404} catch(err) { 405 console.log(`catch err->${JSON.stringify(err)}`); 406} 407``` 408 409### getVersion<sup>9+</sup> 410 411getVersion(): Promise<number> 412 413获取当前权限管理的数据版本。使用Promise异步回调。 414 415**系统接口：** 此接口为系统接口。 416 417**系统能力：** SystemCapability.Security.AccessToken 418 419**返回值：** 420 421| 类型 | 说明 | 422| :------------ | :---------------------------------- | 423| Promise<number> | Promise对象。返回查询到的版本号。 | 424 425**示例：** 426 427```ts 428import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 429 430let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 431let promise = atManager.getVersion(); 432promise.then((data: number) => { 433 console.log(`promise: data->${JSON.stringify(data)}`); 434}); 435``` 436 437### on<sup>9+</sup> 438 439on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void 440 441订阅指定tokenId列表与权限列表的权限状态变更事件。 442 443允许指定tokenId列表与权限列表订阅多个callback。 444 445不允许存在交集的tokenId列表与权限列表订阅相同callback。 446 447**系统接口：** 此接口为系统接口。 448 449**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS，仅系统应用可用。 450 451**系统能力：** SystemCapability.Security.AccessToken 452 453**参数：** 454 455| 参数名 | 类型 | 必填 | 说明 | 456| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 457| type | string | 是 | 订阅事件类型，固定为'permissionStateChange'，权限状态变更事件。 | 458| tokenIDList | Array<number> | 是 | 订阅的tokenId列表，为空时表示订阅所有的应用的权限状态变化。 | 459| permissionList | Array<Permissions> | 是 | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。| 460| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | 是 | 订阅指定tokenId与指定权限名状态变更事件的回调。| 461 462**错误码：** 463 464以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 465 466| 错误码ID | 错误信息 | 467| -------- | -------- | 468| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 469| 12100004 | The interface is called repeatedly with the same input. | 470| 12100005 | The registration time has exceeded the limitation. | 471| 12100007 | Service is abnormal. | 472| 12100008 | Out of memory. | 473 474**示例：** 475 476```ts 477import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 478import bundleManager from '@ohos.bundle.bundleManager'; 479 480let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 481let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 482let tokenIDList: Array<number> = [appInfo.accessTokenId]; 483let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 484try { 485 atManager.on('permissionStateChange', tokenIDList, permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => { 486 console.debug('receive permission state change, data:' + JSON.stringify(data)); 487 }); 488} catch(err) { 489 console.log(`catch err->${JSON.stringify(err)}`); 490} 491``` 492 493### off<sup>9+</sup> 494 495off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void 496 497取消订阅指定tokenId列表与权限列表的权限状态变更事件，使用callback回调异步返回结果。 498 499取消订阅不传callback时，批量删除tokenIDList和permissionList下面的所有callback。 500 501**系统接口：** 此接口为系统接口。 502 503**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS，仅系统应用可用。 504 505**系统能力：** SystemCapability.Security.AccessToken 506 507**参数：** 508 509| 参数名 | 类型 | 必填 | 说明 | 510| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 511| type | string | 是 | 订阅事件类型，固定为'permissionStateChange'，权限状态变更事件。 | 512| tokenIDList | Array<number> | 是 | 订阅的tokenId列表，为空时表示订阅所有的应用的权限状态变化，必须与on的输入一致。 | 513| permissionList | Array<Permissions> | 是 | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，必须与on的输入一致，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 514| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | 否 | 取消订阅指定tokenId与指定权限名状态变更事件的回调。| 515 516**错误码：** 517 518以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 519 520| 错误码ID | 错误信息 | 521| -------- | -------- | 522| 12100001 | The parameter is invalid. The tokenIDs or permissionNames in the list are all invalid. | 523| 12100004 | The interface is not used together with 'on'. | 524| 12100007 | Service is abnormal. | 525| 12100008 | Out of memory. | 526 527**示例：** 528 529```ts 530import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 531import bundleManager from '@ohos.bundle.bundleManager'; 532 533let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 534let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 535let tokenIDList: Array<number> = [appInfo.accessTokenId]; 536let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 537try { 538 atManager.off('permissionStateChange', tokenIDList, permissionList); 539} catch(err) { 540 console.log(`catch err->${JSON.stringify(err)}`); 541} 542``` 543 544### verifyAccessToken<sup>9+</sup> 545 546verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 547 548校验应用是否授予权限。使用Promise异步回调。 549 550> **说明：** 551> 552> 建议使用[checkAccessToken](#checkaccesstoken9)替代。 553 554**系统能力：** SystemCapability.Security.AccessToken 555 556**参数：** 557 558| 参数名 | 类型 | 必填 | 说明 | 559| -------- | ------------------- | ---- | ------------------------------------------ | 560| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 561| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 562 563**返回值：** 564 565| 类型 | 说明 | 566| :------------ | :---------------------------------- | 567| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 568 569**示例：** 570 571```ts 572import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 573import { BusinessError } from '@ohos.base'; 574 575let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 576let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 577let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 578try { 579 atManager.verifyAccessToken(tokenID, permissionName).then((data: abilityAccessCtrl.GrantStatus) => { 580 console.log(`promise: data->${JSON.stringify(data)}`); 581 }).catch((err: BusinessError) => { 582 console.log(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 583 }); 584}catch(err) { 585 console.log(`catch err->${JSON.stringify(err)}`); 586} 587``` 588 589### requestPermissionsFromUser<sup>9+</sup> 590 591requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>) : void 592 593用于UIAbility拉起弹框请求用户授权。使用callback异步回调。 594> **说明：** 595> 596> 非UIAbility不支持调用本函数。 597 598**模型约束**：此接口仅可在Stage模型下使用。 599 600**系统能力**: SystemCapability.Security.AccessToken 601 602**参数：** 603 604| 参数名 | 类型 | 必填 | 说明 | 605| -------- | -------- | -------- | -------- | 606| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 | 607| permissionList | Array<Permissions> | 是 | 权限名列表，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 608| requestCallback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 是 | 回调函数，返回接口调用是否成功的结果。 | 609 610**错误码：** 611 612以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 613 614| 错误码ID | 错误信息 | 615| -------- | -------- | 616| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. | 617 618**示例：** 619 620```ts 621import abilityAccessCtrl, { Context, PermissionRequestResult } from '@ohos.abilityAccessCtrl'; 622import { BusinessError } from '@ohos.base'; 623import common from '@ohos.app.ability.common'; 624 625let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 626try { 627 let context = getContext(this); 628 atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult)=>{ 629 console.info('data:' + JSON.stringify(data)); 630 console.info('data permissions:' + data.permissions); 631 console.info('data authResults:' + data.authResults); 632 }); 633} catch(err) { 634 console.log(`catch err->${JSON.stringify(err)}`); 635} 636``` 637 638### requestPermissionsFromUser<sup>9+</sup> 639 640requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>) : Promise<PermissionRequestResult> 641 642用于UIAbility拉起弹框请求用户授权。使用promise异步回调。 643 644> **说明：** 645> 646> 非UIAbility不支持调用本函数。 647 648**模型约束**：此接口仅可在Stage模型下使用。 649 650**系统能力**: SystemCapability.Security.AccessToken 651 652**参数：** 653 654| 参数名 | 类型 | 必填 | 说明 | 655| -------- | -------- | -------- | -------- | 656| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 | 657| permissionList | Array<Permissions> | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 658 659**返回值：** 660 661| 类型 | 说明 | 662| -------- | -------- | 663| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 返回一个Promise，包含接口的结果。 | 664 665**错误码：** 666 667以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 668 669| 错误码ID | 错误信息 | 670| -------- | -------- | 671| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. | 672 673**示例：** 674 675```ts 676import abilityAccessCtrl, { Context, PermissionRequestResult } from '@ohos.abilityAccessCtrl'; 677import { BusinessError } from '@ohos.base'; 678 679let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 680try { 681 let context = getContext(this); 682 atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 683 console.info('data:' + JSON.stringify(data)); 684 console.info('data permissions:' + data.permissions); 685 console.info('data authResults:' + data.authResults); 686 }).catch((err: BusinessError) => { 687 console.info('data:' + JSON.stringify(err)); 688 }) 689} catch(err) { 690 console.log(`catch err->${JSON.stringify(err)}`); 691} 692``` 693 694### verifyAccessToken<sup>(deprecated)</sup> 695 696verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 697 698校验应用是否授予权限。使用Promise异步回调。 699 700> **说明：** 701> 702> 从API version 9开始不再维护，建议使用[checkAccessToken](#checkaccesstoken9)替代。 703 704**系统能力：** SystemCapability.Security.AccessToken 705 706**参数：** 707 708| 参数名 | 类型 | 必填 | 说明 | 709| -------- | ------------------- | ---- | ------------------------------------------ | 710| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 711| permissionName | string | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 712 713**返回值：** 714 715| 类型 | 说明 | 716| :------------ | :---------------------------------- | 717| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 718 719**示例：** 720 721```ts 722import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 723import { BusinessError } from '@ohos.base'; 724 725let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 726let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 727try { 728 atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 729 console.log(`promise: data->${JSON.stringify(data)}`); 730 }).catch((err: BusinessError) => { 731 console.log(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 732 }); 733}catch(err) { 734 console.log(`catch err->${JSON.stringify(err)}`); 735} 736``` 737 738### checkAccessTokenSync<sup>10+</sup> 739 740checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 741 742校验应用是否被授予权限，同步返回结果。 743 744**系统能力：** SystemCapability.Security.AccessToken 745 746**参数：** 747 748| 参数名 | 类型 | 必填 | 说明 | 749| -------- | ------------------- | ---- | ------------------------------------------ | 750| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 751| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 752 753**返回值：** 754 755| 类型 | 说明 | 756| :------------ | :---------------------------------- | 757| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 758 759**错误码：** 760 761以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 762 763| 错误码ID | 错误信息 | 764| -------- | -------- | 765| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 766 767**示例：** 768 769```ts 770import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 771 772let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 773let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 774let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 775let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 776console.log(`data->${JSON.stringify(data)}`); 777``` 778 779### GrantStatus 780 781表示授权状态的枚举。 782 783**系统能力：** SystemCapability.Security.AccessToken 784 785| 名称 | 值 | 说明 | 786| ------------------ | ----- | ----------- | 787| PERMISSION_DENIED | -1 | 表示未授权。 | 788| PERMISSION_GRANTED | 0 | 表示已授权。 | 789 790### PermissionStateChangeType<sup>9+</sup> 791 792表示权限授权状态变化操作类型的枚举。 793 794**系统接口：** 此接口为系统接口。 795 796**系统能力：** SystemCapability.Security.AccessToken 797 798| 名称 | 值 | 说明 | 799| ----------------------- | ------ | ----------------- | 800| PERMISSION_REVOKED_OPER | 0 | 表示权限取消操作。 | 801| PERMISSION_GRANTED_OPER | 1 | 表示权限授予操作。 | 802 803### PermissionStateChangeInfo<sup>9+</sup> 804 805表示某次权限授权状态变化的详情。 806 807**系统接口：** 此接口为系统接口。 808 809**系统能力：** SystemCapability.Security.AccessToken 810 811| 名称 | 类型 | 可读 | 可写 | 说明 | 812| -------------- | ------------------------- | ---- | ---- | ------------------ | 813| change | [PermissionStateChangeType](#permissionstatechangetype9) | 是 | 否 | 权限授权状态变化类型。 | 814| tokenID | number | 是 | 否 | 被订阅的应用身份标识。 | 815| permissionName | Permissions | 是 | 否 | 当前授权状态发生变化的权限名，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 816