鸿蒙5.0开发进阶:@ohos.abilityAccessCtrl (程序访问控制管理)

往期鸿蒙全套实战文章必看:(文中附带全栈鸿蒙学习资料)


@ohos.abilityAccessCtrl (程序访问控制管理)

程序访问控制提供程序的权限管理能力,包括鉴权、授权等。

说明

本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import { abilityAccessCtrl } from '@kit.AbilityKit'

abilityAccessCtrl.createAtManager

createAtManager(): AtManager

访问控制管理:获取访问控制模块对象。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Security.AccessToken

返回值:

类型说明
AtManager获取访问控制模块的实例。

示例:

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();

AtManager

管理访问控制模块的实例。

checkAccessToken9+

checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>

校验应用是否授予权限。使用Promise异步回调。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
tokenIDnumber要校验的目标应用的身份标识。可通过应用的ApplicationInfo的accessTokenId字段获得。
permissionNamePermissions需要校验的权限名称,合法的权限名取值可在应用权限列表中查询。

返回值:

类型说明
Promise<GrantStatus>Promise对象。返回授权状态结果。

错误码:

以下错误码的详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters.

示例:

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,三方应用可以通过bundleManager.getBundleInfoForSelf获取
atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => {
  console.log(`checkAccessToken success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`checkAccessToken fail, err->${JSON.stringify(err)}`);
});

verifyAccessTokenSync9+

verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus

校验应用是否被授予权限,同步返回结果。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
tokenIDnumber要校验应用的身份标识。可通过应用的ApplicationInfo的accessTokenId字段获得。
permissionNamePermissions需要校验的权限名称,合法的权限名取值可在应用权限列表中查询。

返回值:

类型说明
GrantStatus枚举实例,返回授权状态。

错误码:

以下错误码的详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters.

示例:

import { abilityAccessCtrl } from '@kit.AbilityKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,三方应用可以通过bundleManager.getBundleInfoForSelf获取
try {
  let data: abilityAccessCtrl.GrantStatus = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS');
  console.log(`data->${JSON.stringify(data)}`);
} catch(err) {
  console.error(`catch err->${JSON.stringify(err)}`);
}

verifyAccessToken9+

verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>

校验应用是否授予权限。使用Promise异步回调。

说明

建议使用checkAccessToken替代。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
tokenIDnumber要校验的目标应用的身份标识。可通过应用的ApplicationInfo的accessTokenId字段获得。
permissionNamePermissions需要校验的权限名称,合法的权限名取值可在应用权限列表中查询。

返回值:

类型说明
Promise<GrantStatus>Promise对象。返回授权状态结果。

示例:

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,三方应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS';
atManager.verifyAccessToken(tokenID, permissionName).then((data: abilityAccessCtrl.GrantStatus) => {
  console.log(`promise: data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`);
});

requestPermissionsFromUser9+

requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>): void

用于UIAbility拉起弹框请求用户授权。使用callback异步回调。

如果用户拒绝授权,将无法再次拉起弹框,需要用户在系统应用“设置”的界面中,手动授予权限。或是调用requestPermissionOnSetting,拉起权限设置弹框,引导用户授权。

说明

仅支持UIAbility。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束:此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
contextContext请求权限的UIAbility的Context。
permissionListArray<Permissions>权限名列表,合法的权限名取值可在应用权限列表中查询。
requestCallbackAsyncCallback<PermissionRequestResult>回调函数,返回接口调用是否成功的结果。

错误码:

以下错误码的详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001Invalid parameter. The context is invalid when it does not belong to the application itself.

示例:

示例中context的获取方式。

import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA'], (err: BusinessError, data: PermissionRequestResult) => {
  if (err) {
    console.error(`requestPermissionsFromUser fail, err->${JSON.stringify(err)}`);
  } else {
    console.info('data:' + JSON.stringify(data));
    console.info('data permissions:' + data.permissions);
    console.info('data authResults:' + data.authResults);
    console.info('data dialogShownResults:' + data.dialogShownResults);
  }
});

requestPermissionsFromUser9+

requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult>

用于UIAbility拉起弹框请求用户授权。使用promise异步回调。

如果用户拒绝授权,将无法再次拉起弹框,需要用户在系统应用“设置”的界面中,手动授予权限。或是调用requestPermissionOnSetting,拉起权限设置弹框,引导用户授权。

说明

仅支持UIAbility。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束:此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
contextContext请求权限的UIAbility的Context。
permissionListArray<Permissions>需要校验的权限名称,合法的权限名取值可在应用权限列表中查询。

返回值:

类型说明
Promise<PermissionRequestResult>返回一个Promise,包含接口的结果。

错误码:

以下错误码的详细介绍

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001Invalid parameter. The context is invalid when it does not belong to the application itself.

示例:

示例中context的获取方式。

import { abilityAccessCtrl, Context, PermissionRequestResult, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA']).then((data: PermissionRequestResult) => {
  console.info('data:' + JSON.stringify(data));
  console.info('data permissions:' + data.permissions);
  console.info('data authResults:' + data.authResults);
  console.info('data dialogShownResults:' + data.dialogShownResults);
}).catch((err: BusinessError) => {
  console.error('data:' + JSON.stringify(err));
});

verifyAccessToken(deprecated)

verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus>

校验应用是否授予权限。使用Promise异步回调。

说明

从API version 9开始不再维护,建议使用checkAccessToken替代。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
tokenIDnumber要校验的目标应用的身份标识。可通过应用的ApplicationInfo的accessTokenId字段获得。
permissionNamestring需要校验的权限名称,合法的权限名取值可在应用权限列表中查询。

返回值:

类型说明
Promise<GrantStatus>Promise对象。返回授权状态结果。

示例:

import { abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,三方应用可以通过bundleManager.getBundleInfoForSelf获取
atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: abilityAccessCtrl.GrantStatus) => {
console.log(`promise: data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
console.error(`verifyAccessToken fail, err->${JSON.stringify(err)}`);
});

