1# @ohos.abilityAccessCtrl (程序访问控制管理)(系统接口) 2 3程序访问控制提供程序的权限管理能力，包括鉴权、授权和取消授权等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.abilityAccessCtrl (程序访问控制管理)](js-apis-abilityAccessCtrl.md)。 9 10## 导入模块 11 12```ts 13import abilityAccessCtrl from '@ohos.abilityAccessCtrl' 14``` 15 16## AtManager 17 18管理访问控制模块的实例。 19 20### grantUserGrantedPermission 21 22grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 23 24授予应用user_grant权限。使用Promise异步回调。 25 26**系统接口：** 此接口为系统接口。 27 28**需要权限：** ohos.permission.GRANT_SENSITIVE_PERMISSIONS，仅系统应用可用。 29 30**系统能力：** SystemCapability.Security.AccessToken 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| --------- | ------------------- | ---- | ------------------------------------------------------------ | 36| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 37| permissionName | Permissions | 是 | 被授予的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 38| permissionFlags | number | 是 | 授权选项<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 64表示当次用户若选择仅本次允许，权限仅本次授权，应用切换后台状态或退出后取消授权。 | 39 40**返回值：** 41 42| 类型 | 说明 | 43| :------------ | :---------------------------------- | 44| Promise<void> | Promise对象。无返回结果的Promise对象。 | 45 46**错误码：** 47 48以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 49 50| 错误码ID | 错误信息 | 51| -------- | -------- | 52| 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. | 53| 12100002 | The specified tokenID does not exist. | 54| 12100003 | The specified permission does not exist. | 55| 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. | 56| 12100007 | Service is abnormal. | 57 58**示例：** 59 60```ts 61import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 62import { BusinessError } from '@ohos.base'; 63 64let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 65let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 66let permissionFlags: number = 1; 67atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 68 console.log('grantUserGrantedPermission success'); 69}).catch((err: BusinessError) => { 70 console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 71}); 72``` 73 74### grantUserGrantedPermission 75 76grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 77 78授予应用user_grant权限。使用callback异步回调。 79 80**系统接口：** 此接口为系统接口。 81 82**需要权限：** ohos.permission.GRANT_SENSITIVE_PERMISSIONS，仅系统应用可用。 83 84**系统能力：** SystemCapability.Security.AccessToken 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| --------- | ------------------- | ---- | ------------------------------------------------------------ | 90| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。| 91| permissionName | Permissions | 是 | 被授予的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 92| permissionFlags | number | 是 | 授权选项<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 64表示当次用户若选择仅本次允许，权限仅本次授权，应用切换后台状态或退出后取消授权。 | 93| callback | AsyncCallback<void> | 是 | 授予应用user_grant权限。当授予权限成功时，err为undefined；否则为错误对象。 | 94 95**错误码：** 96 97以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 98 99| 错误码ID | 错误信息 | 100| -------- | -------- | 101| 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. | 102| 12100002 | The specified tokenID does not exist. | 103| 12100003 | The specified permission does not exist. | 104| 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. | 105| 12100007 | Service is abnormal. | 106 107**示例：** 108 109```ts 110import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 111import { BusinessError } from '@ohos.base'; 112 113let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 114let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 115let permissionFlags: number = 1; 116atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 117 if (err) { 118 console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); 119 } else { 120 console.log('grantUserGrantedPermission success'); 121 } 122}); 123``` 124 125### revokeUserGrantedPermission 126 127revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void> 128 129撤销应用user_grant权限。使用Promise异步回调。 130 131**系统接口：** 此接口为系统接口。 132 133**需要权限：** ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。 134 135**系统能力：** SystemCapability.Security.AccessToken 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| --------- | ------------------- | ---- | ------------------------------------------------------------ | 141| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 142| permissionName | Permissions | 是 | 被撤销的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 143| permissionFlags | number | 是 | 授权选项<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 64表示当次用户若选择仅本次允许，权限仅本次授权，应用切换后台状态或退出后取消授权。 | 144 145**返回值：** 146 147| 类型 | 说明 | 148| :------------ | :---------------------------------- | 149| Promise<void> | Promise对象。无返回结果的Promise对象。 | 150 151**错误码：** 152 153以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 154 155| 错误码ID | 错误信息 | 156| -------- | -------- | 157| 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. | 158| 12100002 | The specified tokenID does not exist. | 159| 12100003 | The specified permission does not exist. | 160| 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. | 161| 12100007 | Service is abnormal. | 162 163**示例：** 164 165```ts 166import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 167import { BusinessError } from '@ohos.base'; 168 169let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 170let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 171let permissionFlags: number = 1; 172atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => { 173 console.log('revokeUserGrantedPermission success'); 174}).catch((err: BusinessError) => { 175 console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 176}); 177``` 178 179### revokeUserGrantedPermission 180 181revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void 182 183撤销应用user_grant权限。使用callback异步回调。 184 185**系统接口：** 此接口为系统接口。 186 187**需要权限：** ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。 188 189**系统能力：** SystemCapability.Security.AccessToken 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| --------- | ------------------- | ---- | ------------------------------------------------------------ | 195| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 196| permissionName | Permissions | 是 | 被撤销的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 197| permissionFlags | number | 是 | 授权选项<br>- 1表示当次用户若选择禁止该权限，下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限，下次不会再弹出权限弹窗，需要用户在setting的权限管理中进行授权。<br>- 64表示当次用户若选择仅本次允许，权限仅本次授权，应用切换后台状态或退出后取消授权。 | 198| callback | AsyncCallback<void> | 是 | 撤销应用user_grant权限。当撤销权限成功时，err为undefined；否则为错误对象。 | 199 200**错误码：** 201 202以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 203 204| 错误码ID | 错误信息 | 205| -------- | -------- | 206| 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. | 207| 12100002 | The specified tokenID does not exist. | 208| 12100003 | The specified permission does not exist. | 209| 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. | 210| 12100007 | Service is abnormal. | 211 212**示例：** 213 214```ts 215import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 216import { BusinessError } from '@ohos.base'; 217 218let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 219let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 220let permissionFlags: number = 1; 221atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => { 222 if (err) { 223 console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); 224 } else { 225 console.log('revokeUserGrantedPermission success'); 226 } 227}); 228``` 229 230### getPermissionFlags 231 232getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number> 233 234获取指定应用的指定权限的flag。使用Promise异步回调。 235 236**系统接口：** 此接口为系统接口。 237 238**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。 239 240**系统能力：** SystemCapability.Security.AccessToken 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245| --------- | ------------------- | ---- | ------------------------------------------------------------ | 246| tokenID | number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。 | 247| permissionName | Permissions | 是 | 查询的权限名称，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 248 249**返回值：** 250 251| 类型 | 说明 | 252| :------------ | :---------------------------------- | 253| Promise<number> | Promise对象。返回查询结果。 | 254 255**错误码：** 256 257以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 258 259| 错误码ID | 错误信息 | 260| -------- | -------- | 261| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 262| 12100002 | The specified tokenID does not exist. | 263| 12100003 | The specified permission does not exist. | 264| 12100006 | The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. | 265| 12100007 | Service is abnormal. | 266 267**示例：** 268 269```ts 270import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 271import { BusinessError } from '@ohos.base'; 272 273let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 274let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 275atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => { 276 console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`); 277}).catch((err: BusinessError) => { 278 console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`); 279}); 280``` 281 282### getVersion<sup>9+</sup> 283 284getVersion(): Promise<number> 285 286获取当前权限管理的数据版本。使用Promise异步回调。 287 288**系统接口：** 此接口为系统接口。 289 290**系统能力：** SystemCapability.Security.AccessToken 291 292**返回值：** 293 294| 类型 | 说明 | 295| :------------ | :---------------------------------- | 296| Promise<number> | Promise对象。返回查询到的版本号。 | 297 298**示例：** 299 300```ts 301import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; 302 303let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 304let promise = atManager.getVersion(); 305promise.then((data: number) => { 306 console.log(`promise: data->${JSON.stringify(data)}`); 307}); 308``` 309 310### on<sup>9+</sup> 311 312on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void 313 314订阅指定tokenId列表与权限列表的权限状态变更事件。 315 316允许指定tokenId列表与权限列表订阅多个callback。 317 318不允许存在交集的tokenId列表与权限列表订阅相同callback。 319 320**系统接口：** 此接口为系统接口。 321 322**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS，仅系统应用可用。 323 324**系统能力：** SystemCapability.Security.AccessToken 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 330| type | string | 是 | 订阅事件类型，固定为'permissionStateChange'，权限状态变更事件。 | 331| tokenIDList | Array<number> | 是 | 订阅的tokenId列表，为空时表示订阅所有的应用的权限状态变化。 | 332| permissionList | Array<Permissions> | 是 | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。| 333| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | 是 | 订阅指定tokenId与指定权限名状态变更事件的回调。| 334 335**错误码：** 336 337以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 338 339| 错误码ID | 错误信息 | 340| -------- | -------- | 341| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. | 342| 12100004 | The interface is called repeatedly with the same input. | 343| 12100005 | The registration time has exceeded the limitation. | 344| 12100007 | Service is abnormal. | 345| 12100008 | Out of memory. | 346 347**示例：** 348 349```ts 350import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 351import bundleManager from '@ohos.bundle.bundleManager'; 352 353let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 354let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 355let tokenIDList: Array<number> = [appInfo.accessTokenId]; 356let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 357try { 358 atManager.on('permissionStateChange', tokenIDList, permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => { 359 console.debug('receive permission state change, data:' + JSON.stringify(data)); 360 }); 361} catch(err) { 362 console.log(`catch err->${JSON.stringify(err)}`); 363} 364``` 365 366### off<sup>9+</sup> 367 368off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void 369 370取消订阅指定tokenId列表与权限列表的权限状态变更事件，使用callback回调异步返回结果。 371 372取消订阅不传callback时，批量删除tokenIDList和permissionList下面的所有callback。 373 374**系统接口：** 此接口为系统接口。 375 376**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS，仅系统应用可用。 377 378**系统能力：** SystemCapability.Security.AccessToken 379 380**参数：** 381 382| 参数名 | 类型 | 必填 | 说明 | 383| ------------------ | --------------------- | ---- | ------------------------------------------------------------ | 384| type | string | 是 | 订阅事件类型，固定为'permissionStateChange'，权限状态变更事件。 | 385| tokenIDList | Array<number> | 是 | 订阅的tokenId列表，为空时表示订阅所有的应用的权限状态变化，必须与on的输入一致。 | 386| permissionList | Array<Permissions> | 是 | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，必须与on的输入一致，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 387| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | 否 | 取消订阅指定tokenId与指定权限名状态变更事件的回调。| 388 389**错误码：** 390 391以下错误码的详细介绍请参见[访问控制错误码](errorcode-access-token.md)。 392 393| 错误码ID | 错误信息 | 394| -------- | -------- | 395| 12100001 | The parameter is invalid. The tokenIDs or permissionNames in the list are all invalid. | 396| 12100004 | The interface is not used together with 'on'. | 397| 12100007 | Service is abnormal. | 398| 12100008 | Out of memory. | 399 400**示例：** 401 402```ts 403import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; 404import bundleManager from '@ohos.bundle.bundleManager'; 405 406let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); 407let appInfo: bundleManager.ApplicationInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100); 408let tokenIDList: Array<number> = [appInfo.accessTokenId]; 409let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC']; 410try { 411 atManager.off('permissionStateChange', tokenIDList, permissionList); 412} catch(err) { 413 console.log(`catch err->${JSON.stringify(err)}`); 414} 415``` 416 417### PermissionStateChangeType<sup>9+</sup> 418 419表示权限授权状态变化操作类型的枚举。 420 421**系统接口：** 此接口为系统接口。 422 423**系统能力：** SystemCapability.Security.AccessToken 424 425| 名称 | 值 | 说明 | 426| ----------------------- | ------ | ----------------- | 427| PERMISSION_REVOKED_OPER | 0 | 表示权限取消操作。 | 428| PERMISSION_GRANTED_OPER | 1 | 表示权限授予操作。 | 429 430### PermissionStateChangeInfo<sup>9+</sup> 431 432表示某次权限授权状态变化的详情。 433 434**系统接口：** 此接口为系统接口。 435 436**系统能力：** SystemCapability.Security.AccessToken 437 438| 名称 | 类型 | 可读 | 可写 | 说明 | 439| -------------- | ------------------------- | ---- | ---- | ------------------ | 440| change | [PermissionStateChangeType](#permissionstatechangetype9) | 是 | 否 | 权限授权状态变化类型。 | 441| tokenID | number | 是 | 否 | 被订阅的应用身份标识。 | 442| permissionName | Permissions | 是 | 否 | 当前授权状态发生变化的权限名，合法的权限名取值可在[应用权限列表](../../security/AccessToken/permissions-for-all.md)中查询。 | 443