!10539 [翻译完成】#I5RGVF

Merge pull request !10539 from Annie_wang/PR9567

en/application-dev/reference/apis/js-apis-privacyManager.md

@@ -3,7 +3,6 @@
 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.
 
@@ -16,7 +15,7 @@ import privacyManager from '@ohos.privacyManager';
 
 ## privacyManager.addPermissionUsedRecord
 
-addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number): Promise<number>
+addPermissionUsedRecord(tokenID: number, permissionName: string, 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.
@@ -29,7 +28,7 @@ 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.             |
+| 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.|
 | successCount | number | Yes  | Number of successful accesses.|
 | failCount | number | Yes  | Number of failed accesses.|
@@ -38,20 +37,28 @@ The permission usage record includes the application identity of the invoker, na
 
 | Type         | Description                               |
 | :------------ | :---------------------------------- |
-| Promise<number> | Promise used to return the result. If **0** is returned, the record is added successfully. If **-1** is returned, the record fails to be added.|
+| Promise<void> | Promise that returns no value.|
 
 **Example**
 
 ```js
-var tokenID = appInfo.accessTokenId; // accessTokenId can be obtained by using getApplicationInfo().
-privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0).then(data => {
-    console.log(`promise: data->${JSON.stringify(data)}`);
-});
+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).then(() => {
+        console.log('addPermissionUsedRecord success');
+    }).catch((err) => {
+        console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
 ```
 
 ## privacyManager.addPermissionUsedRecord
 
-addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number, callback: AsyncCallback<number>): void
+addPermissionUsedRecord(tokenID: number, permissionName: string, 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.
@@ -64,19 +71,29 @@ 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.             |
+| 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.|
 | successCount | number | Yes  | Number of successful accesses.|
 | failCount | number | Yes  | Number of failed accesses.|
-| callback | AsyncCallback<number> | Yes  | Callback used to return the result. If **0** is returned, the record is added successfully. If **-1** is returned, the record fails to be added.|
+| callback | AsyncCallback<void> | Yes  | Callback invoked to return the result.|
 
 **Example**
 
 ```js
-var tokenID = appInfo.accessTokenId; // accessTokenId can be obtained by using getApplicationInfo().
-privacyManager.privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (err, data) => {
-    console.log(`callback: data->${JSON.stringify(data)}`);
-});
+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) => {
+        if (err) {
+            console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
+        } else {
+            console.log('addPermissionUsedRecord success');
+        }
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
 ```
 
 ## privacyManager.getPermissionUsedRecords
@@ -104,19 +121,27 @@ Obtains historical permission usage records. This API uses a promise to return t
 **Example**
 
 ```js
+import privacyManager from '@ohos.privacyManager';
+
 let request = {
     "tokenId": 1,
-    "isRemote": 1,
+    "isRemote": false,
     "deviceId": "device",
     "bundleName": "bundle",
-    "permissionNames": 1,
+    "permissionNames": [],
     "beginTime": 0,
     "endTime": 1,
     "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
 };
-privacyManager.getPermissionUsedRecords(request).then(data => {
-    console.log(`promise: data->${JSON.stringify(data)}`);
-});
+try {
+    privacyManager.getPermissionUsedRecords(request).then((data) => {
+        console.log(`getPermissionUsedRecords success, data->${JSON.stringify(data)}`);
+    }).catch((err) => {
+        console.log(`getPermissionUsedRecords fail, err->${JSON.stringify(err)}`);
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
 ```
 
 ## privacyManager.getPermissionUsedRecords
@@ -134,24 +159,256 @@ 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 used to return the permission usage records obtained.|
+| callback | AsyncCallback<[PermissionUsedResponse](#permissionusedresponse)> | Yes| Callback invoked to return the permission usage records obtained.|
 
 **Example**
 
 ```js
+import privacyManager from '@ohos.privacyManager';
+
 let request = {
     "tokenId": 1,
-    "isRemote": 1,
+    "isRemote": false,
     "deviceId": "device",
     "bundleName": "bundle",
-    "permissionNames": 1,
+    "permissionNames": [],
     "beginTime": 0,
     "endTime": 1,
     "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
 };
-privacyManager.getPermissionUsedRecords(request, (err, data) => {
-    console.log(`promise: data->${JSON.stringify(data)}`);
-});
+try {
+    privacyManager.getPermissionUsedRecords(request, (err, data) => {
+        if (err) {
+            console.log(`getPermissionUsedRecords fail, err->${JSON.stringify(err)}`);
+        } else {
+            console.log(`getPermissionUsedRecords success, data->${JSON.stringify(data)}`);
+        }
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+```
+
+## privacyManager.startUsingPermission
+
+startUsingPermission(tokenID: number, permissionName: string): Promise&lt;void&gt;
+
+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.
+
+**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
+
+**System capability**: SystemCapability.Security.AccessToken
+
+**Parameters**
+
+| 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.                    |
+
+**Return value**
+
+| Type         | Description                                   |
+| ------------- | --------------------------------------- |
+| Promise&lt;void&gt; | Promise that returns no value.|
+
+**Example**
+
+```js
+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").then(() => {
+        console.log('startUsingPermission success');
+    }).catch((err) => {
+        console.log(`startUsingPermission fail, err->${JSON.stringify(err)}`);
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+```
+
+## privacyManager.startUsingPermission
+
+startUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback&lt;void&gt;): 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.
+
+**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
+
+**System capability**: SystemCapability.Security.AccessToken
+
+**Parameters**
+
+| 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&lt;void&gt; | Yes  | Callback invoked to return the result.|
+
+**Example**
+
+```js
+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) => {
+        if (err) {
+            console.log(`startUsingPermission fail, err->${JSON.stringify(err)}`);
+        } else {
+            console.log('startUsingPermission success');
+        }
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+```
+
+## privacyManager.stopUsingPermission
+
+stopUsingPermission(tokenID: number, permissionName: string): Promise&lt;void&gt;
+
+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.
+
+**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
+
+**System capability**: SystemCapability.Security.AccessToken
+
+**Parameters**
+
+| 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.                    |
+
+**Return value**
+
+| Type         | Description                                   |
+| ------------- | --------------------------------------- |
+| Promise&lt;void&gt; | Promise that returns no value.|
+
+**Example**
+
+```js
+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").then(() => {
+        console.log('stopUsingPermission success');
+    }).catch((err) => {
+        console.log(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+```
+
+## privacyManager.stopUsingPermission
+
+stopUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback&lt;void&gt;): 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.
+
+**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
+
+**System capability**: SystemCapability.Security.AccessToken
+
+**Parameters**
+
+| 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&lt;void&gt; | Yes  | Callback invoked to return the result.|
+
+**Example**
+
+```js
+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) => {
+        if (err) {
+            console.log(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
+        } else {
+            console.log('stopUsingPermission success');
+        }
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+```
+
+## privacyManager.on
+
+on(type: 'activeStateChange', permissionNameList: Array&lt;string&gt;, callback: Callback&lt;ActiveChangeResponse&gt;): void
+
+Subscribes to the changes in the usage of the specified permission list. This API uses a callback to return the result.
+
+This is a system API.
+
+**Required permissions**: ohos.permission.PERMISSION_USED_STATS
+
+**System capability**: SystemCapability.Security.AccessToken
+
+**Parameters**
+
+| Name            | Type                  | Mandatory| Description                                                         |
+| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
+| type               | string                | Yes  | Event type to subscribe to. The value is **activeStateChange**, which indicates permission usage change event.  |
+| permissionNameList | Array&lt;string&gt;   | No  | List of permissions to be observed. If this parameter is left empty, the usage changes of all permissions are observed.          |
+| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse)&gt; | Yes| Callback invoked to return a change in permission usage.|
+
+**Example**
+
+```js
+import privacyManager from '@ohos.privacyManager';
+
+let permissionNameList: Array<string> = [];
+try {
+    atManager.on('activeStateChange', permissionNameList, (data) => {
+        console.debug("receive permission state change, data:" + JSON.stringify(data));
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+```
+
+## privacyManager.off
+
+off(type: 'activeStateChange', permissionNameList: Array&lt;string&gt;, callback?: Callback&lt;ActiveChangeResponse&gt;): void;
+
+Unsubscribes from the changes in the usage of the specified permission list. This API uses a callback to return the result.
+
+This is a system API.
+
+**Required permissions**: ohos.permission.PERMISSION_USED_STATS
+
+**System capability**: SystemCapability.Security.AccessToken
+
+**Parameters**
+
+| Name            | Type                  | Mandatory| Description                                                         |
+| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
+| type               | string                | Yes  | Event type to subscribe to. The value is **activeStateChange**, which indicates permission usage change event.  |
+| permissionNameList | Array&lt;string&gt;   | 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&lt;[ActiveChangeResponse](#activechangeresponse)&gt; | No| Callback for the permission usage change event.|
+
+**Example**
+
+```js
+import privacyManager from '@ohos.privacyManager';
+
+let permissionNameList: Array<string> = [];
+try {
+    privacyManager.off('activeStateChange', permissionNameList);
+}catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
 ```
 
 ## PermissionUsageFlag
@@ -236,3 +493,28 @@ Represents the details of a single access record.
 | status  | number         | No   | Access status.                                |
 | timestamp | number         | No   | Access timestamp, in ms.|
 | accessDuration  | number         | No   | Access duration, in ms.                                |
+
+## PermissionActiveStatus
+
+Enumerates of 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.|
+
+## ActiveChangeResponse
+
+Defines the detailed permission usage information.
+
+ **System capability**: SystemCapability.Security.AccessToken
+
+| 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.                |
+| activeStatus   | [PermissionActiveStatus](#permissionactivestatus) | Yes  | No  | Permission usage status.       |