@ohos.abilityAccessCtrl (Application Access Control)

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

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.

Modules to Import

import { abilityAccessCtrl } from '@kit.AbilityKit'

abilityAccessCtrl.createAtManager

createAtManager(): AtManager

Creates an AtManager instance for application access control.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Security.AccessToken

Return value

Example

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

AtManager

Provides APIs for application access control.

checkAccessToken⁹⁺

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

Checks whether a permission is granted to an application. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

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 third-party application.
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)}`);
});

checkAccessTokenSync¹⁰⁺

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

Checks whether a permission is granted to an application. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

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';

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 third-party application.
let permissionName: Permissions = 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS';
let data: abilityAccessCtrl.GrantStatus = atManager.checkAccessTokenSync(tokenID, permissionName);
console.log(`data->${JSON.stringify(data)}`);

on¹⁸⁺

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

Subscribes to changes in the state of the specified permissions for this application.

Multiple callbacks can be registered for the same permission list.

The same callback cannot be registered for overlapping permission lists.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

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

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let permissionList: Array<Permissions> = ['ohos.permission.APPROXIMATELY_LOCATION'];
try {
    atManager.on('selfPermissionStateChange', permissionList, (data: abilityAccessCtrl.PermissionStateChangeInfo) => {
        console.log('receive permission state change, data:' + JSON.stringify(data));
    });
} catch(err) {
    console.error(`catch err->${JSON.stringify(err)}`);
}

off¹⁸⁺

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

Unsubscribes from changes in the state of the specified permissions for this application.

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

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

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

Example

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let permissionList: Array<Permissions> = ['ohos.permission.APPROXIMATELY_LOCATION'];
try {
    atManager.off('selfPermissionStateChange', permissionList);
} catch(err) {
    console.error(`catch err->${JSON.stringify(err)}`);
}

requestPermissionsFromUser⁹⁺

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

Requests user authorization in a dialog box opened by a UIAbility. This API uses an asynchronous callback to return the result.

If the user rejects to grant the permission, the authorization dialog box cannot be displayed again. If required, the user can manually grant the permission on the Settings page. Alternatively, call requestPermissionOnSetting to display the permission settings dialog box for the user to grant the permission.

NOTE

Only UIAbility is supported.

Atomic service API: This API can be used in atomic services since API version 12.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

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

Example

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility. For details about the process and example of applying for user authorization, see Requesting User Authorization.

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = this.getUIContext().getHostContext() 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);
  }
});

requestPermissionsFromUser⁹⁺

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

Requests user authorization in a dialog box opened by a UIAbility. This API uses a promise to return the result.

If the user rejects to grant the permission, the authorization dialog box cannot be displayed again. If required, the user can manually grant the permission on the Settings page. Alternatively, call requestPermissionOnSetting to display the permission settings dialog box for the user to grant the permission.

NOTE

Only UIAbility is supported.

Atomic service API: This API can be used in atomic services since API version 11.

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

For details about how to obtain the context in the example, see Obtaining the Context of UIAbility. For details about the process and example of applying for user authorization, see Requesting User Authorization.

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = this.getUIContext().getHostContext() 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));
});

requestPermissionOnSetting¹²⁺

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

Requests permissions in a Settings dialog box. This API displays a permission settings dialog box for a UIAbility/UIExtensionAbility to grant permissions the second time.

Before calling this API, the application must have called requestPermissionsFromUser. If the user grants the permissions required when the authorization dialog box is displayed the first time, calling this API will not display the permission settings dialog box.

NOTE

This API supports only UIAbilities/UIExtensionAbilities.

Atomic service API: This API can be used in atomic services since API version 12.

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 For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = this.getUIContext().getHostContext() 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));
});

requestGlobalSwitch¹²⁺

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

Displays a dialog box for setting a global switch.

When the features such as recording and photographing are disabled, the application can call this API to open the dialog box, asking the user to enable the related features. If the global switch is turned on, no dialog box will be displayed.

NOTE

This API supports only UIAbilities/UIExtensionAbilities.

Atomic service API: This API can be used in atomic services since API version 12.

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 For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.

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

let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
let context: Context = this.getUIContext().getHostContext() 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));
});

verifyAccessTokenSync⁹⁺

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

Verifies whether a permission is granted to an application. This API returns the result synchronously.

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';

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 third-party application.
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)}`);
}

verifyAccessToken⁹⁺

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

Verifies whether a permission is granted to an application. This API uses a promise to return the result.

NOTE

You are advised to use checkAccessToken.

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Example

import { abilityAccessCtrl, Permissions } 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 third-party application.
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)}`);
});

verifyAccessToken^(deprecated)

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

Verifies whether a permission is granted to an application. This API uses a promise to return the result.

NOTE

This API is no longer maintained since API version 9. Use checkAccessToken instead.

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

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 third-party application.
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)}`);
});

GrantStatus

Enumerates the permission grant states.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Security.AccessToken

SwitchType¹²⁺

Enumerates the global switch types.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Security.AccessToken

PermissionStateChangeType¹⁸⁺

Enumerates the operations that trigger permission state changes.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Security.AccessToken

PermissionStateChangeInfo¹⁸⁺

Represents the permission state change details.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Security.AccessToken

PermissionRequestResult¹⁰⁺

type PermissionRequestResult = _PermissionRequestResult

Represents the permission request result.

Atomic service API: This API can be used in atomic services since API version 11.

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

System capability: SystemCapability.Security.AccessToken

Context¹⁰⁺

type Context = _Context

Represents the context for the ability or application. It allows access to application-specific resources.

Atomic service API: This API can be used in atomic services since API version 11.

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

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