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/AccessToken/permissions-for-all.md)中查询。 | 53 54**返回值：** 55 56| 类型 | 说明 | 57| :------------ | :---------------------------------- | 58| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 59 60**错误码：** 61 62以下错误码的详细介绍请参见[访问控制错误码](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获取 76atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 77 console.log(`checkAccessToken success, data->${JSON.stringify(data)}`); 78}).catch((err: BusinessError) => { 79 console.log(`checkAccessToken fail, err->${JSON.stringify(err)}`); 80}); 81``` 82 83### verifyAccessTokenSync<sup>9+</sup> 84 85verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 86 87校验应用是否被授予权限，同步返回结果。 88 89**系统能力：** SystemCapability.Security.AccessToken 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| -------- | ------------------- | ---- | ------------------------------------------ | 95| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 96| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 97 98**返回值：** 99 100| 类型 | 说明 | 101| :------------ | :---------------------------------- | 102| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 103 104**错误码：** 105 106以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 107 108| 错误码ID | 错误信息 | 109| -------- | -------- | 110| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 111 112**示例：** 113 114```ts 115import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 116 117let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 118let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 119let data: abilityAccessCtrl.GrantStatus = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'); 120console.log(`data->${JSON.stringify(data)}`); 121``` 122 123### verifyAccessToken<sup>9+</sup> 124 125verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> 126 127校验应用是否授予权限。使用Promise异步回调。 128 129> **说明：** 130> 131> 建议使用[checkAccessToken](#checkaccesstoken9)替代。 132 133**系统能力：** SystemCapability.Security.AccessToken 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| -------- | ------------------- | ---- | ------------------------------------------ | 139| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 140| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 141 142**返回值：** 143 144| 类型 | 说明 | 145| :------------ | :---------------------------------- | 146| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 147 148**示例：** 149 150```ts 151import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 152import { BusinessError } from '@ohos.base'; 153 154let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 155let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 156let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 157atManager.verifyAccessToken(tokenID, permissionName).then((data: abilityAccessCtrl.GrantStatus) => { 158 console.log(`promise: data->${JSON.stringify(data)}`); 159}).catch((err: BusinessError) => { 160 console.log(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 161}); 162``` 163 164### requestPermissionsFromUser<sup>9+</sup> 165 166requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>) : void 167 168用于UIAbility拉起弹框请求用户授权。使用callback异步回调。 169 170如果用户拒绝授权，将无法再次拉起弹框，需要用户在系统应用“设置”的界面中，手动授予权限。 171 172> **说明：** 173> 174> 非UIAbility不支持调用本函数。 175 176**模型约束**：此接口仅可在Stage模型下使用。 177 178**系统能力**: SystemCapability.Security.AccessToken 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| -------- | -------- | -------- | -------- | 184| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 | 185| permissionList | Array<Permissions> | 是 | 权限名列表，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 186| requestCallback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 是 | 回调函数，返回接口调用是否成功的结果。 | 187 188**错误码：** 189 190以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 191 192| 错误码ID | 错误信息 | 193| -------- | -------- | 194| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. | 195 196**示例：** 197示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 198 199```ts 200import abilityAccessCtrl, { Context, PermissionRequestResult } from '@ohos.abilityAccessCtrl'; 201import { BusinessError } from '@ohos.base'; 202import common from '@ohos.app.ability.common'; 203 204let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 205let context: Context = getContext(this) as common.UIAbilityContext; 206atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult)=>{ 207 if (err) { 208 console.log(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`); 209 } else { 210 console.info('data:' + JSON.stringify(data)); 211 console.info('data permissions:' + data.permissions); 212 console.info('data authResults:' + data.authResults); 213 } 214}); 215``` 216 217### requestPermissionsFromUser<sup>9+</sup> 218 219requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>) : Promise<PermissionRequestResult> 220 221用于UIAbility拉起弹框请求用户授权。使用promise异步回调。 222 223如果用户拒绝授权，将无法再次拉起弹框，需要用户在系统应用“设置”的界面中，手动授予权限。 224 225> **说明：** 226> 227> 非UIAbility不支持调用本函数。 228 229**模型约束**：此接口仅可在Stage模型下使用。 230 231**系统能力**: SystemCapability.Security.AccessToken 232 233**参数：** 234 235| 参数名 | 类型 | 必填 | 说明 | 236| -------- | -------- | -------- | -------- | 237| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 | 238| permissionList | Array<Permissions> | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 239 240**返回值：** 241 242| 类型 | 说明 | 243| -------- | -------- | 244| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | 返回一个Promise，包含接口的结果。 | 245 246**错误码：** 247 248以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 249 250| 错误码ID | 错误信息 | 251| -------- | -------- | 252| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. | 253 254**示例：** 255示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 256 257```ts 258import abilityAccessCtrl, { Context, PermissionRequestResult } from '@ohos.abilityAccessCtrl'; 259import { BusinessError } from '@ohos.base'; 260import common from '@ohos.app.ability.common'; 261 262let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 263let context: Context = getContext(this) as common.UIAbilityContext; 264atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => { 265 console.info('data:' + JSON.stringify(data)); 266 console.info('data permissions:' + data.permissions); 267 console.info('data authResults:' + data.authResults); 268}).catch((err: BusinessError) => { 269 console.info('data:' + JSON.stringify(err)); 270}); 271``` 272 273### verifyAccessToken<sup>(deprecated)</sup> 274 275verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> 276 277校验应用是否授予权限。使用Promise异步回调。 278 279> **说明：** 280> 281> 从API version 9开始不再维护，建议使用[checkAccessToken](#checkaccesstoken9)替代。 282 283**系统能力：** SystemCapability.Security.AccessToken 284 285**参数：** 286 287| 参数名 | 类型 | 必填 | 说明 | 288| -------- | ------------------- | ---- | ------------------------------------------ | 289| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 290| permissionName | string | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 291 292**返回值：** 293 294| 类型 | 说明 | 295| :------------ | :---------------------------------- | 296| Promise<GrantStatus> | Promise对象。返回授权状态结果。 | 297 298**示例：** 299 300```ts 301import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 302import { BusinessError } from '@ohos.base'; 303 304let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 305let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 306atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => { 307 console.log(`promise: data->${JSON.stringify(data)}`); 308}).catch((err: BusinessError) => { 309 console.log(`verifyAccessToken fail, err->${JSON.stringify(err)}`); 310}); 311``` 312 313### checkAccessTokenSync<sup>10+</sup> 314 315checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus 316 317校验应用是否被授予权限，同步返回结果。 318 319**系统能力：** SystemCapability.Security.AccessToken 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| -------- | ------------------- | ---- | ------------------------------------------ | 325| tokenID | number | 是 | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 326| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 327 328**返回值：** 329 330| 类型 | 说明 | 331| :------------ | :---------------------------------- | 332| [GrantStatus](#grantstatus) | 枚举实例，返回授权状态。 | 333 334**错误码：** 335 336以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 337 338| 错误码ID | 错误信息 | 339| -------- | -------- | 340| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 341 342**示例：** 343 344```ts 345import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 346 347let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 348let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 349let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS'; 350let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName); 351console.log(`data->${JSON.stringify(data)}`); 352``` 353 354### GrantStatus 355 356表示授权状态的枚举。 357 358**系统能力：** SystemCapability.Security.AccessToken 359 360| 名称 | 值 | 说明 | 361| ------------------ | ----- | ----------- | 362| PERMISSION_DENIED | -1 | 表示未授权。 | 363| PERMISSION_GRANTED | 0 | 表示已授权。 | 364