1# @ohos.abilityAccessCtrl (程序访问控制管理) 2 3程序访问控制提供程序的权限管理能力，包括鉴权、授权等。 4 5> **说明：** 6> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8## 导入模块 9 10```ts 11import { abilityAccessCtrl } from '@kit.AbilityKit' 12``` 13 14## abilityAccessCtrl.createAtManager 15 16createAtManager(): AtManager 17 18访问控制管理：获取访问控制模块对象。 19 20**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 21 22**系统能力：** SystemCapability.Security.AccessToken 23 24 25**返回值：** 26 27| 类型 | 说明 | 28| -------- | -------- | 29| [AtManager](#atmanager) | 获取访问控制模块的实例。 | 30 31**示例：** 32 33```ts 34let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 35``` 36 37## AtManager 38 39管理访问控制模块的实例。 40 41### checkAccessToken<sup>9+</sup> 42 43checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 44 45校验应用是否授予权限。使用Promise异步回调。 46 47**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.Security.AccessToken 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| -------- | ------------------- | ---- | ------------------------------------------ | 55| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 56| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 57 58**返回值：** 59 60| 类型 | 说明 | 61| :------------ | :---------------------------------- | 62| Promise<[GrantStatus](#grantstatus)> | Promise对象。返回授权状态结果。 | 63 64**错误码：** 65 66以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 67 68| 错误码ID | 错误信息 | 69| -------- | -------- | 70| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 71| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 72 73**示例：** 74 75```ts 76import { abilityAccessCtrl } from '@kit.AbilityKit'; 77import { BusinessError } from '@kit.BasicServicesKit'; 78 79let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 80let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 81atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 82 console.log(`checkAccessToken success, data->${JSON.stringify(data)}`); 83}).catch((err: BusinessError) => { 84 console.error(`checkAccessToken fail, err->${JSON.stringify(err)}`); 85}); 86``` 87 88### verifyAccessTokenSync<sup>9+</sup> 89 90verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 91 92校验应用是否被授予权限，同步返回结果。 93 94**系统能力：** SystemCapability.Security.AccessToken 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| -------- | ------------------- | ---- | ------------------------------------------ | 100| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 101| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 102 103**返回值：** 104 105| 类型 | 说明 | 106| :------------ | :---------------------------------- | 107| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 108 109**错误码：** 110 111以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 112 113| 错误码ID | 错误信息 | 114| -------- | -------- | 115| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 116| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 117 118**示例：** 119 120```ts 121import { abilityAccessCtrl } from '@kit.AbilityKit'; 122 123let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 124let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 125try { 126 let data: abilityAccessCtrl.GrantStatus = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'); 127 console.log(`data->${JSON.stringify(data)}`); 128} catch(err) { 129 console.error(`catch err->${JSON.stringify(err)}`); 130} 131``` 132 133### verifyAccessToken<sup>9+</sup> 134 135verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 136 137校验应用是否授予权限。使用Promise异步回调。 138 139> **说明：** 140> 141> 建议使用[checkAccessToken](#checkaccesstoken9)替代。 142 143**系统能力：** SystemCapability.Security.AccessToken 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| -------- | ------------------- | ---- | ------------------------------------------ | 149| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 150| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 151 152**返回值：** 153 154| 类型 | 说明 | 155| :------------ | :---------------------------------- | 156| Promise<[GrantStatus](#grantstatus)> | Promise对象。返回授权状态结果。 | 157 158**示例：** 159 160```ts 161import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 162import { BusinessError } from '@kit.BasicServicesKit'; 163 164let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 165let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 166let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 167atManager.verifyAccessToken(tokenID, permissionName).then((data: abilityAccessCtrl.GrantStatus) => { 168 console.log(`promise: data->${JSON.stringify(data)}`); 169}).catch((err: BusinessError) => { 170 console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 171}); 172``` 173 174### requestPermissionsFromUser<sup>9+</sup> 175 176requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>): void 177 178用于<!--RP1-->UIAbility<!--RP1End-->拉起弹框请求用户授权。使用callback异步回调。 179 180如果用户拒绝授权，将无法再次拉起弹框，需要用户在系统应用“设置”的界面中，手动授予权限。或是调用[requestPermissionOnSetting](#requestpermissiononsetting12)，拉起权限设置弹框，引导用户授权。 181 182> **说明：** 183> 184> 仅支持<!--RP1-->UIAbility<!--RP1End-->。 185 186**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 187 188**模型约束**：此接口仅可在Stage模型下使用。 189 190**系统能力**: SystemCapability.Security.AccessToken 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| -------- | -------- | -------- | -------- | 196| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的<!--RP1-->UIAbility<!--RP1End-->的Context。 | 197| permissionList | Array<Permissions> | 是 | 权限名列表，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 198| requestCallback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 是 | 回调函数，返回接口调用是否成功的结果。 | 199 200**错误码：** 201 202以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 203 204| 错误码ID | 错误信息 | 205| -------- | -------- | 206| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 207| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. | 208 209**示例：** 210示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 211 212```ts 213import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 214import { BusinessError } from '@kit.BasicServicesKit'; 215 216let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 217let context: Context = getContext(this) as common.UIAbilityContext; 218atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => { 219 if (err) { 220 console.error(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`); 221 } else { 222 console.info('data:' + JSON.stringify(data)); 223 console.info('data permissions:' + data.permissions); 224 console.info('data authResults:' + data.authResults); 225 console.info('data dialogShownResults:' + data.dialogShownResults); 226 } 227}); 228``` 229 230### requestPermissionsFromUser<sup>9+</sup> 231 232requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult> 233 234用于<!--RP1-->UIAbility<!--RP1End-->拉起弹框请求用户授权。使用promise异步回调。 235 236如果用户拒绝授权，将无法再次拉起弹框，需要用户在系统应用“设置”的界面中，手动授予权限。或是调用[requestPermissionOnSetting](#requestpermissiononsetting12)，拉起权限设置弹框，引导用户授权。 237 238> **说明：** 239> 240> 仅支持<!--RP1-->UIAbility<!--RP1End-->。 241 242**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 243 244**模型约束**：此接口仅可在Stage模型下使用。 245 246**系统能力**: SystemCapability.Security.AccessToken 247 248**参数：** 249 250| 参数名 | 类型 | 必填 | 说明 | 251| -------- | -------- | -------- | -------- | 252| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的<!--RP1-->UIAbility<!--RP1End-->的Context。 | 253| permissionList | Array<Permissions> | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 254 255**返回值：** 256 257| 类型 | 说明 | 258| -------- | -------- | 259| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 返回一个Promise，包含接口的结果。 | 260 261**错误码：** 262 263以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 264 265| 错误码ID | 错误信息 | 266| -------- | -------- | 267| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 268| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. | 269 270**示例：** 271示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 272 273```ts 274import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 275import { BusinessError } from '@kit.BasicServicesKit'; 276 277let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 278let context: Context = getContext(this) as common.UIAbilityContext; 279atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 280 console.info('data:' + JSON.stringify(data)); 281 console.info('data permissions:' + data.permissions); 282 console.info('data authResults:' + data.authResults); 283 console.info('data dialogShownResults:' + data.dialogShownResults); 284}).catch((err: BusinessError) => { 285 console.error('data:' + JSON.stringify(err)); 286}); 287``` 288 289### verifyAccessToken<sup>(deprecated)</sup> 290 291verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 292 293校验应用是否授予权限。使用Promise异步回调。 294 295> **说明：** 296> 297> 从API version 9开始不再维护，建议使用[checkAccessToken](#checkaccesstoken9)替代。 298 299**系统能力：** SystemCapability.Security.AccessToken 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| -------- | ------------------- | ---- | ------------------------------------------ | 305| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 306| permissionName | string | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 307 308**返回值：** 309 310| 类型 | 说明 | 311| :------------ | :---------------------------------- | 312| Promise<[GrantStatus](#grantstatus)> | Promise对象。返回授权状态结果。 | 313 314**示例：** 315 316```ts 317import { abilityAccessCtrl } from '@kit.AbilityKit'; 318import { BusinessError } from '@kit.BasicServicesKit'; 319 320let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 321let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 322atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 323 console.log(`promise: data->${JSON.stringify(data)}`); 324}).catch((err: BusinessError) => { 325 console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 326}); 327``` 328 329### checkAccessTokenSync<sup>10+</sup> 330 331checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 332 333校验应用是否被授予权限，同步返回结果。 334 335**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 336 337**系统能力：** SystemCapability.Security.AccessToken 338 339**参数：** 340 341| 参数名 | 类型 | 必填 | 说明 | 342| -------- | ------------------- | ---- | ------------------------------------------ | 343| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 344| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 345 346**返回值：** 347 348| 类型 | 说明 | 349| :------------ | :---------------------------------- | 350| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 351 352**错误码：** 353 354以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 355 356| 错误码ID | 错误信息 | 357| -------- | -------- | 358| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 359| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 360 361**示例：** 362 363```ts 364import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 365 366let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 367let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 368let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 369let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 370console.log(`data->${JSON.stringify(data)}`); 371``` 372 373### GrantStatus 374 375表示授权状态的枚举。 376 377**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 378 379**系统能力：** SystemCapability.Security.AccessToken 380 381| 名称 | 值 | 说明 | 382| ------------------ | ----- | ----------- | 383| PERMISSION_DENIED | -1 | 表示未授权。 | 384| PERMISSION_GRANTED | 0 | 表示已授权。 | 385 386### requestPermissionOnSetting<sup>12+</sup> 387 388requestPermissionOnSetting(context: Context, permissionList: Array<Permissions>): Promise<Array<GrantStatus>> 389 390用于UIAbility/UIExtensionAbility二次拉起权限设置弹框。 391 392在调用此接口前，应用需要先调用[requestPermissionsFromUser](#requestpermissionsfromuser9)，如果用户在首次弹窗授权时已授权，调用当前接口将无法拉起弹窗。 393 394> **说明：** 395> 396> 仅支持UIAbility/UIExtensionAbility。 397 398**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 399 400**模型约束**：此接口仅可在Stage模型下使用。 401 402**系统能力**: SystemCapability.Security.AccessToken 403 404**参数：** 405 406| 参数名 | 类型 | 必填 | 说明 | 407| -------- | -------- | -------- | -------- | 408| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的UIAbility/UIExtensionAbility的Context。 | 409| permissionList | Array<Permissions> | 是 | 权限名列表，合法的权限名取值可在[应用权限组列表](../../security/AccessToken/app-permission-group-list.md)中查询。 | 410 411**返回值：** 412 413| 类型 | 说明 | 414| :------------ | :---------------------------------- | 415| Promise<Array<[GrantStatus](#grantstatus)>> | Promise对象。返回授权状态结果。 | 416 417**错误码：** 418 419以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 420 421| 错误码ID | 错误信息 | 422| -------- | -------- | 423| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 424| 12100001 | Invalid parameter. Possible causes: 1. The context is invalid because it does not belong to the application itself; 2. The permission list contains the permission that is not declared in the module.json file; 3. The permission list is invalid because the permissions in it do not belong to the same permission group. | 425| 12100010 | The request already exists. | 426| 12100011 | All permissions in the permission list have been granted. | 427| 12100012 | The permission list contains the permission that has not been revoked by the user. | 428 429**示例：** 430示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 431 432```ts 433import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 434import { BusinessError } from '@kit.BasicServicesKit'; 435 436let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 437let context: Context = getContext(this) as common.UIAbilityContext; 438atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.GrantStatus>) => { 439 console.info('data:' + JSON.stringify(data)); 440}).catch((err: BusinessError) => { 441 console.error('data:' + JSON.stringify(err)); 442}); 443``` 444 445### requestGlobalSwitch<sup>12+</sup> 446 447requestGlobalSwitch(context: Context, type: SwitchType): Promise<boolean> 448 449用于UIAbility/UIExtensionAbility拉起全局开关设置弹框。 450 451部分情况下，录音、拍照等功能禁用，应用可拉起此弹框请求用户同意开启对应功能。如果当前全局开关的状态为开启，则不拉起弹框。 452 453> **说明：** 454> 455> 仅支持UIAbility/UIExtensionAbility。 456 457**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 458 459**模型约束**：此接口仅可在Stage模型下使用。 460 461**系统能力**: SystemCapability.Security.AccessToken 462 463**参数：** 464 465| 参数名 | 类型 | 必填 | 说明 | 466| -------- | -------- | -------- | -------- | 467| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的UIAbility/UIExtensionAbility>的Context。 | 468| type | [SwitchType](#switchtype12) | 是 | 全局开关类型。 | 469 470**返回值：** 471 472| 类型 | 说明 | 473| :------------ | :---------------------------------- | 474| Promise<boolean> | Promise对象。返回全局开关状态。 | 475 476**错误码：** 477 478以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 479 480| 错误码ID | 错误信息 | 481| -------- | -------- | 482| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 483| 12100001 | Invalid parameter. Possible causes: 1. The context is invalid because it does not belong to the application itself; 2. The type of global switch is not support. | 484| 12100010 | The request already exists. | 485| 12100013 | The specific global switch is already open. | 486 487**示例：** 488示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 489 490```ts 491import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 492import { BusinessError } from '@kit.BasicServicesKit'; 493 494let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 495let context: Context = getContext(this) as common.UIAbilityContext; 496atManager.requestGlobalSwitch(context, abilityAccessCtrl.SwitchType.CAMERA).then((data: Boolean) => { 497 console.info('data:' + JSON.stringify(data)); 498}).catch((err: BusinessError) => { 499 console.error('data:' + JSON.stringify(err)); 500}); 501``` 502 503### SwitchType<sup>12+</sup> 504 505表示全局开关类型。 506 507**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 508 509**系统能力：** SystemCapability.Security.AccessToken 510 511| 名称 | 值 | 说明 | 512| ------------------ | ----- | ----------- | 513| CAMERA | 0 | 表示相机全局开关。 | 514| MICROPHONE | 1 | 表示麦克风全局开关。 | 515| LOCATION | 2 | 表示位置全局开关。 |