!9124 添加atm与privacy新增接口的描述

Merge pull request !9124 from zhouyan/zy_privacy

zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md

@@ -282,13 +282,113 @@ promise.then(data => {
 });
 ```
 
+### on<sup>9+</sup>
+
+on(type: 'permissionStateChange', tokenIDList: Array&lt;number&gt;, permissionNameList: Array&lt;string&gt;, callback: Callback&lt;PermissionStateChangeInfo&gt;): void;
+
+订阅指定tokenId列表与权限列表的权限状态变更事件，使用callback回调异步返回结果。
+
+此接口为系统接口。
+
+**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名             | 类型                   | 必填 | 说明                                                          |
+| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
+| type               | string                | 是   | 订阅事件类型，固定为'permissionStateChange'，权限状态变更事件。  |
+| tokenIDList        | Array&lt;number&gt;   | 否   | 订阅的tokenId列表，为空时表示订阅所有的应用的权限状态变化。        |
+| permissionNameList | Array&lt;string&gt;   | 否   | 订阅的权限名列表，为空时表示订阅所有的权限状态变化。               |
+| callback | Callback&lt;[PermissionStateChangeInfo](#permissionstatechangeinfo9)&gt; | 是 | 订阅指定tokenId与指定权限名状态变更事件的回调。|
+
+**示例：**
+
+```js
+import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+
+function OnPermissionStateChanged(data){
+    console.debug("receive permission state change, data:" + JSON.stringify(data));
+}
+let atManager = abilityAccessCtrl.createAtManager();
+let type: 'permissionStateChange' = 'permissionStateChange';
+let tokenIDList: Array&lt;number&gt; = [];
+let permissionNameList: Array&lt;string&gt; = [];
+try{
+    atManager.on(type, tokenIDList, permissionNameList, OnPermissionStateChanged);
+}
+catch(err){
+    console.error("on err:" + JSON.stringify(err));
+}
+```
+
+### off<sup>9+</sup>
+
+off(type: 'permissionStateChange', tokenIDList: Array&lt;number&gt;, permissionNameList: Array&lt;string&gt;, callback?: Callback&lt;PermissionStateChangeInfo&gt;): void;
+
+取消订阅指定tokenId列表与权限列表的权限状态变更事件，使用callback回调异步返回结果。
+
+此接口为系统接口。
+
+**需要权限：** ohos.permission.GET_SENSITIVE_PERMISSIONS
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名             | 类型                   | 必填 | 说明                                                          |
+| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
+| type               | string                | 是   | 订阅事件类型，固定为'permissionStateChange'，权限状态变更事件。  |
+| tokenIDList        | Array&lt;number&gt;   | 否   | 订阅的tokenId列表，为空时表示订阅所有的应用的权限状态变化，必须与on的输入一致。 |
+| permissionNameList | Array&lt;string&gt;   | 否   | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，必须与on的输入一致。 |
+| callback | Callback&lt;[PermissionStateChangeInfo](#permissionstatechangeinfo9)&gt; | 否 | 取消订阅指定tokenId与指定权限名状态变更事件的回调。|
+
+**示例：**
+
+```js
+import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+
+let atManager = abilityAccessCtrl.createAtManager();
+let type: 'permissionStateChange' = 'permissionStateChange';
+let tokenIDList: Array&lt;number&gt; = [];
+let permissionNameList: Array&lt;string&gt; = [];
+try{
+    atManager.off(type, tokenIDList, permissionNameList);
+}
+catch(err){
+    console.error("off err:" + JSON.stringify(err));
+}
+```
+
 ### GrantStatus
 
 表示授权状态的枚举。
 
-**系统能力：** 以下各项对应的系统能力均为SystemCapability.Security.AccessToken
+**系统能力：** SystemCapability.Security.AccessToken
+
+| 名称               | 默认值 | 描述        |
+| ------------------ | ----- | ----------- |
+| PERMISSION_DENIED  | -1    | 表示未授权。 |
+| PERMISSION_GRANTED | 0     | 表示已授权。 |
+
+### PermissionStateChangeType<sup>9+</sup>
+
+表示权限状态变化操作类型的枚举。
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+| 名称                     | 默认值 | 描述              |
+| ----------------------- | ------ | ----------------- |
+| PERMISSION_REVOKED_OPER | 0      | 表示权限取消操作。 |
+| PERMISSION_GRANTED      | 1      | 表示权限授予操作。 |
+
+### PermissionStateChangeInfo<sup>9+</sup>
+
+ **系统能力:** SystemCapability.Security.AccessToken
 
-| 名称                          | 默认值                  | 描述                    |
-| ----------------------------- | ---------------------- | -----------------------  |
-| PERMISSION_DENIED             | -1                     | 表示未授权。             |
-| PERMISSION_GRANTED            | 0                      | 表示已授权。             |
+| 名称           | 类型                       | 可读 | 可写 | 说明                |
+| -------------- | ------------------------- | ---- | ---- | ------------------ |
+| change         | [PermissionStateChangeType](#permissionstatechangetype9) | 是   | 否   | 权限变化类型        |
+| tokenID        | number                    | 是   | 否   | 调用方的应用身份标识 |
+| permissionName | string                    | 是   | 否   | 状态发生变化的权限名 |

zh-cn/application-dev/reference/apis/js-apis-privacyManager.md

@@ -153,6 +153,237 @@ privacyManager.getPermissionUsedRecords(request, (err, data) => {
 });
 ```
 
