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.
## Modules to Import
...
...
@@ -30,7 +29,7 @@ Creates an **AtManager** instance, which is used for ability access control.
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | string | Yes | Name of the permission to grant.|
| permissionName | Permissions | Yes | Name of the permission to grant.|
| permissionFlag | number | Yes | Permission flag. The value **1** means that the permission request dialog box will still be displayed after the user grants or denies the permission. The value **2** means that no dialog box will be displayed after the user grants or denies the permission. The value **3** means a system permission that cannot be changed. |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 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. |
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).|
| permissionName | string | Yes | Name of the permission to grant.|
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).|
| permissionName | Permissions | Yes | Name of the permission to grant.|
| permissionFlag | number | Yes | Permission flag. The value **1** means that the permission request dialog box will still be displayed after the user grants or denies the permission. The value **2** means that no dialog box will be displayed after the user grants or denies the permission. The value **3** means a system permission that cannot be changed. |
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the permission is granted successfully, **err** is **undefine**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 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. |
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | string | Yes | Name of the permission to revoke.|
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | Permissions | Yes | Name of the permission to revoke.|
| permissionFlag | number | Yes | Permission flag. The value **1** means that the permission request dialog box will still be displayed after the user grants or denies the permission. The value **2** means that no dialog box will be displayed after the user grants or denies the permission. The value **3** means a system permission that cannot be changed. |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 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. |
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | string | Yes | Name of the permission to revoke.|
| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | Permissions | Yes | Name of the permission to revoke.|
| permissionFlag | number | Yes | Permission flag. The value **1** means that the permission request dialog box will still be displayed after the user grants or denies the permission. The value **2** means that no dialog box will be displayed after the user grants or denies the permission. The value **3** means a system permission that cannot be changed. |
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the permission is revoked successfully, **err** is **undefine**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 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. |
Obtains the flags of the specified permission of a given application. This API uses a promise to return the result.
Obtains the flags of the specified permission of an application. This API uses a promise to return the result.
This is a system API.
**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
**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS, ohos.permission.GRANT_SENSITIVE_PERMISSIONS, or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications)
Subscribes to permission grant state change events of a specified token ID list and permission list. This API uses an asynchronous callback to return the result.
Subscribes to permission grant state changes of the specified applications and permissions.
| type | string | Yes | Event type. The value is fixed at **'permissionStateChange'**, indicating the permission grant state change event. |
| tokenIDList | Array<number> | No | List of token IDs. If this parameter is left empty, the permission grant state changes of all applications are subscribed to. |
| permissionNameList | Array<string> | No | List of permission names. If this parameter is left empty, the permission grant state changes of all permissions are subscribed to. |
| tokenIDList | Array<number> | Yes | List of token IDs. If this parameter is left empty, the permission grant state changes of all applications are subscribed to. |
| permissionNameList | Array<Permissions> | Yes | List of permission names. If this parameter is left empty, the permission grant state changes of all permissions are subscribed to. |
| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | Yes| Callback used to return the permission grant state change information.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 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. |
**Example**
```js
...
...
@@ -378,7 +463,7 @@ import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
Unsubscribes from permission grant state change events of a specified token ID list and permission list. This API uses an asynchronous callback to return the result.
Unsubscribes from permission grant state changes of the specified applications and permissions. This API uses an asynchronous callback to return the result.
| type | string | Yes | Event type. The value is fixed at **'permissionStateChange'**, indicating the permission grant state change event. |
| tokenIDList | Array<number> | No | List of token IDs. If this parameter is left empty, the permission grant state changes of all applications are unsubscribed from. The value must be the same as that passed in **on()**.|
| permissionNameList | Array<string> | No | List of permission names. If this parameter is left empty, the permission grant state changes of all permissions are unsubscribed from. The value must be the same as that passed in **on()**.|
| tokenIDList | Array<number> | Yes | List of token IDs. If this parameter is left empty, the permission grant state changes of all applications are unsubscribed from. The value must be the same as that passed in **on()**.|
| permissionNameList | Array<Permissions> | Yes | List of permission names. If this parameter is left empty, the permission grant state changes of all permissions are unsubscribed from. The value must be the same as that passed in **on()**.|
| callback | Callback<[PermissionStateChangeInfo](#permissionstatechangeinfo9)> | No| Callback used to return the permission grant state change information.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 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. |
**Example**
```js
...
...
@@ -416,7 +512,7 @@ import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
The **PrivacyManager** module provides APIs for privacy management, such as management of permission usage records.
The **privacyManager** module provides APIs for privacy management, such as management of permission usage records.
> **NOTE**
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module are system APIs and cannot be called by third-party applications.
> The APIs provided by this module are system APIs.
## Modules to Import
...
...
@@ -15,10 +15,10 @@ import privacyManager from '@ohos.privacyManager';
Adds a permission usage record when an application protected by the permission is called by another service or application. This API uses a promise to return the result.
The permission usage record includes the application identity of the invoker, name of the permission used, and number of successful and failed accesses to the application.
The permission usage record includes the application identity (token ID) of the invoker, name of the permission used, and number of successful and failed accesses to the target application.
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
...
...
@@ -28,8 +28,8 @@ The permission usage record includes the application identity of the invoker, na
Adds a permission usage record when an application protected by the permission is called by another service or application. This API uses an asynchronous callback to return the result.
The permission usage record includes the application identity of the invoker, name of the permission used, and number of successful and failed accesses to the application.
The permission usage record includes the application identity (token ID) of the invoker, name of the permission used, and number of successful and failed accesses to the target application.
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
...
...
@@ -71,11 +80,20 @@ The permission usage record includes the application identity of the invoker, na
| tokenID | number | Yes | Application token ID of the invoker. You can obtain it from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | string | Yes | Name of the permission.|
| tokenID | number | Yes | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). |
| permissionName | Permissions | Yes | Name of the permission.|
| successCount | number | Yes | Number of successful accesses.|
| failCount | number | Yes | Number of failed accesses.|
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.|
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If a usage record is added successfully, **err** is **undefine**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 12100001 | Parameter invalid. |
| 12100002 | TokenId does not exist. |
| 12100003 | Permission does not exist. |
**Example**
...
...
@@ -84,7 +102,7 @@ import privacyManager from '@ohos.privacyManager';
lettokenID=0;// You can use getApplicationInfo to obtain the access token ID.
| callback | AsyncCallback<[PermissionUsedResponse](#permissionusedresponse)> | Yes| Callback invoked to return the permission usage records obtained.|
| callback | AsyncCallback<[PermissionUsedResponse](#permissionusedresponse)> | Yes| Callback invoked to return the result. If the query is successful, **err** is **undefine** and **data** is the permission usage record. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
Starts to record a permission usage event. This API is called by a system service and uses a promise to return the result. The permissions used by an app in the foreground and background can be observed, and the permission usage records can be saved.
Starts to use a permission and flushes the permission usage record. This API is called by a system application, either running in the foreground or background, and uses a promise to return the result. This API uses a promise to return the result.
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
...
...
@@ -203,8 +239,8 @@ Starts to record a permission usage event. This API is called by a system servic
Starts to record a permission usage event. This API is called by a system service and uses an asynchronous callback to return the result. The permissions used by an app in the foreground and background can be observed and saved.
Starts to use a permission and flushes the permission usage record. This API is called by a system application, either running in the foreground or background, and uses a promise to return the result. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
...
...
@@ -243,9 +289,19 @@ Starts to record a permission usage event. This API is called by a system servic
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the permission is successfully used, **err** is **undefine**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 12100001 | Parameter invalid. |
| 12100002 | TokenId does not exist. |
| 12100003 | Permission does not exist. |
| 12100004 | The interface is not used together. |
**Example**
...
...
@@ -254,7 +310,7 @@ import privacyManager from '@ohos.privacyManager';
lettokenID=0;// You can use getApplicationInfo to obtain the access token ID.
Stops recording the permission usage event. This API is called by a system service and uses a promise to return the result. **startUsingPermission** and **stopUsingPermission** are used in pairs.
Stops using a permission. This API is called by a system application and uses a promise to return the result. **startUsingPermission** and **stopUsingPermission** are used in pairs. This API uses a promise to return the result.
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
...
...
@@ -280,8 +336,8 @@ Stops recording the permission usage event. This API is called by a system servi
Stops recording the permission usage event. This API is called by the system service and uses an asynchronous callback to return the result. **startUsingPermission** and **stopUsingPermission** are used in pairs.
Stops using a permission. This API is called by a system application and uses a promise to return the result. **startUsingPermission** and **stopUsingPermission** are used in pairs. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
...
...
@@ -320,9 +386,19 @@ Stops recording the permission usage event. This API is called by the system ser
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefine**. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 12100001 | Parameter invalid. |
| 12100002 | TokenId does not exist. |
| 12100003 | Permission does not exist. |
| 12100004 | The interface is not used together. |
**Example**
...
...
@@ -331,7 +407,7 @@ import privacyManager from '@ohos.privacyManager';
lettokenID=0;// You can use getApplicationInfo to obtain the access token ID.
| type | string | Yes | Event type to subscribe to. The value is **activeStateChange**, which indicates permission usage change event. |
| permissionNameList | Array<string> | No | List of permissions to be observed. If this parameter is left empty, the usage changes of all permissions are observed. |
| callback | Callback<[ActiveChangeResponse](#activechangeresponse)> | Yes| Callback invoked to return a change in permission usage.|
| type | string | Yes | Event type to subscribe to. The value is **'activeStateChange'**, which indicates the permission usage change event. |
| permissionNameList | Array<Permissions> | No | List of permissions to be observed. If this parameter is left empty, the usage changes of all permissions are observed. |
| callback | Callback<[ActiveChangeResponse](#activechangeresponse)> | Yes| Callback invoked to return a change in the permission usage.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 12100001 | Parameter invalid. |
| 12100004 | The interface is not used together. |
| 12100005 | The number of listeners exceeds the limit. |
| type | string | Yes | Event type to subscribe to. The value is **activeStateChange**, which indicates permission usage change event. |
| permissionNameList | Array<string> | No | List of permissions to be observed. If this parameter is left blank, the usage changes of all permissions are unsubscribed from. The value must be the same as that specified in **on()**.|
| type | string | Yes | Event type to subscribe to. The value is **'activeStateChange'**, which indicates the permission usage change event. |
| permissionNameList | Array<Permissions> | No | List of permissions to be observed. If this parameter is left blank, the usage changes of all permissions are unsubscribed from. The value must be the same as that specified in **on()**.|
| callback | Callback<[ActiveChangeResponse](#activechangeresponse)> | No| Callback for the permission usage change event.|
**Error codes**
For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
| ID| Error Message|
| -------- | -------- |
| 12100001 | Parameter invalid. |
| 12100004 | The interface is not used together. |
| permissionName | string | No | Name of the permission. |
| permissionName | Permissions | No | Name of the permission. |
| accessCount | number | No | Total number of times that the permission is accessed.|
| rejectCount | number | No | Total number of times that the access to the permission is rejected.|
| lastAccessTime | number | No | Last time when the permission was accessed, accurate to ms.|
| lastRejectTime | number | No | Last time when the access to the permission was rejected, accurate to ms.|
| lastAccessDuration | number | No | Last access duration, in ms.|
| accessRecords | Array<[UsedRecordDetail](#usedrecorddetail)> | No | Access records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided. |
| rejectRecords | Array<[UsedRecordDetail](#usedrecorddetail)> | No | Rejected records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided. |
| accessRecords | Array<[UsedRecordDetail](#usedrecorddetail)> | No | Successful access records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided. |
| rejectRecords | Array<[UsedRecordDetail](#usedrecorddetail)> | No | Rejected access records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided. |
## UsedRecordDetail
...
...
@@ -496,15 +585,15 @@ Represents the details of a single access record.
This error code is reported if an error occurs during JS parameter parsing. The possible causes are as follows:
1. The number of input parameters is insufficient.
2. The parameter type is incorrect.
Parameter invalid, message is ${messageInfo}.
### Solution
1. Add input parameters.
2. Correct parameter types.
**Possible Causes**
This error code is reported if an error occurs during parameter verification. The possible causes are as follows:
- The value of **tokenId** is **0**.
- The permission name is empty or exceeds 256 characters.
- The **flag** value in the permission authorization or revocation request is invalid.
- The input parameters specified for registering a listener are incorrect.
## 201 Permission denied.
**Solution**
### Error Message
Permission denied.${messageInfo}.
Correct the invalid parameter values.
### Possible Causes
This error code is reported if the application process that calls an API is not granted the required permission. The possible causes are as follows:
1. The application process is not granted the required permission.
2. The permission requires user authorization to take effect, but the application process does not obtain the user authorization.
### Solution
1. Check whether the application process is granted the required permission.
2. Check whether the application process has obtained the user authorization if the permission requires user authorization to take effect.
## 12100002 TokenId Does Not Exist
**Error Message**
## 12100001 Invalid Parameters
TokenId does not exist.
### Error Message
Parameter invalid, message is ${messageInfo}.
**Possible Causes**
### Possible Causes
This error code is reported if an error occurs during parameter verification. The possible causes are as follows:
1. The value of **tokenId** is **0**.
2. The specified permission name is empty or contains more than 256 characters.
3. The **flag** value in the permission authorization or revocation request is invalid.
4. The input parameters specified for registering a listener are incorrect.
- The specified **tokenId** does not exist.
- The process of the specified **tokenId** is not an application process.
### Solution
1. Correct the invalid parameter values.
**Solution**
Set **tokenId** correctly.
## 12100002 TokenId does not exist.
### Error Message
TokenId does not exist.
### Possible Causes
1. The specified **tokenId** does not exist.
2. The process corresponding to the specified **tokenId** is not an application process.
## 12100003 Permission Does Not Exist
### Solution
Set a correct **tokenId**, and make sure that the process corresponding to the specified **tokenId** is an application process.
**Error Message**
Permission does not exist.
## 12100003 Permission Not Exist
**Possible Causes**
### Error Message
Permission does not exist.
- The specified **permissionName** does not exist.
- The specified **permissionName** does not match the **tokenId** in the permission authorization or revocation scenario.
- The specified **permissionName** is not a sensitive permission that requires user authorization.
### Possible Causes
1. The specified **permissionName** does not exist.
2. The specified **permissionName** does not match the specified **tokenId** in the permission authorization or revocation scenario.
3. The specified **permissionName** is not a sensitive permission that requires user authorization.
**Solution**
### Solution
Set the **permissionName** parameter correctly. For details, see [permission-list](../../security/permission-list.md).
## 12100004 Listener APIs Not Used in Pairs
### Error Message
The listener interface is not used together.
**Error Message**
The interface is not used together.
**Possible Causes**
### Possible Causes
This error code is reported if listener APIs are not used in pairs. The possible causes are as follows:
1. The listener APIs that need to be used in pairs are repeatedly called.
2. The listener APIs that need to be used in pairs are independently called.
### Solution
**Solution**
1. Check whether the API needs to be used in pairs. That is, if an API is called to enable listening, an API with the same input parameters cannot be called unless an API is called to stop listening first.
2. Check whether the API needs to be used in pairs. That is, an API for disabling listening or unregistering a listener can only be called after the API for enabling listening or registering a listener is called.
## 12100005 Listener Overflow
### Error Message
**Error Message**
The number of listeners exceeds the limit.
### Possible Causes
**Possible Causes**
The number of listeners exceeds 200 (the upper limit).
### Solution
Abandon unused listeners in a timely manner.
**Solution**
Release unused listeners in a timely manner.
## 12100006 Permission Granting or Revocation Not Supported for the Specified Application
### Error Message
**Error Message**
The specified application does not support the permissions granted or ungranted as specified.
### Possible Causes
1. The specified **tokenId** is the identity of the remote device. Distributed granting and revocation are not yet supported.
**Possible Causes**
1. The specified **tokenId** is the identity of the remote device. Distributed permission granting and revocation are not yet supported.
2. The specified **tokenId** belongs to a sandbox application, which is not allowed to apply for the specified permission.
### Solution
**Solution**
1. Check whether the method of obtaining **tokenId** is correct.
2. Check whether the sandbox application works in restrictive mode. Most permissions cannot be granted to a sandbox application in restrictive mode.
## 12100007 System Services Not Working Properly
### Error Message
**Error Message**
Service is abnormal.
### Possible Causes
**Possible Causes**
This error code is reported if system services are not working properly. The possible causes are as follows:
1. The permission management service cannot be started properly.
2. An error occurs while reading or writing IPC data.
- The permission management service cannot start properly.
- The read or write of IPC data fails.
**Solution**
### Solution
System services do not work properly. Try again later or restart the device.