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 211完整示例： 212 213[向用户申请授权](../../security/AccessToken/request-user-authorization.md) 214 215示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 216 217```ts 218import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 219import { BusinessError } from '@kit.BasicServicesKit'; 220 221let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 222let context: Context = getContext(this) as common.UIAbilityContext; 223atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => { 224 if (err) { 225 console.error(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`); 226 } else { 227 console.info('data:' + JSON.stringify(data)); 228 console.info('data permissions:' + data.permissions); 229 console.info('data authResults:' + data.authResults); 230 console.info('data dialogShownResults:' + data.dialogShownResults); 231 } 232}); 233``` 234 235### requestPermissionsFromUser<sup>9+</sup> 236 237requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult> 238 239用于<!--RP1-->UIAbility<!--RP1End-->拉起弹框请求用户授权。使用promise异步回调。 240 241如果用户拒绝授权，将无法再次拉起弹框，需要用户在系统应用“设置”的界面中，手动授予权限。或是调用[requestPermissionOnSetting](#requestpermissiononsetting12)，拉起权限设置弹框，引导用户授权。 242 243> **说明：** 244> 245> 仅支持<!--RP1-->UIAbility<!--RP1End-->。 246 247**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 248 249**模型约束**：此接口仅可在Stage模型下使用。 250 251**系统能力**: SystemCapability.Security.AccessToken 252 253**参数：** 254 255| 参数名 | 类型 | 必填 | 说明 | 256| -------- | -------- | -------- | -------- | 257| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的<!--RP1-->UIAbility<!--RP1End-->的Context。 | 258| permissionList | Array<Permissions> | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 259 260**返回值：** 261 262| 类型 | 说明 | 263| -------- | -------- | 264| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 返回一个Promise，包含接口的结果。 | 265 266**错误码：** 267 268以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 269 270| 错误码ID | 错误信息 | 271| -------- | -------- | 272| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 273| 12100001 | Invalid parameter. The context is invalid when it does not belong to the application itself. | 274 275**示例：** 276 277完整示例： 278 279[向用户申请授权](../../security/AccessToken/request-user-authorization.md) 280 281示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 282 283```ts 284import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit'; 285import { BusinessError } from '@kit.BasicServicesKit'; 286 287let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 288let context: Context = getContext(this) as common.UIAbilityContext; 289atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 290 console.info('data:' + JSON.stringify(data)); 291 console.info('data permissions:' + data.permissions); 292 console.info('data authResults:' + data.authResults); 293 console.info('data dialogShownResults:' + data.dialogShownResults); 294}).catch((err: BusinessError) => { 295 console.error('data:' + JSON.stringify(err)); 296}); 297``` 298 299### verifyAccessToken<sup>(deprecated)</sup> 300 301verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 302 303校验应用是否授予权限。使用Promise异步回调。 304 305> **说明：** 306> 307> 从API version 9开始不再维护，建议使用[checkAccessToken](#checkaccesstoken9)替代。 308 309**系统能力：** SystemCapability.Security.AccessToken 310 311**参数：** 312 313| 参数名 | 类型 | 必填 | 说明 | 314| -------- | ------------------- | ---- | ------------------------------------------ | 315| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 316| permissionName | string | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 317 318**返回值：** 319 320| 类型 | 说明 | 321| :------------ | :---------------------------------- | 322| Promise<[GrantStatus](#grantstatus)> | Promise对象。返回授权状态结果。 | 323 324**示例：** 325 326```ts 327import { abilityAccessCtrl } from '@kit.AbilityKit'; 328import { BusinessError } from '@kit.BasicServicesKit'; 329 330let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 331let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取，三方应用可以通过bundleManager.getBundleInfoForSelf获取 332atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 333 console.log(`promise: data->${JSON.stringify(data)}`); 334}).catch((err: BusinessError) => { 335 console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 336}); 337``` 338 339### checkAccessTokenSync<sup>10+</sup> 340 341checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 342 343校验应用是否被授予权限，同步返回结果。 344 345**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 346 347**系统能力：** SystemCapability.Security.AccessToken 348 349**参数：** 350 351| 参数名 | 类型 | 必填 | 说明 | 352| -------- | ------------------- | ---- | ------------------------------------------ | 353| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 354| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 355 356**返回值：** 357 358| 类型 | 说明 | 359| :------------ | :---------------------------------- | 360| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 361 362**错误码：** 363 364以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 365 366| 错误码ID | 错误信息 | 367| -------- | -------- | 368| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 369| 12100001 | Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters. | 370 371**示例：** 372 373```ts 374import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'; 375 376let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 377let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取，三方应用可以通过bundleManager.getBundleInfoForSelf获取 378let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 379let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 380console.log(`data->${JSON.stringify(data)}`); 381``` 382 383### GrantStatus 384 385表示授权状态的枚举。 386 387**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 388 389**系统能力：** SystemCapability.Security.AccessToken 390 391| 名称 | 值 | 说明 | 392| ------------------ | ----- | ----------- | 393| PERMISSION_DENIED | -1 | 表示未授权。 | 394| PERMISSION_GRANTED | 0 | 表示已授权。 | 395 396### requestPermissionOnSetting<sup>12+</sup> 397 398requestPermissionOnSetting(context: Context, permissionList: Array<Permissions>): Promise<Array<GrantStatus>> 399 400用于UIAbility/UIExtensionAbility二次拉起权限设置弹框。 401 402在调用此接口前，应用需要先调用[requestPermissionsFromUser](#requestpermissionsfromuser9)，如果用户在首次弹窗授权时已授权，调用当前接口将无法拉起弹窗。 403 404> **说明：** 405> 406> 仅支持UIAbility/UIExtensionAbility。 407 408**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 409 410**模型约束**：此接口仅可在Stage模型下使用。 411 412**系统能力**: SystemCapability.Security.AccessToken 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417| -------- | -------- | -------- | -------- | 418| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的UIAbility/UIExtensionAbility的Context。 | 419| permissionList | Array<Permissions> | 是 | 权限名列表，合法的权限名取值可在[应用权限组列表](../../security/AccessToken/app-permission-group-list.md)中查询。 | 420 421**返回值：** 422 423| 类型 | 说明 | 424| :------------ | :---------------------------------- | 425| Promise<Array<[GrantStatus](#grantstatus)>> | Promise对象。返回授权状态结果。 | 426 427**错误码：** 428 429以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 430 431| 错误码ID | 错误信息 | 432| -------- | -------- | 433| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 434| 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. | 435| 12100010 | The request already exists. | 436| 12100011 | All permissions in the permission list have been granted. | 437| 12100012 | The permission list contains the permission that has not been revoked by the user. | 438 439**示例：** 440示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 441 442```ts 443import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 444import { BusinessError } from '@kit.BasicServicesKit'; 445 446let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 447let context: Context = getContext(this) as common.UIAbilityContext; 448atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.GrantStatus>) => { 449 console.info('data:' + JSON.stringify(data)); 450}).catch((err: BusinessError) => { 451 console.error('data:' + JSON.stringify(err)); 452}); 453``` 454 455### requestGlobalSwitch<sup>12+</sup> 456 457requestGlobalSwitch(context: Context, type: SwitchType): Promise<boolean> 458 459用于UIAbility/UIExtensionAbility拉起全局开关设置弹框。 460 461部分情况下，录音、拍照等功能禁用，应用可拉起此弹框请求用户同意开启对应功能。如果当前全局开关的状态为开启，则不拉起弹框。 462 463> **说明：** 464> 465> 仅支持UIAbility/UIExtensionAbility。 466 467**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 468 469**模型约束**：此接口仅可在Stage模型下使用。 470 471**系统能力**: SystemCapability.Security.AccessToken 472 473**参数：** 474 475| 参数名 | 类型 | 必填 | 说明 | 476| -------- | -------- | -------- | -------- | 477| context | [Context](js-apis-inner-application-context.md) | 是 | 请求权限的UIAbility/UIExtensionAbility>的Context。 | 478| type | [SwitchType](#switchtype12) | 是 | 全局开关类型。 | 479 480**返回值：** 481 482| 类型 | 说明 | 483| :------------ | :---------------------------------- | 484| Promise<boolean> | Promise对象。返回全局开关状态。 | 485 486**错误码：** 487 488以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 489 490| 错误码ID | 错误信息 | 491| -------- | -------- | 492| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 493| 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. | 494| 12100010 | The request already exists. | 495| 12100013 | The specific global switch is already open. | 496 497**示例：** 498示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 499 500```ts 501import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit'; 502import { BusinessError } from '@kit.BasicServicesKit'; 503 504let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 505let context: Context = getContext(this) as common.UIAbilityContext; 506atManager.requestGlobalSwitch(context, abilityAccessCtrl.SwitchType.CAMERA).then((data: Boolean) => { 507 console.info('data:' + JSON.stringify(data)); 508}).catch((err: BusinessError) => { 509 console.error('data:' + JSON.stringify(err)); 510}); 511``` 512 513### SwitchType<sup>12+</sup> 514 515表示全局开关类型。 516 517**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 518 519**系统能力：** SystemCapability.Security.AccessToken 520 521| 名称 | 值 | 说明 | 522| ------------------ | ----- | ----------- | 523| CAMERA | 0 | 表示相机全局开关。 | 524| MICROPHONE | 1 | 表示麦克风全局开关。 | 525| LOCATION | 2 | 表示位置全局开关。 |