+## privacyManager.startUsingPermission<sup>9+</sup>
+
+startUsingPermission(tokenID: number, permissionName: string): Promise&lt;number&gt;
+
+应用开始使用某项权限，可监听应用在前后台使用权限，并将使用权限的记录落盘，由系统服务调用。
+
+**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名          | 类型   | 必填 | 说明                                  |
+| -------------- | ------ | ---- | ------------------------------------ |
+| tokenID        | number | 是   | 调用方的应用身份标识，获取方法参照示例。 |
+| permissionName | string | 是   | 需要使用的权限名。                     |
+
+**返回值：**
+
+| 类型          | 说明                                    |
+| ------------- | --------------------------------------- |
+| Promise&lt;number&gt; | Promise对象。返回开始使用权限的结果。|
+
+**示例：**
+
+```js
+import bundle from '@ohos.bundle';
+import privacyManager from '@ohos.privacyManager';
+
+let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
+let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function
+
+let tokenID = appInfo.accessTokenId;
+let permissionName = "ohos.permission.CAMERA";
+privacyManager.startUsingPermission(tokenID, permissionName).then(data => {
+    console.log(`promise: data->${JSON.stringify(data)}`);
+}).catch(err => {
+    console.log(`Error: err->${JSON.stringify(err)}`);
+});
+```
+
+## privacyManager.startUsingPermission<sup>9+</sup>
+
+startUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback&lt;number&gt;): void
+
+应用开始使用某项权限，可监听应用在前后台使用权限，并将使用权限的记录落盘，由系统服务调用。
+
+**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名          | 类型                  | 必填 | 说明                                  |
+| -------------- | --------------------- | ---- | ------------------------------------ |
+| tokenID        | number                | 是   | 调用方的应用身份标识，获取方法参照示例。 |
+| permissionName | string                | 是   | 需要使用的权限名。                     |
+| callback       | AsyncCallback&lt;number&gt; | 是   | 异步回调，返回开始使用权限的结果。 |
+
+**示例：**
+
+```js
+import bundle from '@ohos.bundle';
+import privacyManager from '@ohos.privacyManager';
+
+let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
+let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function
+
+let tokenID = appInfo.accessTokenId;
+let permissionName = "ohos.permission.CAMERA";
+privacyManager.startUsingPermission(tokenID, permissionName, (err, data)=> {
+    if (err) {
+        console.log(`Error: err->${JSON.stringify(err)}`);
+    } else {
+        console.log(`promise: data->${JSON.stringify(data)}`);
+    }
+});
+```
+
+## privacyManager.stopUsingPermission<sup>9+</sup>
+
+stopUsingPermission(tokenID: number, permissionName: string): Promise&lt;number&gt;
+
+应用停止使用某项权限，与Start对应，由系统服务调用。
+
+**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名          | 类型   | 必填 | 说明                                  |
+| -------------- | ------ | ---- | ------------------------------------ |
+| tokenID        | number | 是   | 调用方的应用身份标识，获取方法参照示例。 |
+| permissionName | string | 是   | 需要使用的权限名。                     |
+
+**返回值：**
+
+| 类型          | 说明                                    |
+| ------------- | --------------------------------------- |
+| Promise&lt;number&gt; | Promise对象。返回停止使用权限的结果。|
+
+**示例：**
+
+```js
+import bundle from '@ohos.bundle';
+import privacyManager from '@ohos.privacyManager';
+
+let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
+let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function
+
+let tokenID = appInfo.accessTokenId;
+let permissionName = "ohos.permission.CAMERA";
+privacyManager.stopUsingPermission(tokenID, permissionName).then(data => {
+    console.log(`promise: data->${JSON.stringify(data)}`);
+}).catch(err => {
+    console.log(`Error: err->${JSON.stringify(err)}`);
+});
+```
+
+## privacyManager.stopUsingPermission<sup>9+</sup>
+
+stopUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback&lt;number&gt;): void
+
+应用停止使用某项权限，与Start对应，由系统服务调用。
+
+**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名          | 类型                  | 必填 | 说明                                  |
+| -------------- | --------------------- | ---- | ------------------------------------ |
+| tokenID        | number                | 是   | 调用方的应用身份标识，获取方法参照示例。 |
+| permissionName | string                | 是   | 需要使用的权限名。                      |
+| callback       | AsyncCallback&lt;number&gt; | 是   | 异步回调，返回停止使用权限的结果。 |
+
+**示例：**
+
+```js
+import bundle from '@ohos.bundle';
+import privacyManager from '@ohos.privacyManager';
+
+let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
+let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function
+
+let tokenID = appInfo.accessTokenId;
+let permissionName = "ohos.permission.CAMERA";
+privacyManager.privacyManager.stopUsingPermission(tokenID, permissionName, (err, data)=> {
+    if (err) {
+        console.log(`Error: err->${JSON.stringify(err)}`);
+    } else {
+        console.log(`promise: data->${JSON.stringify(data)}`);
+    }
+});
+```
+
+## privacyManager.on<sup>9+</sup>
+
+on(type: 'activeStateChange', permissionNameList: Array&lt;string&gt;, callback: Callback&lt;ActiveChangeResponse&gt;): void
+
+订阅指定权限列表的权限使用状态变更事件，使用callback回调异步返回结果。
+
+此接口为系统接口。
+
+**需要权限：** ohos.permission.PERMISSION_USED_STATS
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名             | 类型                   | 必填 | 说明                                                          |
+| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
+| type               | string                | 是   | 订阅事件类型，固定为'activeStateChange'，权限使用状态变更事件。   |
+| permissionNameList | Array&lt;string&gt;   | 否   | 订阅的权限名列表，为空时表示订阅所有的权限使用状态变化。           |
+| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse9)&gt; | 是 | 订阅指定权限使用状态变更事件的回调。 |
+
+**示例：**
+
+```js
+import privacyManager from '@ohos.privacyManager';
+
+function OnPermissionUseStateChanged(data){
+    console.debug("receive permission state change, data:" + JSON.stringify(data));
+}
+let type: 'activeStateChange' = 'activeStateChange';
+let permissionNameList: Array&lt;string&gt; = [];
+try{
+    privacyManager.on(type, permissionNameList, OnPermissionUseStateChanged);
+}
+catch(err){
+    console.error("on err:" + JSON.stringify(err));
+}
+```
+
+## privacyManager.off<sup>9+</sup>
+
+off(type: 'activeStateChange', permissionNameList: Array&lt;string&gt;, callback?: Callback&lt;ActiveChangeResponse&gt;): void;
+
+取消订阅指定权限列表的权限使用状态变更事件，使用callback回调异步返回结果。
+
+此接口为系统接口。
+
+**需要权限：** ohos.permission.PERMISSION_USED_STATS
+
+**系统能力：** SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名             | 类型                   | 必填 | 说明                                                          |
+| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
+| type               | string                | 是   | 订阅事件类型，固定为'activeStateChange'，权限使用状态变更事件。   |
+| permissionNameList | Array&lt;string&gt;   | 否   | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，必须与on的输入一致。 |
+| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse9)&gt; | 否 | 取消订阅指定tokenId与指定权限名状态变更事件的回调。|
+
+**示例：**
+
+```js
+import privacyManager from '@ohos.privacyManager';
+
+let type: 'activeStateChange' = 'activeStateChange';
+let permissionNameList: Array&lt;string&gt; = [];
+try{
+    privacyManager.off(type, permissionNameList);
+}
+catch(err){
+    console.error("off err:" + JSON.stringify(err));
+}
+```
+
 ## PermissionUsageFlag
 
 使用记录的查询方式的枚举。
