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

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

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

导入模块

import abilityAccessCtrl from '@ohos.abilityAccessCtrl'

abilityAccessCtrl.createAtManager

createAtManager(): AtManager

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

系统能力： SystemCapability.Security.AccessToken

返回值：

示例：

let atManager = abilityAccessCtrl.createAtManager();

AtManager

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

checkAccessToken⁹⁺

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

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

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
try {
    atManager.checkAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => {
        console.log(`checkAccessToken success, data->${JSON.stringify(data)}`);
    }).catch((err) => {
        console.log(`checkAccessToken fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

verifyAccessTokenSync⁹⁺

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

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

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let data = atManager.verifyAccessTokenSync(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
console.log(`data->${JSON.stringify(data)}`);

grantUserGrantedPermission

grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>

授予应用user grant权限。使用Promise异步回调。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.GRANT_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags).then(() => {
        console.log('grantUserGrantedPermission success');
    }).catch((err) => {
        console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

grantUserGrantedPermission

grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void

授予应用user grant权限。使用callback异步回调。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.GRANT_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags, (err, data) => {
        if (err) {
            console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('grantUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

revokeUserGrantedPermission

revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>

撤销应用user grant权限。使用Promise异步回调。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags).then(() => {
        console.log('revokeUserGrantedPermission success');
    }).catch((err) => {
        console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

revokeUserGrantedPermission

revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void

撤销应用user grant权限。使用callback异步回调。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags, (err, data) => {
        if (err) {
            console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('revokeUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

getPermissionFlags

getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number>

获取指定应用的指定权限的flag。使用Promise异步回调。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
try {
    atManager.getPermissionFlags(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => {
        console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`);
    }).catch((err) => {
        console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

getVersion⁹⁺

getVersion(): Promise<number>

获取当前权限管理的数据版本。使用Promise异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Security.AccessToken

返回值：

示例：

let atManager = abilityAccessCtrl.createAtManager();
let promise = atManager.getVersion();
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

on⁹⁺

on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void;

订阅指定tokenId列表与权限列表的权限状态变更事件。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.GET_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import {Permissions} from '@ohos.abilityAccessCtrl';
import bundleManager from '@ohos.bundle.bundleManager';

let atManager = abilityAccessCtrl.createAtManager();
let appInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
let tokenIDList: Array<number> = [appInfo.accessTokenId];
let permissionList: Array<Permissions> = ["ohos.permission.DISTRIBUTED_DATASYNC"];
try {
    atManager.on('permissionStateChange', tokenIDList, permissionList, (data) => {
        console.debug("receive permission state change, data:" + JSON.stringify(data));
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

off⁹⁺

off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void;

取消订阅指定tokenId列表与权限列表的权限状态变更事件，使用callback回调异步返回结果。

系统接口： 此接口为系统接口。

需要权限： ohos.permission.GET_SENSITIVE_PERMISSIONS，仅系统应用可用。

系统能力： SystemCapability.Security.AccessToken

参数：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import {Permissions} from '@ohos.abilityAccessCtrl';
import bundleManager from '@ohos.bundle.bundleManager';

let atManager = abilityAccessCtrl.createAtManager();
let appInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
let tokenIDList: Array<number> = [appInfo.accessTokenId];
let permissionList: Array<Permissions> = ["ohos.permission.DISTRIBUTED_DATASYNC"];
try {
    atManager.off('permissionStateChange', tokenIDList, permissionList);
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

verifyAccessToken⁹⁺

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

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

说明：

建议使用checkAccessToken替代。

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

requestPermissionsFromUser⁹⁺

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

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

说明：

非UIAbility不支持调用本函数。

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

系统能力: SystemCapability.Security.AccessToken

参数：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
let atManager = abilityAccessCtrl.createAtManager();
try {
  atManager.requestPermissionsFromUser(this.context, ["ohos.permission.CAMERA"], (err, data)=>{
      console.info("data:" + JSON.stringify(data));
      console.info("data permissions:" + data.permissions);
      console.info("data authResults:" + data.authResults);
  });
} catch(err) {
  console.log(`catch err->${JSON.stringify(err)}`);
}

requestPermissionsFromUser⁹⁺

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

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

说明：

非UIAbility不支持调用本函数。

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

系统能力: SystemCapability.Security.AccessToken

参数：

返回值：

错误码：

以下错误码的详细介绍请参见程序访问控制错误码。

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
let atManager = abilityAccessCtrl.createAtManager();
try {
  atManager.requestPermissionsFromUser(this.context, ["ohos.permission.CAMERA"]).then((data) => {
      console.info("data:" + JSON.stringify(data));
      console.info("data permissions:" + data.permissions);
      console.info("data authResults:" + data.authResults);
  }).catch((err) => {
      console.info("data:" + JSON.stringify(err));
  })
} catch(err) {
  console.log(`catch err->${JSON.stringify(err)}`);
}

verifyAccessToken^(deprecated)

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

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

说明：

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

系统能力： SystemCapability.Security.AccessToken

参数：

返回值：

示例：

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

GrantStatus

表示授权状态的枚举。

系统能力： SystemCapability.Security.AccessToken

PermissionStateChangeType⁹⁺

表示权限授权状态变化操作类型的枚举。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Security.AccessToken

PermissionStateChangeInfo⁹⁺

表示某次权限授权状态变化的详情。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Security.AccessToken