checkAccessTokenSync10+

checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus

校验应用是否被授予权限,同步返回结果。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
tokenIDnumber要校验应用的身份标识。可通过应用的ApplicationInfo的accessTokenId字段获得。
permissionNamePermissions需要校验的权限名称,合法的权限名取值可在应用权限列表中查询。

返回值:

类型说明
GrantStatus枚举实例,返回授权状态。

错误码:

以下错误码的详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001Invalid parameter. The tokenID is 0, or the permissionName exceeds 256 characters.

示例:

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,三方应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS';
let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName);
console.log(`data->${JSON.stringify(data)}`);

GrantStatus

表示授权状态的枚举。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Security.AccessToken

名称说明
PERMISSION_DENIED-1表示未授权。
PERMISSION_GRANTED0表示已授权。

requestPermissionOnSetting12+

requestPermissionOnSetting(context: Context, permissionList: Array<Permissions>): Promise<Array<GrantStatus>>

用于UIAbility/UIExtensionAbility二次拉起权限设置弹框。

在调用此接口前,应用需要先调用requestPermissionsFromUser,如果用户在首次弹窗授权时已授权,调用当前接口将无法拉起弹窗。

说明

仅支持UIAbility/UIExtensionAbility。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束:此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
contextContext请求权限的UIAbility/UIExtensionAbility的Context。
permissionListArray<Permissions>权限名列表,合法的权限名取值可在应用权限组列表中查询。

返回值:

类型说明
Promise<Array<GrantStatus>>Promise对象。返回授权状态结果。

错误码:

以下错误码的详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12100001Invalid 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.
12100010The request already exists.
12100011All permissions in the permission list have been granted.
12100012The permission list contains the permission that has not been revoked by the user.

示例:

示例中context的获取方式。

import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestPermissionOnSetting(context, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.GrantStatus>) => {
  console.info('data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error('data:' + JSON.stringify(err));
});

requestGlobalSwitch12+

requestGlobalSwitch(context: Context, type: SwitchType): Promise<boolean>

用于UIAbility/UIExtensionAbility拉起全局开关设置弹框。

部分情况下,录音、拍照等功能禁用,应用可拉起此弹框请求用户同意开启对应功能。如果当前全局开关的状态为开启,则不拉起弹框。

说明

仅支持UIAbility/UIExtensionAbility。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束:此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名类型必填说明
contextContext请求权限的UIAbility/UIExtensionAbility>的Context。
typeSwitchType全局开关类型。

返回值:

类型说明
Promise<boolean>Promise对象。返回全局开关状态。

错误码:

以下错误码的详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12100001Invalid 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.
12100010The request already exists.
12100013The specific global switch is already open.

示例:

示例中context的获取方式。

import { abilityAccessCtrl, Context, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = getContext(this) as common.UIAbilityContext;
atManager.requestGlobalSwitch(context, abilityAccessCtrl.SwitchType.CAMERA).then((data: Boolean) => {
  console.info('data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error('data:' + JSON.stringify(err));
});

SwitchType12+

表示全局开关类型。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Security.AccessToken

名称说明
CAMERA0表示相机全局开关。
MICROPHONE1表示麦克风全局开关。
LOCATION2表示位置全局开关。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值