@@ -235,3 +466,26 @@ privacyManager.getPermissionUsedRecords(request, (err, data) => {
 | status  | number         | 否    | 访问状态。                                 |
 | timestamp | number         | 否    | 访问时的时间戳，单位：ms。 |
 | accessDuration  | number         | 否    | 访问时长，单位：ms。                                 |
+
+## PermissionActiveStatus<sup>9+</sup>
+
+表示权限使用状态类型的枚举。
+
+**系统能力：** 以下各项对应的系统能力均为SystemCapability.Security.AccessToken
+
+| 名称                      | 默认值 | 描述              |
+| ------------------------- | ------ | ---------------- |
+| PERM_INACTIVE             | 0      | 表示未使用权限。   |
+| PERM_ACTIVE_IN_FOREGROUND | 1      | 表示前台使用权限。 |
+| PERM_ACTIVE_IN_BACKGROUND | 2      | 表示后台使用权限。 |
+
+## ActiveChangeResponse<sup>9+</sup>
+
+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.Security.AccessToken
+
+| 名称           | 类型                    | 可读 | 可写 | 说明                   |
+| -------------- | ---------------------- | ---- | ---- | --------------------- |
+| tokenId        | number                 | 是   | 否   | 调用方的应用身份标识    |
+| permissionName | string                 | 是   | 否   | 使用状态发生变化的权限名 |
+| deviceId       | string                 | 是   | 否   | 设备号                 |
+| activeStatus   | [PermissionActiveStatus](#permissionactivestatus9) | 是   | 否   | 权限使用状态类型        |