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


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

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

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

导入模块

import abilityAccessCtrl from '@ohos.abilityAccessCtrl'
1

abilityAccessCtrl.createAtManager

createAtManager(): AtManager

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

系统能力: SystemCapability.Security.AccessToken

返回值:

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

示例:

let atManager = abilityAccessCtrl.createAtManager();
1

AtManager

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

checkAccessToken9+

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

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

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验的目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 需要校验的权限名称。

返回值:

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

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
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)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13

verifyAccessTokenSync9+

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

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

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验应用的身份标识。
permissionName Permissions 需要校验的权限名称。

返回值:

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

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0

示例:

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0;
let data = atManager.verifyAccessTokenSync(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
console.log(`data->${JSON.stringify(data)}`);
1
2
3
4

grantUserGrantedPermission

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

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

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GRANT_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被授予的权限名称。
permissionFlag number 授权选项,1表示下次仍需弹窗,2表示允许、禁止后不再提醒,3表示系统授权不允许更改。

返回值:

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0
12100002 The specified tokenID does not exist.
12100003 The specified permission does not exist.
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.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let permissionFlag = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag).then(() => {
        console.log('grantUserGrantedPermission success');
    }).catch((err) => {
        console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

grantUserGrantedPermission

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

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

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GRANT_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被授予的权限名称。
permissionFlag number 授权选项,1表示下次仍需弹窗,2表示允许、禁止后不再提醒,3表示系统授权不允许更改。
callback AsyncCallback<void> 授予应用user grant权限。当授予权限成功时,err为undefine;否则为错误对象。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0
12100002 TokenId does not exist.
12100003 Permission does not exist.
12100006 The specified application does not support the permissions granted or ungranted as specified.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let permissionFlag = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (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)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

revokeUserGrantedPermission

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

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

系统接口: 此接口为系统接口。

需要权限: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被撤销的权限名称。
permissionFlag number 授权选项,1表示下次仍需弹窗,2表示允许、禁止后不再提醒,3表示系统授权不允许更改。

返回值:

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0
12100002 The specified tokenID does not exist.
12100003 The specified permission does not exist.
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.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let permissionFlag = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag).then(() => {
        console.log('revokeUserGrantedPermission success');
    }).catch((err) => {
        console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

revokeUserGrantedPermission

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

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

系统接口: 此接口为系统接口。

需要权限: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被撤销的权限名称。
permissionFlag number 授权选项,1表示下次仍需弹窗,2表示允许、禁止后不再提醒,3表示系统授权不允许更改。
callback AsyncCallback<void> 撤销应用user grant权限。当撤销权限成功时,err为undefine;否则为错误对象。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0
12100002 TokenId does not exist.
12100003 Permission does not exist.
12100006 The specified application does not support the permissions granted or ungranted as specified.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let permissionFlag = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (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)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 查询的权限名称。

返回值:

类型 说明
Promise<number> Promise对象。返回查询结果。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0
12100002 The specified tokenID does not exist.
12100003 The specified permission does not exist.
12100006 The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let permissionFlag = 1;
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)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

getVersion9+

getVersion(): Promise<number>

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

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Security.AccessToken

返回值:

类型 说明
Promise<number> Promise对象。返回查询到的版本号。

示例:

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

on9+

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

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

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GET_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
type string 订阅事件类型,固定为'permissionStateChange',权限状态变更事件。
tokenIDList Array<number> 订阅的tokenId列表,为空时表示订阅所有的应用的权限状态变化。
permissionNameList Array<Permissions> 订阅的权限名列表,为空时表示订阅所有的权限状态变化。
callback Callback<PermissionStateChangeInfo> 订阅指定tokenId与指定权限名状态变更事件的回调。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0
12100004 The interface is called repeatedly with the same input.
12100005 The registration time has exceeded the limitation.
12100007 Service is abnormal.
12100008 Out of memory.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenIDList: Array<number> = [];
let permissionNameList = [];
try {
    atManager.on('permissionStateChange', tokenIDList, permissionNameList, (data) => {
        console.debug("receive permission state change, data:" + JSON.stringify(data));
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12

off9+

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

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

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GET_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
type string 订阅事件类型,固定为'permissionStateChange',权限状态变更事件。
tokenIDList Array<number> 订阅的tokenId列表,为空时表示订阅所有的应用的权限状态变化,必须与on的输入一致。
permissionNameList Array<Permissions> 订阅的权限名列表,为空时表示订阅所有的权限状态变化,必须与on的输入一致。
callback Callback<PermissionStateChangeInfo> 取消订阅指定tokenId与指定权限名状态变更事件的回调。

错误码:

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

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID in list is all invalid
12100004 The interface is not used with
12100007 Service is abnormal.
12100008 Out of memory.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenIDList: Array<number> = [];
let permissionNameList = [];
try {
    atManager.off('permissionStateChange', tokenIDList, permissionNameList);
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
1
2
3
4
5
6
7
8
9
10

verifyAccessToken9+

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

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

说明: 建议使用checkAccessToken替代。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验的目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 需要校验的权限名称。仅支持输入有效的权限名称。

返回值:

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

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
1
2
3
4
5
6
7
8

requestPermissionsFromUser9+

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

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

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

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
context Context 请求权限的应用ability上下文context。
permissions Array<Permissions> 权限列表。
callback AsyncCallback<PermissionRequestResult> 回调函数,返回接口调用是否成功的结果。

错误码:

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

错误码ID 错误信息
12100001 Parameter invalid.

示例:

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)}`);
}
1
2
3
4
5
6
7
8
9
10
11

requestPermissionsFromUser9+

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

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

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

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
context Context 请求权限的应用ability上下文context。
permissions Array<Permissions> 权限列表。

返回值:

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

错误码:

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

错误码ID 错误信息
12100001 Parameter invalid.

示例:

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)}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13

verifyAccessToken(deprecated)

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

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

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

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验的目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName string 需要校验的权限名称。

返回值:

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

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 可以通过getApplicationInfo获取accessTokenId
let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
1
2
3
4
5
6
7
8

GrantStatus

表示授权状态的枚举。

系统能力: SystemCapability.Security.AccessToken

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

PermissionStateChangeType9+

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

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Security.AccessToken

名称 说明
PERMISSION_REVOKED_OPER 0 表示权限取消操作。
PERMISSION_GRANTED_OPER 1 表示权限授予操作。

PermissionStateChangeInfo9+

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

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Security.AccessToken

名称 类型 可读 可写 说明
change PermissionStateChangeType 权限授权状态变化类型。
tokenID number 被订阅的应用身份标识。
permissionName Permissions 当前授权状态发生变化的权限名。