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.GRANT_SENSITIVE_PERMISSIONS', 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.GRANT_SENSITIVE_PERMISSIONS', 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.GRANT_SENSITIVE_PERMISSIONS', 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.GRANT_SENSITIVE_PERMISSIONS', 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 620ArkTS语法不支持直接使用globalThis，需要通过一个单例的map来做中转。开发者需要： 621 622a. 在EntryAbility.ets中导入构建的单例对象GlobalThis。 623 ```ts 624 import { GlobalThis } from '../utils/globalThis'; // 需要根据globalThis.ets的路径自行适配 625 ``` 626b. 在onCreate中添加: 627 ```ts 628 GlobalThis.getInstance().setContext('context', this.context); 629 ``` 630 631 > **说明：** 632 > 633 > 由于在ts中引入ets文件会有告警提示，需要将EntryAbility.ts的文件后缀修改为EntryAbility.ets，并在module.json5中同步修改。 634 635**globalThis.ets示例代码如下：** 636```ts 637import { Context } from '@ohos.abilityAccessCtrl'; 638 639// 构造单例对象 640export class GlobalThis { 641 private constructor() {} 642 private static instance: GlobalThis; 643 private _uiContexts = new Map<string, Context>(); 644 645 public static getInstance(): GlobalThis { 646 if (!GlobalThis.instance) { 647 GlobalThis.instance = new GlobalThis(); 648 } 649 return GlobalThis.instance; 650 } 651 652 getContext(key: string): Context | undefined { 653 return this._uiContexts.get(key); 654 } 655 656 setContext(key: string, value: Context): void { 657 this._uiContexts.set(key, value); 658 } 659 660 // 其他需要传递的内容依此扩展 661} 662``` 663 664```ts 665import abilityAccessCtrl, { Context, PermissionRequestResult } from '@ohos.abilityAccessCtrl'; 666import { BusinessError } from '@ohos.base'; 667import common from '@ohos.app.ability.common'; 668import { GlobalThis } from '../utils/globalThis'; 669 670let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 671try { 672 let context: Context = GlobalThis.getInstance().getContext('context'); 673 atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult)=>{ 674 console.info('data:' + JSON.stringify(data)); 675 console.info('data permissions:' + data.permissions); 676 console.info('data authResults:' + data.authResults); 677 }); 678} catch(err) { 679 console.log(`catch err->${JSON.stringify(err)}`); 680} 681``` 682 683### requestPermissionsFromUser<sup>9+</sup> 684 685requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>) : Promise<PermissionRequestResult> 686 687用于UIAbility拉起弹框请求用户授权。使用promise异步回调。 688 689> **说明：** 690> 691> 非UIAbility不支持调用本函数。 692 693**模型约束**：此接口仅可在Stage模型下使用。 694 695**系统能力**: SystemCapability.Security.AccessToken 696 697**参数：** 698 699| 参数名 | 类型 | 必填 | 说明 | 700| -------- | -------- | -------- | -------- | 701| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 | 702| permissionList | Array<Permissions> | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 703 704**返回值：** 705 706| 类型 | 说明 | 707| -------- | -------- | 708| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 返回一个Promise，包含接口的结果。 | 709 710**错误码：** 711 712以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 713 714| 错误码ID | 错误信息 | 715| -------- | -------- | 716| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. | 717 718**示例：** 719 720修改EntryAbility.ets和导入GlobalThis等步骤同上，此处不再重复 721 722```ts 723import abilityAccessCtrl, { Context, PermissionRequestResult } from '@ohos.abilityAccessCtrl'; 724import { BusinessError } from '@ohos.base'; 725import { GlobalThis } from '../utils/globalThis'; 726 727let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 728try { 729 let context: Context = GlobalThis.getInstance().getContext('context'); 730 atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 731 console.info('data:' + JSON.stringify(data)); 732 console.info('data permissions:' + data.permissions); 733 console.info('data authResults:' + data.authResults); 734 }).catch((err: BusinessError) => { 735 console.info('data:' + JSON.stringify(err)); 736 }) 737} catch(err) { 738 console.log(`catch err->${JSON.stringify(err)}`); 739} 740``` 741 742### verifyAccessToken<sup>(deprecated)</sup> 743 744verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 745 746校验应用是否授予权限。使用Promise异步回调。 747 748> **说明：** 749> 750> 从API version 9开始不再维护，建议使用[checkAccessToken](#checkaccesstoken9)替代。 751 752**系统能力：** SystemCapability.Security.AccessToken 753 754**参数：** 755 756| 参数名 | 类型 | 必填 | 说明 | 757| -------- | ------------------- | ---- | ------------------------------------------ | 758| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 759| permissionName | string | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 760 761**返回值：** 762 763| 类型 | 说明 | 764| :------------ | :---------------------------------- | 765| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 766 767**示例：** 768 769```ts 770import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 771import { BusinessError } from '@ohos.base'; 772 773let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 774let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 775try { 776 atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 777 console.log(`promise: data->${JSON.stringify(data)}`); 778 }).catch((err: BusinessError) => { 779 console.log(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 780 }); 781}catch(err) { 782 console.log(`catch err->${JSON.stringify(err)}`); 783} 784``` 785 786### checkAccessTokenSync<sup>10+</sup> 787 788checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 789 790校验应用是否被授予权限，同步返回结果。 791 792**系统能力：** SystemCapability.Security.AccessToken 793 794**参数：** 795 796| 参数名 | 类型 | 必填 | 说明 | 797| -------- | ------------------- | ---- | ------------------------------------------ | 798| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 799| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 800 801**返回值：** 802 803| 类型 | 说明 | 804| :------------ | :---------------------------------- | 805| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 806 807**错误码：** 808 809以下错误码的详细介绍请参见[访问控制错误码](../errorcodes/errorcode-access-token.md)。 810 811| 错误码ID | 错误信息 | 812| -------- | -------- | 813| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 814 815**示例：** 816 817```ts 818import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 819 820let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 821let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 822let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 823let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 824console.log(`data->${JSON.stringify(data)}`); 825``` 826 827### GrantStatus 828 829表示授权状态的枚举。 830 831**系统能力：** SystemCapability.Security.AccessToken 832 833| 名称 | 值 | 说明 | 834| ------------------ | ----- | ----------- | 835| PERMISSION_DENIED | -1 | 表示未授权。 | 836| PERMISSION_GRANTED | 0 | 表示已授权。 | 837 838### PermissionStateChangeType<sup>9+</sup> 839 840表示权限授权状态变化操作类型的枚举。 841 842**系统接口：** 此接口为系统接口。 843 844**系统能力：** SystemCapability.Security.AccessToken 845 846| 名称 | 值 | 说明 | 847| ----------------------- | ------ | ----------------- | 848| PERMISSION_REVOKED_OPER | 0 | 表示权限取消操作。 | 849| PERMISSION_GRANTED_OPER | 1 | 表示权限授予操作。 | 850 851### PermissionStateChangeInfo<sup>9+</sup> 852 853表示某次权限授权状态变化的详情。 854 855**系统接口：** 此接口为系统接口。 856 857**系统能力：** SystemCapability.Security.AccessToken 858 859| 名称 | 类型 | 可读 | 可写 | 说明 | 860| -------------- | ------------------------- | ---- | ---- | ------------------ | 861| change | [PermissionStateChangeType](#permissionstatechangetype9) | 是 | 否 | 权限授权状态变化类型。 | 862| tokenID | number | 是 | 否 | 被订阅的应用身份标识。 | 863| permissionName | Permissions | 是 | 否 | 当前授权状态发生变化的权限名，合法的权限名取值可在[应用权限列表](../../security/permission-list.md)中查询。 | 864