diff --git a/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md b/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md index 733fee0c5671f9e100191f8b23a54fd7b5edec67..faf338b504e33f90e71749eec565f177a4ff16b4 100644 --- a/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md +++ b/en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md @@ -3,7 +3,6 @@ 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. **Example** ```js -var AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); ``` ## AtManager @@ -39,9 +38,9 @@ Implements ability access control. ### checkAccessToken9+ -checkAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> +checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> -Checks whether an application has been granted the specified permission. This API uses a promise to return the result. +Checks whether an application has the specified permission. This API uses a promise to return the result. **System capability**: SystemCapability.Security.AccessToken @@ -49,8 +48,8 @@ Checks whether an application has been granted the specified permission. This AP | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | -| 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 verify.| +| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). | +| permissionName | Permissions | Yes | Permission to check.| **Return value** @@ -58,15 +57,23 @@ Checks whether an application has been granted the specified permission. This AP | :------------ | :---------------------------------- | | Promise<GrantStatus> | Promise used to return the permission grant state.| +**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 | + **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -let AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. try { - AtManager.checkAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => { + 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)}`); @@ -78,9 +85,9 @@ try { ### verifyAccessTokenSync9+ -verifyAccessTokenSync(tokenID: number, permissionName: string): GrantStatus +verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus -Checks whether an application has been granted the specified permission. This API synchronously returns the result. +Verifies whether an application has the specified permission. This API returns the result synchronously. **System capability**: SystemCapability.Security.AccessToken @@ -89,7 +96,7 @@ Checks whether an application has been granted the specified permission. This AP | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | | tokenID | number | Yes | Token ID of the application. | -| permissionName | string | Yes | Name of the permission to verify.| +| permissionName | Permissions | Yes | Name of the permission to verify.| **Return value** @@ -97,24 +104,32 @@ Checks whether an application has been granted the specified permission. This AP | :------------ | :---------------------------------- | | [GrantStatus](#grantstatus) | Permission grant state.| +**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 | + **Example** ```js -var AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; -let data = AtManager.verifyAccessTokenSync(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS"); +let data = atManager.verifyAccessTokenSync(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS"); console.log(`data->${JSON.stringify(data)}`); ``` ### grantUserGrantedPermission -grantUserGrantedPermission(tokenID: number, permissionName: string, permissionFlag: number): Promise<void> +grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlag: number): Promise<void> -Grants a user granted permission to an application. This API uses a promise to return the result. +Grants a user_grant permission to 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.GRANT_SENSITIVE_PERMISSIONS +**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -123,7 +138,7 @@ This is a system API. | Name | Type | Mandatory| Description | | --------- | ------------------- | ---- | ------------------------------------------------------------ | | 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. | **Return value** @@ -132,16 +147,28 @@ This is a system API. | :------------ | :---------------------------------- | | 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. | +| 12100007 | Service is abnormal. | + **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -let AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. let permissionFlag = 1; try { - AtManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag).then(() => { + atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag).then(() => { console.log('grantUserGrantedPermission success'); }).catch((err) => { console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); @@ -153,13 +180,13 @@ try { ### grantUserGrantedPermission -grantUserGrantedPermission(tokenID: number, permissionName: string, permissionFlag: number, callback: AsyncCallback<void>): void +grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlag: number, callback: AsyncCallback<void>): void -Grants a user granted permission to an application. This API uses an asynchronous callback to return the result. +Grants a user_grant permission to an application. This API uses an asynchronous callback to return the result. -This is a system API. +**System API**: This is a system API. -**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS +**Required permissions**: ohos.permission.GRANT_SENSITIVE_PERMISSIONS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -167,21 +194,32 @@ This is a system API. | Name | Type | Mandatory| Description | | --------- | ------------------- | ---- | ------------------------------------------------------------ | -| 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. | **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -var AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. let permissionFlag = 1; try { - AtManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (data, err) => { + atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (err, data) => { if (err) { console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`); } else { @@ -195,13 +233,13 @@ try { ### revokeUserGrantedPermission -revokeUserGrantedPermission(tokenID: number, permissionName: string, permissionFlag: number): Promise<void> +revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlag: number): Promise<void> -Revokes a user granted permission given to an application. This API uses a promise to return the result. +Revokes a user_grant permission from 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.REVOKE_SENSITIVE_PERMISSIONS +**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -209,8 +247,8 @@ This is a system API. | Name | Type | Mandatory| Description | | --------- | ------------------- | ---- | ------------------------------------------------------------ | -| 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. | **Return value** @@ -219,16 +257,28 @@ This is a system API. | :------------ | :---------------------------------- | | 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. | +| 12100007 | Service is abnormal. | + **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -let AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. let permissionFlag = 1; try { - AtManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag).then(() => { + atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag).then(() => { console.log('revokeUserGrantedPermission success'); }).catch((err) => { console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); @@ -240,13 +290,13 @@ try { ### revokeUserGrantedPermission -revokeUserGrantedPermission(tokenID: number, permissionName: string, permissionFlag: number, callback: AsyncCallback<void>): void +revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlag: number, callback: AsyncCallback<void>): void -Revokes a user granted permission given to an application. This API uses an asynchronous callback to return the result. +Revokes a user_grant permission from an application. This API uses an asynchronous callback to return the result. -This is a system API. +**System API**: This is a system API. -**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS +**Required permissions**: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -254,21 +304,32 @@ This is a system API. | Name | Type | Mandatory| Description | | --------- | ------------------- | ---- | ------------------------------------------------------------ | -| 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. | **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -var AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. let permissionFlag = 1; try { - AtManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (data, err) => { + atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlag, (err, data) => { if (err) { console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`); } else { @@ -282,13 +343,13 @@ try { ### getPermissionFlags -getPermissionFlags(tokenID: number, permissionName: string): Promise<number> +getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number> -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) **System capability**: SystemCapability.Security.AccessToken @@ -297,7 +358,7 @@ This is a system API. | Name | Type | Mandatory| Description | | --------- | ------------------- | ---- | ------------------------------------------------------------ | | 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 query.| +| permissionName | Permissions | Yes | Name of the permission to query.| **Return value** @@ -305,18 +366,30 @@ This is a system API. | :------------ | :---------------------------------- | | Promise<number> | Promise used to return the result.| +**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 operation is not allowd. Either the application is a sandbox or the tokenID is from a remote device. | +| 12100007 | Service is abnormal. | + **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -let AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. let permissionFlag = 1; try { - AtManager.getPermissionFlags(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => { + atManager.getPermissionFlags(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => { console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`); - }).catch((err) = > { + }).catch((err) => { console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`); }); } catch(err) { @@ -328,9 +401,9 @@ try { getVersion(): Promise<number> -Obtains the data version of the current permission management. This API uses a promise to return the result. +Obtains the data version of the permission management. This API uses a promise to return the result. -This is a system API. +**System API**: This is a system API. **System capability**: SystemCapability.Security.AccessToken @@ -343,8 +416,8 @@ This is a system API. **Example** ```js -var AtManager = abilityAccessCtrl.createAtManager(); -let promise = AtManager.getVersion(); +let atManager = abilityAccessCtrl.createAtManager(); +let promise = atManager.getVersion(); promise.then(data => { console.log(`promise: data->${JSON.stringify(data)}`); }); @@ -352,13 +425,13 @@ promise.then(data => { ### on9+ -on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionNameList: Array<string>, callback: Callback<PermissionStateChangeInfo>): void; +on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionNameList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void; -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. -This is a system API. +**System API**: This is a system API. -**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS +**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -367,10 +440,22 @@ This is a system API. | Name | Type | Mandatory| Description | | ------------------ | --------------------- | ---- | ------------------------------------------------------------ | | 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'; let atManager = abilityAccessCtrl.createAtManager(); let tokenIDList: Array = []; -let permissionNameList: Array = []; +let permissionNameList = []; try { atManager.on('permissionStateChange', tokenIDList, permissionNameList, (data) => { console.debug("receive permission state change, data:" + JSON.stringify(data)); @@ -390,13 +475,13 @@ try { ### off9+ -off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionNameList: Array<string>, callback?: Callback<PermissionStateChangeInfo>): void; +off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionNameList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void; -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. -This is a system API. +**System API**: This is a system API. -**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS +**Required permissions**: ohos.permission.GET_SENSITIVE_PERMISSIONS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -405,10 +490,21 @@ This is a system API. | Name | Type | Mandatory| Description | | ------------------ | --------------------- | ---- | ------------------------------------------------------------ | | 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'; let atManager = abilityAccessCtrl.createAtManager(); let tokenIDList: Array = []; -let permissionNameList: Array = []; +let permissionNameList = []; try { atManager.off('permissionStateChange', tokenIDList, permissionNameList); } catch(err) { @@ -424,15 +520,49 @@ try { } ``` +### verifyAccessToken9+ + +verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> + +Verifies whether an application has the specified permission. This API uses a promise to return the result. + +> **NOTE**
You are advised to use [checkAccessToken](#checkaccesstoken9). + +**System capability**: SystemCapability.Security.AccessToken + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------- | ---- | ------------------------------------------ | +| 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 verify. Only valid permission names are supported.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<GrantStatus> | Promise used to return the permission grant state.| + +**Example** + +```js +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; + +let atManager = abilityAccessCtrl.createAtManager(); +let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. +let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS"); +promise.then(data => { + console.log(`promise: data->${JSON.stringify(data)}`); +}); +``` + ### verifyAccessToken(deprecated) verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> -Checks whether an application has been granted the specified permission. This API uses a promise to return the result. +Verifies whether an application has the specified permission. This API uses a promise to return the result. -> **NOTE** -> -> This API is deprecated since API version 9. You are advised to use [checkAccessToken](#checkaccesstoken9) instead. +> NOTE
This API is deprecated since API version 9. You are advised to use [checkAccessToken](#checkaccesstoken9). **System capability**: SystemCapability.Security.AccessToken @@ -440,7 +570,7 @@ Checks whether an application has been granted the specified permission. This AP | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | -| tokenID | number | Yes | Token ID of the application. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md). | +| 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 verify.| **Return value** @@ -452,11 +582,11 @@ Checks whether an application has been granted the specified permission. This AP **Example** ```js -import privacyManager from '@ohos.abilityAccessCtrl'; +import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; -var AtManager = abilityAccessCtrl.createAtManager(); +let atManager = abilityAccessCtrl.createAtManager(); let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. -let promise = AtManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS"); +let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS"); promise.then(data => { console.log(`promise: data->${JSON.stringify(data)}`); }); @@ -468,7 +598,7 @@ Enumerates the permission grant states. **System capability**: SystemCapability.Security.AccessToken -| Name | Default Value| Description | +| Name | Value| Description | | ------------------ | ----- | ----------- | | PERMISSION_DENIED | -1 | Permission denied.| | PERMISSION_GRANTED | 0 | Permission granted.| @@ -481,7 +611,7 @@ Enumerates the operations that trigger permission grant state changes. **System capability**: SystemCapability.Security.AccessToken -| Name | Default Value| Description | +| Name | Value| Description | | ----------------------- | ------ | ----------------- | | PERMISSION_REVOKED_OPER | 0 | Operation to revoke the permission.| | PERMISSION_GRANTED_OPER | 1 | Operation to grant the permission.| @@ -492,10 +622,10 @@ Defines the detailed permission grant state change information. **System API**: This is a system API. - **System capability**: SystemCapability.Security.AccessToken +**System capability**: SystemCapability.Security.AccessToken | Name | Type | Readable| Writable| Description | | -------------- | ------------------------- | ---- | ---- | ------------------ | | change | [PermissionStateChangeType](#permissionstatechangetype9) | Yes | No | Operation that triggers the permission grant state change. | | tokenID | number | Yes | No | Token ID of the application whose permission grant state changes are subscribed.| -| permissionName | string | Yes | No | Name of the permission whose grant state is changed.| +| permissionName | Permissions | Yes | No | Name of the permission whose grant state is changed.| diff --git a/en/application-dev/reference/apis/js-apis-privacyManager.md b/en/application-dev/reference/apis/js-apis-privacyManager.md index 1f3f64ff1aaaa2b5267cdfc55632c46b986df74f..cf518ed93a2aea668985ae96031b12d48e284811 100644 --- a/en/application-dev/reference/apis/js-apis-privacyManager.md +++ b/en/application-dev/reference/apis/js-apis-privacyManager.md @@ -1,10 +1,10 @@ # Privacy Management -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'; ## privacyManager.addPermissionUsedRecord -addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number): Promise<void> +addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number): Promise<void> 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 | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | -| 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.| @@ -39,6 +39,15 @@ The permission usage record includes the application identity of the invoker, na | :------------ | :---------------------------------- | | 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 | Parameter invalid. | +| 12100002 | TokenId does not exist. | +| 12100003 | Permission does not exist. | + **Example** ```js @@ -58,10 +67,10 @@ try { ## privacyManager.addPermissionUsedRecord -addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number, callback: AsyncCallback<void>): void +addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number, callback: AsyncCallback<void>): void 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 | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | -| 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'; let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. try { - privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (data, err) => { + privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (err, data) => { if (err) { console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`); } else { @@ -116,7 +134,16 @@ Obtains historical permission usage records. This API uses a promise to return t | Type | Description | | :------------ | :---------------------------------- | -| Promise<[PermissionUsedResponse](#permissionusedresponse)> | Promise used to return the permission usage records obtained.| +| Promise<[PermissionUsedResponse](#permissionusedresponse)> | Promise used to return the permission usage records.| + +**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** @@ -159,7 +186,16 @@ Obtains historical permission usage records. This API uses an asynchronous callb | Name | Type | Mandatory| Description | | -------- | ------------------- | ---- | ------------------------------------------ | | request | [PermissionUsedRequest](#permissionusedrequest) | Yes| Request for querying permission usage records.| -| 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). +| ID| Error Message| +| -------- | -------- | +| 12100001 | Parameter invalid. | +| 12100002 | TokenId does not exist. | +| 12100003 | Permission does not exist. | **Example** @@ -191,9 +227,9 @@ try { ## privacyManager.startUsingPermission -startUsingPermission(tokenID: number, permissionName: string): Promise<void> +startUsingPermission(tokenID: number, permissionName: Permissions): Promise<void> -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 | Name | Type | Mandatory| Description | | -------------- | ------ | ---- | ------------------------------------ | -| tokenID | number | Yes | Application token ID of the invoker. You can obtain it from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| -| permissionName | string | Yes | Permission to use. | +| tokenID | number | Yes | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| +| permissionName | Permissions | Yes | Permission to use. | **Return value** @@ -212,6 +248,16 @@ Starts to record a permission usage event. This API is called by a system servic | ------------- | --------------------------------------- | | 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 | Parameter invalid. | +| 12100002 | TokenId does not exist. | +| 12100003 | Permission does not exist. | +| 12100004 | The interface is not used together. | + **Example** ```js @@ -231,9 +277,9 @@ try { ## privacyManager.startUsingPermission -startUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback<void>): void +startUsingPermission(tokenID: number, permissionName: Permissions, callback: AsyncCallback<void>): void -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 | Name | Type | Mandatory| Description | | -------------- | --------------------- | ---- | ------------------------------------ | -| tokenID | number | Yes | Application token ID of the invoker. You can obtain it from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| -| permissionName | string | Yes | Permission to use. | -| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| +| tokenID | number | Yes | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| +| permissionName | Permissions | Yes | Permission to use. | +| 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'; let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. try { - privacyManager.startUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (data, err) => { + privacyManager.startUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (err, data) => { if (err) { console.log(`startUsingPermission fail, err->${JSON.stringify(err)}`); } else { @@ -270,7 +326,7 @@ try { stopUsingPermission(tokenID: number, permissionName: string): Promise<void> -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 | Name | Type | Mandatory| Description | | -------------- | ------ | ---- | ------------------------------------ | -| tokenID | number | Yes | Application token ID of the invoker. You can obtain it from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| -| permissionName | string | Yes | Permission to use. | +| tokenID | number | Yes | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| +| permissionName | Permissions | Yes | Permission to use. | **Return value** @@ -289,6 +345,16 @@ Stops recording the permission usage event. This API is called by a system servi | ------------- | --------------------------------------- | | 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 | Parameter invalid. | +| 12100002 | TokenId does not exist. | +| 12100003 | Permission does not exist. | +| 12100004 | The interface is not used together. | + **Example** ```js @@ -308,9 +374,9 @@ try { ## privacyManager.stopUsingPermission -stopUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback<void>): void +stopUsingPermission(tokenID: number, permissionName: Permissions, callback: AsyncCallback<void>): void -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 | Name | Type | Mandatory| Description | | -------------- | --------------------- | ---- | ------------------------------------ | -| tokenID | number | Yes | Application token ID of the invoker. You can obtain it from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| -| permissionName | string | Yes | Permission to use. | -| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| +| tokenID | number | Yes | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).| +| permissionName | Permissions | Yes | Permission to use. | +| 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'; let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID. try { - privacyManager.stopUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (data, err) => { + privacyManager.stopUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (err, data) => { if (err) { console.log(`stopUsingPermission fail, err->${JSON.stringify(err)}`); } else { @@ -345,13 +421,11 @@ try { ## privacyManager.on -on(type: 'activeStateChange', permissionNameList: Array<string>, callback: Callback<ActiveChangeResponse>): void - -Subscribes to the changes in the usage of the specified permission list. This API uses a callback to return the result. +on(type: 'activeStateChange', permissionNameList: Array<Permissions>, callback: Callback<ActiveChangeResponse>): void -This is a system API. +Subscribes to the permission usage status changes of the specified permissions. -**Required permissions**: ohos.permission.PERMISSION_USED_STATS +**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -359,16 +433,25 @@ This is a system API. | Name | Type | Mandatory| Description | | ------------------ | --------------------- | ---- | ------------------------------------------------------------ | -| 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. | **Example** ```js import privacyManager from '@ohos.privacyManager'; -let permissionNameList: Array = []; +let permissionNameList: Array = []; try { atManager.on('activeStateChange', permissionNameList, (data) => { console.debug("receive permission state change, data:" + JSON.stringify(data)); @@ -380,13 +463,11 @@ try { ## privacyManager.off -off(type: 'activeStateChange', permissionNameList: Array<string>, callback?: Callback<ActiveChangeResponse>): void; - -Unsubscribes from the changes in the usage of the specified permission list. This API uses a callback to return the result. +off(type: 'activeStateChange', permissionNameList: Array<Permissions>, callback?: Callback<ActiveChangeResponse>): void; -This is a system API. +Unsubscribes from the permission usage status changes of the specified permissions. -**Required permissions**: ohos.permission.PERMISSION_USED_STATS +**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications) **System capability**: SystemCapability.Security.AccessToken @@ -394,16 +475,24 @@ This is a system API. | Name | Type | Mandatory| Description | | ------------------ | --------------------- | ---- | ------------------------------------------------------------ | -| 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. | + **Example** ```js import privacyManager from '@ohos.privacyManager'; -let permissionNameList: Array = []; +let permissionNameList: Array = []; try { privacyManager.off('activeStateChange', permissionNameList); }catch(err) { @@ -430,11 +519,11 @@ Represents the request for querying permission usage records. | Name | Type | Mandatory | Description | | -------- | -------------- | ---- | ---------------------------------------- | -| tokenId | number | No | Token ID of the application. | -| isRemote | boolean | No | Whether the token ID belongs to a remote device. The default value is **false**.| +| tokenId | number | No | Token ID of the application (invoker). | +| isRemote | boolean | No | Whether the token ID belongs to the application on a remote device. The default value is **false**.| | deviceId | string | No | ID of the device hosting the target application. | | bundleName | string | No | Bundle name of the target application.| -| permissionNames | Array<string> | No | Permissions to query. | +| permissionNames | Array<Permissions> | No | Permissions to query. | | beginTime | number | No | Start time of the query, in ms. The default value is **0**, indicating that no start time is set.| | endTime | number | No | End time of the query, in ms. The default value is **0**, indicating that no end time is set.| | flag | [PermissionUsageFlag](#permissionusageflag) | Yes | Query mode. The default value is **FLAG_PERMISSION_USAGE_SUMMARY**.| @@ -449,7 +538,7 @@ Represents the permission usage records of all applications. | -------- | -------------- | ---- | ---------------------------------------- | | beginTime | number | No | Start time of the query, in ms.| | endTime | number | No | End time of the query, in ms.| -| bundleRecords | Array<[BundleUsedRecord](#bundleusedrecord)> | No | Permission usage records obtained. | +| bundleRecords | Array<[BundleUsedRecord](#bundleusedrecord)> | No | Permission usage records. | ## BundleUsedRecord @@ -459,8 +548,8 @@ Represents the permission access records of an application. | Name | Type | Mandatory | Description | | -------- | -------------- | ---- | ---------------------------------------- | -| tokenId | number | No | Token ID of the application. | -| isRemote | boolean | No | Whether the token ID belongs to a remote device. The default value is **false**.| +| tokenId | number | No | Token ID of the application (invoker). | +| isRemote | boolean | No | Whether the token ID belongs to the application on a remote device. The default value is **false**.| | deviceId | string | No | ID of the device hosting the target application. | | bundleName | string | No | Bundle name of the target application.| | permissionRecords | Array<[PermissionUsedRecord](#permissionusedrecord)> | No | Permission usage records of the target application. | @@ -473,14 +562,14 @@ Represents the usage records of a permission. | Name | Type | Mandatory | Description | | -------- | -------------- | ---- | ---------------------------------------- | -| 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. ## PermissionActiveStatus -Enumerates of permission usage statuses. +Enumerates the permission usage statuses. **System capability**: SystemCapability.Security.AccessToken | Name | Default Value| Description | | ------------------------- | ------ | ---------------- | | PERM_INACTIVE | 0 | The permission is not used. | -| PERM_ACTIVE_IN_FOREGROUND | 1 | The permission is being used in the foreground.| -| PERM_ACTIVE_IN_BACKGROUND | 2 | The permission is being used in the background.| +| PERM_ACTIVE_IN_FOREGROUND | 1 | The permission is being used by an application running in the foreground.| +| PERM_ACTIVE_IN_BACKGROUND | 2 | The permission is being used by an application running in the background.| ## ActiveChangeResponse @@ -514,7 +603,7 @@ Defines the detailed permission usage information. | Name | Type | Readable| Writable| Description | | -------------- | ---------------------- | ---- | ---- | --------------------- | -| tokenId | number | Yes | No | Token ID of the application that applies for the permission. | -| permissionName | string | Yes | No | Name of the permission.| -| deviceId | string | Yes | No | Device number. | +| tokenId | number | Yes | No | Token ID of the application. | +| permissionName | Permissions | Yes | No | Name of the permission.| +| deviceId | string | Yes | No | Device ID. | | activeStatus | [PermissionActiveStatus](#permissionactivestatus) | Yes | No | Permission usage status. | diff --git a/en/application-dev/reference/errorcodes/errorcode-Access-token.md b/en/application-dev/reference/errorcodes/errorcode-Access-token.md deleted file mode 100644 index 306ad41da505db3a42a8d6668ce00b47c7e3f60e..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/errorcodes/errorcode-Access-token.md +++ /dev/null @@ -1,140 +0,0 @@ -# Access Token Error Codes - -## 401 Parameter Error - -### Error Message -Parameter error.${messageInfo}. - -### Possible Causes -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. - -### Solution -1. Add input parameters. -2. Correct parameter types. - - -## 201 Permission denied. - -### Error Message -Permission denied.${messageInfo}. - -### 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. - - -## 12100001 Invalid Parameters - -### Error Message -Parameter invalid, message is ${messageInfo}. - -### 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. - -### Solution -1. Correct the invalid parameter values. - - -## 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. - -### Solution -Set a correct **tokenId**, and make sure that the process corresponding to the specified **tokenId** is an application process. - - -## 12100003 Permission Not Exist - -### Error Message -Permission does not exist. - -### 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 -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. - -### 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 -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 -The number of listeners exceeds the limit. - -### Possible Causes -The number of listeners exceeds 200 (the upper limit). - -### Solution -Abandon unused listeners in a timely manner. - - -## 12100006 Permission Granting or Revocation Not Supported for the Specified Application - -### 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. -2. The specified **tokenId** belongs to a sandbox application, which is not allowed to apply for the specified permission. - -### 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 -Service is abnormal. - -### 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. - -### Solution -System services do not work properly. Try again later or restart the device. - - -## 12100008 Out of Memory - -### Error Message -Out of memory. - -### Possible Causes -The system memory is insufficient. - -### Solution -Try again later or restart the device. diff --git a/en/application-dev/reference/errorcodes/errorcode-access-token.md b/en/application-dev/reference/errorcodes/errorcode-access-token.md new file mode 100644 index 0000000000000000000000000000000000000000..da0cb07f0e9947fbe6d86796a72466a926041bb4 --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-access-token.md @@ -0,0 +1,134 @@ +# Ability Access Control Error Codes + +## 12100001 Invalid Parameters + +**Error Message** + +Parameter invalid, message is ${messageInfo}. + +**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. + +**Solution** + +Correct the invalid parameter values. + + +## 12100002 TokenId Does Not Exist + +**Error Message** + +TokenId does not exist. + +**Possible Causes** + +- The specified **tokenId** does not exist. +- The process of the specified **tokenId** is not an application process. + +**Solution** + +Set **tokenId** correctly. + + +## 12100003 Permission Does Not Exist + +**Error Message** + +Permission does not exist. + +**Possible Causes** + +- 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. + +**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 interface is not used together. + +**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** + +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** + +The number of listeners exceeds the limit. + +**Possible Causes** + +The number of listeners exceeds 200 (the upper limit). + +**Solution** + +Release unused listeners in a timely manner. + + +## 12100006 Permission Granting or Revocation Not Supported for the Specified Application + +**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 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** + +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** + +Service is abnormal. + +**Possible Causes** + +This error code is reported if system services are not working properly. The possible causes are as follows: +- The permission management service cannot start properly. +- The read or write of IPC data fails. + +**Solution** + +System services do not work properly. Try again later or restart the device. + + +## 12100008 Out of Memory + +**Error Message** + +Out of memory. + +**Possible Causes** + +The system memory is insufficient. + +**Solution** + +Try again later or restart the device.