@ohos.abilityAccessCtrl (Application Access Control) (System API)

The abilityAccessCtrl module provides APIs for application permission management, including authentication, authorization, and revocation.

NOTE

• The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.abilityAccessCtrl (Application Access Control).

Modules to Import

import { abilityAccessCtrl } from '@kit.AbilityKit'

AtManager

Provides APIs for application access control.

grantUserGrantedPermission

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

Grants a user_grant permission to an application. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.log('grantUserGrantedPermission success');
}).catch((err: BusinessError) => {
  console.error(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
});

grantUserGrantedPermission

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

Grants a user_grant permission to an application. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('grantUserGrantedPermission success');
  }
});

revokeUserGrantedPermission

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

Revokes a user_grant permission from an application. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags).then(() => {
  console.log('revokeUserGrantedPermission success');
}).catch((err: BusinessError) => {
  console.error(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
});

revokeUserGrantedPermission

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

Revokes a user_grant permission from an application. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
let permissionFlags: number = 1;
atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.READ_AUDIO', permissionFlags, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('revokeUserGrantedPermission success');
  }
});

getPermissionFlags

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

Obtains the flag of the specified permission of an application. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS, ohos.permission.GRANT_SENSITIVE_PERMISSIONS, or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data: number) => {
  console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getPermissionFlags fail, err->${JSON.stringify(err)}`);
});

setPermissionRequestToggleStatus¹²⁺

setPermissionRequestToggleStatus(permissionName: Permissions, status: PermissionRequestToggleStatus): Promise<void>

Sets the toggle state of a permission. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.DISABLE_PERMISSION_DIALOG

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager = abilityAccessCtrl.createAtManager();
let permission: Permissions = 'ohos.permission.CAMERA';

atManager.setPermissionRequestToggleStatus(permission, abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED).then((err) => {
  console.info('toggle_status: Set closed successful');
}).catch((err: BusinessError) => {
  console.error('toggle_status: Code is ${err.code}, message is ${err.message}');
});

getPermissionRequestToggleStatus¹²⁺

getPermissionRequestToggleStatus(permissionName: Permissions): Promise<PermissionRequestToggleStatus>

Obtains the toggle state of a permission. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager = abilityAccessCtrl.createAtManager();
let permission: Permissions = 'ohos.permission.CAMERA';

atManager.getPermissionRequestToggleStatus(permission).then((res) => {
  if (res == abilityAccessCtrl.PermissionRequestToggleStatus.CLOSED) {
    console.info('toggle_status: The toggle status is close');
  } else {
    console.info('toggle_status: The toggle status is open');
  }
}).catch((err: BusinessError) => {
console.error('toggle_status: Code is ${err.code}, message is ${err.message}');
});

getVersion⁹⁺

getVersion(): Promise<number>

Obtains the data version of the permission management. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

Return value

Example

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

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

getPermissionsStatus¹²⁺

getPermissionsStatus(tokenID: number, permissionList: Array<Permissions>): Promise<Array<PermissionStatus>>

Obtains the status of the specified permissions. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
atManager.getPermissionsStatus(tokenID, ['ohos.permission.CAMERA']).then((data: Array<abilityAccessCtrl.PermissionStatus>) => {
  console.log(`getPermissionsStatus success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getPermissionsStatus fail, err->${JSON.stringify(err)}`);
});

on⁹⁺

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

Subscribes to changes in the state of specified permissions for the given applications.

Multiple callbacks can be registered for the specified tokenIDList and permissionList.

If tokenIDList and permissionList have common values with the tokenIDList and permissionList of a callback registered, callback must be different.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let appInfo: bundleManager.ApplicationInfo = 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: abilityAccessCtrl.PermissionStateChangeInfo) => {
        console.debug('receive permission state change, data:' + JSON.stringify(data));
    });
} catch(err) {
    console.error(`catch err->${JSON.stringify(err)}`);
}

off⁹⁺

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

Unsubscribes from changes in the state of specified permissions for the given applications. This API uses an asynchronous callback to return the result.

If callback is not specified, this API will unregister all callbacks for tokenIDList and permissionList.

System API: This is a system API.

Required permissions: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications)

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let appInfo: bundleManager.ApplicationInfo = 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.error(`catch err->${JSON.stringify(err)}`);
}

requestPermissionOnApplicationSetting¹⁸⁺

requestPermissionOnApplicationSetting(tokenID: number): Promise<void>

Starts the permission settings page for an application. This API uses a promise to return the result.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

For details about the error codes, see Access Control Error Codes.

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let tokenID: number = 0; // System applications can obtain the token ID using bundleManager.getApplicationInfo.
atManager.requestPermissionOnApplicationSetting(tokenID).then(() => {
  console.log('requestPermissionOnApplicationSetting success');
}).catch((err: BusinessError) => {
  console.error(`requestPermissionOnApplicationSetting fail, err->${JSON.stringify(err)}`);
});

PermissionRequestToggleStatus¹²⁺

Enumerates the permission toggle states.

System capability: SystemCapability.Security.AccessToken

PermissionStatus¹²⁺

Enumerates the permission states.

System API: This is a system API.

System capability: SystemCapability.Security.AccessToken

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit

harmony 鸿蒙AbilityAccessControl

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_access_control.h

harmony 鸿蒙ability_base_common.h