From 62936f9912d967c190bec308cf2e9154644ea1b9 Mon Sep 17 00:00:00 2001 From: xujie Date: Sun, 9 Jul 2023 21:51:56 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E7=BD=91=E7=BB=9C?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E7=AD=96=E7=95=A5md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: xujie --- .../connectivity/net-policy-management.md | 362 ++++++++++++++++++ 1 file changed, 362 insertions(+) create mode 100644 zh-cn/application-dev/connectivity/net-policy-management.md diff --git a/zh-cn/application-dev/connectivity/net-policy-management.md b/zh-cn/application-dev/connectivity/net-policy-management.md new file mode 100644 index 00000000000..f78c0233449 --- /dev/null +++ b/zh-cn/application-dev/connectivity/net-policy-management.md @@ -0,0 +1,362 @@ +# 网络策略管理部件 + +## 简介 + +网络策略管理提供一些限制网络的基础能力，包括蜂窝网络策略、休眠/省电模式策略、后台网络策略、重置网络策略等功能。 + +> **说明：** +> 为了保证应用的运行效率，大部分API调用都是异步的，对于异步调用的API均提供了callback和Promise两种方式，以下示例均采用callback函数，更多方式可以查阅[API参考](../reference/apis/js-apis-net-policy.md)。 + +## 基本概念 + +- 休眠模式：设备在不需要工作的时候把一些部件、外设关掉(进入低功耗模式)，并限制部分应用对网络的访问。 +- 省电模式：省电模式是系统里的一个开关，开启后会降低设备的性能，并限制部分应用对网络的访问。 +- 省流量模式：即后台网络策略，对处于后台的使用计量网络的应用进行限制。 +- 蜂窝网络：移动通信网络。 +- 计量网络：设置了流量配额的电话卡网络、Wlan网络以及以太网。 + +## 约束 + +- 开发语言：C++ JS +- 系统：linux内核 +- 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 场景介绍 + +网络策略管理的典型场景有： + +- 设置计量网络配额/获取已经设置的计量网络策略 +- 后台网络限制开关/获取后台网络限制状态/获取指定uid在后台状态下能否访问网络 +- 设定指定uid访问计量网络的策略/获取指定uid访问计量网络的策略/获取设置了对应策略的uids +- 重置网络策略 +- 判断uid能否访问计量/非计量网络 +- 将对应uid从休眠白名单里添加、移除/获取休眠模式的白名单列表 +- 将对应uid从省电白名单里添加、移除/获取省电模式的白名单列表 +- 更新网络提醒策略 + +以下分别介绍具体开发方式。 + +## 接口说明 + +完整的JS API说明以及实例代码请参考：[网络策略管理](../reference/apis/js-apis-net-policy.md)。 + +| 类型 | 接口 | 功能说明 | +| ---- | ---- | ---- | +| ohos.net.policy | function setBackgroundPolicy(isAllowed: boolean, callback: AsyncCallback\): void |设置后台网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function isBackgroundAllowed(callback: AsyncCallback\): void; |获取后台网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function setPolicyByUid(uid: number, policy: NetUidPolicy, callback: AsyncCallback\): void; |设置对应uid应用的访问计量网络的策略，使用callback方式作为异步方法 | +| ohos.net.policy | function getPolicyByUid(uid: number, callback: AsyncCallback\): void;| 通过应用uid获取策略，使用callback方式作为异步方法 | +| ohos.net.policy | function getUidsByPolicy(policy: NetUidPolicy, callback: AsyncCallback\>): void; | 通过策略获取设置这一策略的应用uid数组，使用callback方式作为异步方法 | +| ohos.net.policy | function getNetQuotaPolicies(callback: AsyncCallback\>): void; |获取计量网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function setNetQuotaPolicies(quotaPolicies: Array\, callback: AsyncCallback\): void; |设置计量网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function isUidNetAllowed(uid: number, isMetered: boolean, callback: AsyncCallback\): void; | 获取对应uid能否访问计量或非计量网络，使用callback方式作为异步方法 | +| ohos.net.policy | function isUidNetAllowed(uid: number, iface: string, callback: AsyncCallback\): void; | 获取对应uid能否访问指定的iface的网络，使用callback方式作为异步方法 | +| ohos.net.policy | function setDeviceIdleTrustlist(uid: number, isAllowed: boolean, callback: AsyncCallback\): void; | 设置指定uid应用是否在休眠防火墙的白名单，使用callback方式作为异步方法 | +| ohos.net.policy | function getDeviceIdleTrustlist(callback: AsyncCallback\>): void; | 获取休眠模式白名单所包含的uid数组，使用callback方式作为异步方法 | +| ohos.net.policy | function getBackgroundPolicyByUid(uid: number, callback: AsyncCallback\): void; | 获取指定uid能否访问后台网络，使用callback方式作为异步方法 | +| ohos.net.policy | function resetPolicies(simId: string, callback: AsyncCallback\): void; | 重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用callback方式作为异步方法 | +| ohos.net.policy | function updateRemindPolicy(netType: NetBearType, simId: string, remindType: RemindType, callback: AsyncCallback\): void; | 更新提醒策略，使用callback方式作为异步方法 | +| ohos.net.policy | function setPowerSaveTrustlist(uid: number, isAllowed: boolean, callback: AsyncCallback\): void; | 设置指定uid应用是否在省电防火墙的白名单，使用callback方式作为异步方法 | +| ohos.net.policy | function getPowerSaveTrustlist(callback: AsyncCallback\>): void; | 获取省电模式白名单所包含的uid数组，使用callback方式作为异步方法 | +| ohos.net.policy | function on(type: "netUidPolicyChange", callback: Callback\<{ uid: number, policy: NetUidPolicy }>): void; | 订阅policy发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function off(type: "netUidPolicyChange", callback: Callback\<{ uid: number, policy: NetUidPolicy }>): void; | 取消订阅policy发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function on(type: "netUidRuleChange", callback: Callback\<{ uid: number, rule: NetUidRule }>): void; | 订阅rule发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function off(type: "netUidRuleChange", callback: Callback\<{ uid: number, rule: NetUidRule }>): void; | 取消订阅rule发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function on(type: "netMeteredIfacesChange", callback: Callback\>): void; | 订阅计量iface发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function off(type: "netMeteredIfacesChange", callback: Callback\>): void; | 取消订阅计量iface发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function on(type: "netQuotaPolicyChange", callback: Callback\>): void; | 订阅计量网络策略发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function off(type: "netQuotaPolicyChange", callback: Callback\>): void; | 取消订阅计量网络策略发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function on(type: "netBackgroundPolicyChange", callback: Callback\): void; | 订阅后台网络策略发生改变时的回调，使用callback方式作为异步方法 | +| ohos.net.policy | function off(type: "netBackgroundPolicyChange", callback: Callback\): void; | 取消订阅后台网络策略发生改变时的回调，使用callback方式作为异步方法 | + +## 设置计量网络配额/获取已经设置的计量网络策略 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用setNetQuotaPolicies方法，设置计量网络策略。 + +3. 调用getNetQuotaPolicies方法，获取计量网络策略。 + +```js +// 引入包名 +import policy from '@ohos.net.policy'; +import connection from '@ohos.net.connection'; +netQuotaPolicyList = [] +let param = { + // netType值详见 [NetBearType](../reference/apis/js-apis-net-connection.md#netbeartype) + netType: Number.parseInt(connection.NetBearType.BEARER_CELLULAR), + + // 计量蜂窝网络的SIM卡的标识值。以太网，wifi网络不会用到 + simId: 1, + + // 计量蜂窝网络中配合simId联合使用。以太网，wifi网络单独使用。用于标记类型 + identity: "", + + // 计量开始时间。例如M1、D1、Y1等 + periodDuration: "M1", + + // 发出警告的流量阈值 大于0的整数即可 + warningBytes: Number.parseInt(40000), + + // 流量设置的配额 大于0的整数即可 + limitBytes: Number.parseInt(50000), + + // 是否为计量网络 true为计量网络 false为非计量网络 + metered: Boolean(Number.parseInt(true)), + // 到达流量限制后的动作 详见[LimitAction](../reference/apis/js-apis-net-policy.md#limitaction) + limitAction: policy.LimitAction.LIMIT_ACTION_NONE +}; +netQuotaPolicyList.push(param); + +// 订阅计量网络iface发生改变时的回调 +policy.on('netMeteredIfacesChange', (data) => { + console.log('on netMeteredIfacesChange:' + JSON.stringify(data)); +}); + +// 订阅计量网络策略发生改变时的回调 +policy.on('netQuotaPolicyChange', (data) => { + console.log('on netQuotaPolicyChange:' + JSON.stringify(data)); +}); + +// 调用setNetQuotaPolicies方法，设置计量网络策略 +policy.setNetQuotaPolicies(netQuotaPolicyList, (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); +}); + +// 调用getNetQuotaPolicies方法，获取计量网络策略 +policy.getNetQuotaPolicies((error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); + +// 取消订阅计量网络iface发生改变时的回调 +policy.off('netMeteredIfacesChange', (data) => { + console.log('off netMeteredIfacesChange:' + JSON.stringify(data)); +}); + +// 取消订阅计量网络策略发生改变时的回调 +policy.off('netQuotaPolicyChange', (data) => { + console.log('off netQuotaPolicyChange:' + JSON.stringify(data)); +}); +``` + +## 后台网络限制开关/获取后台网络限制状态/获取指定uid在后台状态下能否访问网络 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用setBackgroundAllowed方法，设置开启后台省流量或关闭后台省流量。 + +3. 调用isBackgroundAllowed方法，获取后台网络限制状态（省流量）是开启还是关闭。 + +4. 调用getBackgroundPolicyByUid方法，获取指定uid在后台状态下能否访问网络。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 订阅后台网络策略发生改变时的回调 +policy.on('netBackgroundPolicyChange', (data) => { + console.log('on netBackgroundPolicyChange:' + JSON.stringify(data)); +}); + +// 调用setBackgroundAllowed方法，设置开启后台省流量或关闭后台省流量 +policy.setBackgroundAllowed(Boolean(Number.parseInt(true)), (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)) +}); + +// 调用isBackgroundAllowed方法，获取后台网络限制状态（省流量）是开启还是关闭。 +policy.isBackgroundAllowed((err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)) +}); + +// 调用getBackgroundPolicyByUid方法，获取指定uid在后台状态下能否访问网络。 +policy.getBackgroundPolicyByUid((Number.parseInt(11111)), (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)) +}); + +// 取消订阅后台网络策略发生改变时的回调 +policy.off('netBackgroundPolicyChange', (data) => { + console.log('off netBackgroundPolicyChange:' + JSON.stringify(data)); +}); +``` + +## 设定指定uid访问计量网络的策略/获取指定uid访问计量网络的策略/获取设置了对应策略的uids + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用setPolicyByUid方法，设置指定uid是否可以访问后台网络。 + +3. 调用getPolicyByUid方法，获取指定uid的策略。 + +4. 调用getUidsByPolicy方法，获取使用指定策略的uids。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 订阅uid的policy发生改变时的回调 +policy.on('netUidPolicyChange', (data) => { + console.log('on netUidPolicyChange:' + JSON.stringify(data)); +}); + +// 订阅uid的rule发生改变时的回调 +policy.on('netUidRuleChange', (data) => { + console.log('on netUidRuleChange:' + JSON.stringify(data)); +}); + +// 调用setPolicyByUid方法，设置指定uid是否可以访问后台网络 +let param = { + uid: Number.parseInt(11111), policy: Number.parseInt(policy.NetUidPolicy.NET_POLICY_NONE) +} +policy.setPolicyByUid(param, (error) => { + console.log(JSON.stringify(error)) +}); + +// 调用getPolicyByUid方法，获取指定uid的策略 +policy.getPolicyByUid(Number.parseInt(11111), (error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); + +// 调用getUidsByPolicy方法，获取使用指定策略的uids +policy.getUidsByPolicy(Number.parseInt(11111), (error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); + +// 取消订阅uid的policy发生改变时的回调 +policy.off('netUidPolicyChange', (data) => { + console.log('off netUidPolicyChange:' + JSON.stringify(data)); +}); + +// 取消订阅uid的rule发生改变时的回调 +policy.off('netUidRuleChange', (data) => { + console.log('off netUidRuleChange:' + JSON.stringify(data)); +}); +``` + +## 重置网络策略 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用restoreAllPolicies方法，重置网络策略。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 调用restoreAllPolicies方法，重置网络策略 +policy.resetPolicies(1, (error) => { + console.log(JSON.stringify(error)) +}); +``` + +## 判断uid能否访问计量/非计量网络 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用isUidNetAllowed方法，获取uid能否访问计量/非计量网络。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 调用isUidNetAllowed方法，获取uid能否访问计量/非计量网络 +let param = { + uid: Number.parseInt(11111), isMetered: true +} +policy.isUidNetAllowed(param, (error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); +``` + +## 将对应uid从休眠白名单里添加、移除/获取休眠模式的白名单列表 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用setDeviceIdleTrustlist方法，设置uid是否添加到休眠模式白名单。 + +3. 调用getDeviceIdleTrustlist方法，获取添加在休眠模式白名单的uids。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 调用setDeviceIdleTrustlist方法，设置uid是否添加到休眠模式白名单 +let param = { + uids: [11111, 22222], isAllowed: true +} +policy.setDeviceIdleTrustlist(param, (error) => { + console.log(JSON.stringify(error)) +}); + +// 调用getDeviceIdleTrustlist方法，获取添加在休眠模式白名单的uids +policy.getDeviceIdleTrustlist((error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); +``` + +## 将对应uid从省电白名单里添加、移除/获取省电模式的白名单列表 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 +2. 调用setPowerSaveTrustlist方法，设置uid是否添加到省电模式白名单。 +3. 调用getPowerSaveTrustlist方法，获取添加在省电模式白名单的uids。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 调用setPowerSaveTrustlist方法，设置uid是否添加到省电模式白名单 +let param = { + uids: [11111, 22222], isAllowed: true +} +policy.setDeviceIdleTrustlist(param, (error) => { + console.log(JSON.stringify(error)) +}); + +// 调用getPowerSaveTrustlist方法，获取添加在省电模式白名单的uids +policy.getPowerSaveTrustlist((error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); +``` + +## 更新网络提醒策略 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用updateRemindPolicy，更新网络提醒策略。 + +```js +// 引入包名 +import policy from '@ohos.net.policy' + +// 调用updateRemindPolicy，更新网络提醒策略 +let param = { + netType: Number.parseInt(connection.NetBearType.BEARER_CELLULAR), simId: 1, + remindType: policy.NetUidPolicy.NET_POLICY_NONE +} +policy.updateRemindPolicy(param, (error) => { + console.log(JSON.stringify(error)) +}); +``` \ No newline at end of file -- Gitee From 07b18a5d187e706a8c8db90a3f9186d3da6aea9e Mon Sep 17 00:00:00 2001 From: xujie Date: Fri, 14 Jul 2023 10:19:17 +0800 Subject: [PATCH 2/2] update Change-Id: Ia85cf8bbdf1c35056b4ffaf42494a17ad1730174 Signed-off-by: xujie --- zh-cn/application-dev/connectivity/net-policy-management.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/zh-cn/application-dev/connectivity/net-policy-management.md b/zh-cn/application-dev/connectivity/net-policy-management.md index f78c0233449..0681a6953aa 100644 --- a/zh-cn/application-dev/connectivity/net-policy-management.md +++ b/zh-cn/application-dev/connectivity/net-policy-management.md @@ -1,4 +1,4 @@ -# 网络策略管理部件 +# 网络策略管理 ## 简介 @@ -11,9 +11,9 @@ - 休眠模式：设备在不需要工作的时候把一些部件、外设关掉(进入低功耗模式)，并限制部分应用对网络的访问。 - 省电模式：省电模式是系统里的一个开关，开启后会降低设备的性能，并限制部分应用对网络的访问。 -- 省流量模式：即后台网络策略，对处于后台的使用计量网络的应用进行限制。 +- 省流量模式：即后台网络策略，将阻止应用在后台使用计量网络。 - 蜂窝网络：移动通信网络。 -- 计量网络：设置了流量配额的电话卡网络、Wlan网络以及以太网。 +- 计量网络：设置了流量配额的蜂窝网络、Wlan网络以及以太网。 ## 约束 -- Gitee