From 9d4394f1880602b778e120b0ea460e7ce5745a1b Mon Sep 17 00:00:00 2001 From: zhanghaifeng Date: Wed, 8 Feb 2023 15:44:33 +0800 Subject: [PATCH] Description: add doc Signed-off-by: zhanghaifeng --- .../application-dev/connectivity/Readme-CN.md | 4 + .../connectivity/net-connection-manager.md | 265 +++ .../connectivity/net-ethernet.md | 145 ++ .../connectivity/net-mgmt-overview.md | 4 + .../connectivity/net-policy-management.md | 421 +++++ .../connectivity/net-sharing.md | 141 ++ .../connectivity/socket-connection.md | 213 ++- .../reference/apis/js-apis-http.md | 2 +- .../reference/apis/js-apis-net-connection.md | 1234 ++++++++++--- .../reference/apis/js-apis-net-ethernet.md | 13 +- .../reference/apis/js-apis-net-policy.md | 1558 +++++++++++++++++ .../reference/apis/js-apis-net-sharing.md | 4 +- 12 files changed, 3709 insertions(+), 295 deletions(-) create mode 100644 zh-cn/application-dev/connectivity/net-connection-manager.md create mode 100644 zh-cn/application-dev/connectivity/net-ethernet.md create mode 100644 zh-cn/application-dev/connectivity/net-policy-management.md create mode 100644 zh-cn/application-dev/connectivity/net-sharing.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-net-policy.md diff --git a/zh-cn/application-dev/connectivity/Readme-CN.md b/zh-cn/application-dev/connectivity/Readme-CN.md index 1a28dc8b98..b9d8b96bc4 100755 --- a/zh-cn/application-dev/connectivity/Readme-CN.md +++ b/zh-cn/application-dev/connectivity/Readme-CN.md @@ -5,6 +5,10 @@ - [HTTP数据请求](http-request.md) - [WebSocket连接](websocket-connection.md) - [Socket连接](socket-connection.md) + - [策略管理](net-policy-management.md) + - [网络共享](net-sharing.md) + - [以太网连接](net-ethernet.md) + - [网络连接管理](net-connection-manager.md) - IPC与RPC通信 - [IPC与RPC通信概述](ipc-rpc-overview.md) - [IPC与RPC通信开发指导](ipc-rpc-development-guideline.md) diff --git a/zh-cn/application-dev/connectivity/net-connection-manager.md b/zh-cn/application-dev/connectivity/net-connection-manager.md new file mode 100644 index 0000000000..cdf86d140d --- /dev/null +++ b/zh-cn/application-dev/connectivity/net-connection-manager.md @@ -0,0 +1,265 @@ +# 网络连接管理 + +## 简介 +网络连接管理提供管理网络一些基础能力，包括WiFi/蜂窝/Ethernet等多网络连接优先级管理、网络质量评估、订阅默认/指定网络连接状态变化、查询网络连接信息、DNS解析等功能。 + +> **说明：** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 基本概念 +- 网络生产者：数据网络的提供方，比如WiFi、蜂窝、Ethernet等。 +- 网络消费者：数据网络的使用方，比如应用或系统服务。 +- 网络探测：检测网络有效性，避免将网络从可用网络切换到不可用网络。内容包括绑定网络探测、DNS探测、HTTP探测及HTTPS探测。 +- 网络优选：处理多网络共存时选择最优网络。在网络状态、网络信息及评分发生变化时被触发。 + +## 约束 +- 开发语言：C++ JS +- 系统：linux内核 + +## 场景介绍 +网络连接管理的典型场景有： +- 接收指定网络的状态变化通知 +- 获取所有注册的网络 +- 根据数据网络查询网络的连接信息 +- 使用对应网络解析域名，获取所有IP + +以下分别介绍具体开发方式。 +## 接口说明 +完整的JS API说明以及实例代码请参考：[网络连接管理](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-net-connection.md)。 + +| 类型 | 接口 | 功能说明 | +| ---- | ---- | ---- | +| ohos.net.connection | function getDefaultNet(callback: AsyncCallback\): void; |获取一个含有默认网络的netId的NetHandle对象，使用callback回调 | +| ohos.net.connection | function getDefaultNet(): Promise\; |获取一个含有默认网络的netId的NetHandle对象，使用Promise回调 | +| ohos.net.connection | function getGlobalHttpProxy10+(callback: AsyncCallback\): void;| 获取网络的全局代理设置，使用callback回调 | +| ohos.net.connection | function getGlobalHttpProxy10+(): Promise\;| 获取网络的全局代理设置，使用Promise回调 | +| ohos.net.connection | function setGlobalHttpProxy10+(httpProxy: HttpProxy, callback: AsyncCallback): void;| 设置网络全局Http代理配置信息，使用callback回调 | +| ohos.net.connection | function setGlobalHttpProxy10+(httpProxy: HttpProxy): Promise;| 设置网络全局Http代理配置信息，使用Promise回调 | +| ohos.net.connection | function getAppNet9+(callback: AsyncCallback\): void;| 获取一个App绑定的包含了网络netId的NetHandle对象，使用callback回调 | +| ohos.net.connection | function getAppNet9+(): Promise\;| 获取一个App绑定的包含了网络netId的NetHandle对象，使用Promise回调 | +| ohos.net.connection | function setAppNet9+(netHandle: NetHandle, callback: AsyncCallback\): void;| 绑定App到指定网络，绑定后的App只能通过指定网络访问外网。使用callback回调 | +| ohos.net.connection | function setAppNet9+(netHandle: NetHandle): Promise\;| 绑定App到指定网络，绑定后的App只能通过指定网络访问外网。使用Promise回调 | +| ohos.net.connection | function getDefaultNetSync9+(): NetHandle; |使用同步方法获取默认激活的数据网络。可以使用getNetCapabilities去获取网络的类型、拥有的能力等信息。| +| ohos.net.connection | function hasDefaultNet(callback: AsyncCallback\): void; |查询是否有默认网络，使用callback回调 | +| ohos.net.connection | function hasDefaultNet(): Promise\; |查询是否有默认网络，使用Promise回调 | +| ohos.net.connection | function getAllNets(callback: AsyncCallback\>): void;| 获取所处于连接状态的网络的MetHandle对象列表，使用callback回调 | +| ohos.net.connection | function getAllNets(): Promise\>;| 获取所有处于连接状态的网络的NetHandle对象列表，使用Promise回调 | +| ohos.net.connection | function getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback\): void; |查询默认网络的链路信息，使用callback回调 | +| ohos.net.connection | function getConnectionProperties(netHandle: NetHandle): Promise\; |查询默认网络的链路信息，使用Promise回调 | +| ohos.net.connection | function getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback\): void; |查询默认网络的能力集信息，使用callback回调 | +| ohos.net.connection | function getNetCapabilities(netHandle: NetHandle): Promise\; |查询默认网络的能力集信息，使用Promise回调 | +| ohos.net.connection | function isDefaultNetMetered9+(callback: AsyncCallback): void; |检查当前网络上的数据流量使用是否被计量，使用callback方式作为异步方法 | +| ohos.net.connection | function isDefaultNetMetered9+(): Promise; |检查当前网络上的数据流量使用是否被计量，使用Promise方式作为异步方法 | +| ohos.net.connection | function reportNetConnected(netHandle: NetHandle, callback: AsyncCallback\): void;| 向网络管理报告网络处于可用状态，调用此接口说明应用程序认为网络的可用性（ohos.net.connection.NetCap.NET_CAPABILITY_VAILDATED）与网络管理不一致。使用callback回调 | +| ohos.net.connection | function reportNetConnected(netHandle: NetHandle): Promise\;| 向网络管理报告网络处于可用状态，调用此接口说明应用程序认为网络的可用性（ohos.net.connection.NetCap.NET_CAPABILITY_VAILDATED）与网络管理不一致。使用Promise回调 | +| ohos.net.connection | function reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback\): void;| 向网络管理报告网络处于不可用状态，调用此接口说明应用程序认为网络的可用性（ohos.net.connection.NetCap.NET_CAPABILITY_VAILDATED）与网络管理不一致。使用callback回调 | +| ohos.net.connection | function reportNetDisconnected(netHandle: NetHandle): Promise\;| 向网络管理报告网络处于不可用状态，调用此接口说明应用程序认为网络的可用性（ohos.net.connection.NetCap.NET_CAPABILITY_VAILDATED）与网络管理不一致。使用Promise回调 | +| ohos.net.connection | function getAddressesByName(host: string, callback: AsyncCallback\>): void; |使用对应网络解析域名，获取所有IP，使用callback回调 | +| ohos.net.connection | function getAddressesByName(host: string): Promise\>; |使用默认网络解析域名，获取所有IP，使用Promise回调 | +| ohos.net.connection | function enableAirplaneMode(callback: AsyncCallback\): void; | 设置网络为飞行模式，使用callback回调 | +| ohos.net.connection | function enableAirplaneMode(): Promise\;|设置网络为飞行模式，使用Promise回调 | +| ohos.net.connection | function disableAirplaneMode(callback: AsyncCallback\): void;| 关闭网络飞行模式，使用callback回调 | +| ohos.net.connection | function disableAirplaneMode(): Promise\;| 关闭网络飞行模式，使用Promise回调 | +| ohos.net.connection | function createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection; | 返回一个NetConnection对象，netSpecifier指定关注的网络的各项特征，timeout是超时时间(单位是毫秒)，netSpecifier是timeout的必要条件，两者都没有则表示关注默认网络 | +| ohos.net.connection.NetHandle | bindSocket(socketParam: TCPSocket \| UDPSocket, callback: AsyncCallback\): void; | 将TCPSocket或UDPSockett绑定到当前网络，使用callback回调 | +| ohos.net.connection.NetHandle | bindSocket(socketParam: TCPSocket \| UDPSocket): Promise\;| 将TCPSocket或UDPSockett绑定到当前网络，使用Promise回调 | +| ohos.net.connection.NetHandle | getAddressesByName(host: string, callback: AsyncCallback\>): void; |使用默认网络解析域名，获取所有IP，使用callback回调 | +| ohos.net.connection.NetHandle | getAddressesByName(host: string): Promise\>; |使用对应网络解析域名，获取所有IP，使用Promise回调 | +| ohos.net.connection.NetHandle | getAddressByName(host: string, callback: AsyncCallback\): void; |使用对应网络解析域名，获取一个IP，调用callbac | +| ohos.net.connection.NetHandle | getAddressByName(host: string): Promise\; |使用对应网络解析域名，获取一个IP，使用Promise回调 | +| ohos.net.connection.NetConnection | on(type: 'netAvailable', callback: Callback\): void; |监听收到网络可用的事件 | +| ohos.net.connection.NetConnection | on(type: 'netCapabilitiesChange', callback: Callback\<{ netHandle: NetHandle, netCap: NetCapabilities }>): void; |监听网络能力变化的事件 | +| ohos.net.connection.NetConnection | on(type: 'netConnectionPropertiesChange', callback: Callback\<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void; |监听网络连接信息变化的事件 | +| ohos.net.connection.NetConnection | on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void; |订阅网络阻塞状态事件，使用callback方式作为异步方法 | +| ohos.net.connection.NetConnection | on(type: 'netLost', callback: Callback\): void; |监听网络丢失的事件 | +| ohos.net.connection.NetConnection | on(type: 'netUnavailable', callback: Callback\): void; |监听网络不可用的事件 | +| ohos.net.connection.NetConnection | register(callback: AsyncCallback\): void; |注册默认网络或者createNetConnection中指定的网络的监听 | +| ohos.net.connection.NetConnection | unregister(callback: AsyncCallback\): void; |注销默认网络或者createNetConnection中指定的网络的监听 | + +## 接收指定网络的状态变化通知 + +### 开发步骤 + +1. 从@ohos.net.connection.d.ts中导入connection命名空间。 + +2. 调用createNetConnection方法，指定网络能力、网络类型和超时时间（可选，如不传入代表默认网络；创建不同于默认网络时可通过指定这些参数完成），创建一个NetConnection对象。 + +3. 调用该对象的on()方法，传入type和callback，订阅关心的事件。 + +4. 调用该对象的register()方法，订阅指定网络状态变化的通知。 + +5. 当网络可用时，会收到netAvailable事件的回调；当网络不可用时，会收到netUnavailable事件的回调。 + +6. 当不使用该网络时，可以调用该对象的unregister()方法，取消订阅。 + +```js + // 引入包名 + import connection from '@ohos.net.connection' + + let netCap = { + // 假设当前默认网络是WiFi，需要创建蜂窝网络连接，可指定网络类型为蜂窝网 + bearerTypes: [connection.NetBearType.BEARER_CELLULAR], + // 指定网络能力为Internet + networkCap: [connection.NetCap.NET_CAPABILITY_INTERNET], + }; + let netSpec = { + netCapabilities: netCap, + }; + + // 指定超时时间为10s(默认值为0) + let timeout = 10 * 1000; + + // 创建NetConnection对象 + let conn = connection.createNetConnection(netSpec, timeout); + + // 订阅事件，如果当前指定网络可用，通过on_netAvailable通知用户 + conn.on('netAvailable', (data=> { + console.log("net is available, netId is " + data.netId); + })); + + // 订阅事件，如果当前指定网络不可用，通过on_netUnavailable通知用户 + conn.on('netUnavailable', (data=> { + console.log("net is unavailable, netId is " + data.netId); + })); + + // 订阅指定网络状态变化的通知 + conn.register((err, data) => {}); + + // 当不使用该网络时，可以调用该对象的unregister()方法，取消订阅 + conn.unregister((err, data) => {}); +``` + +## 获取所有注册的网络 + +### 开发步骤 + +1. 从@ohos.net.connection.d.ts中导入connection命名空间。 + +2. 调用getAllNets方法，获取所有处于连接状态的网络列表。 + +```js + // 引入包名 + import connection from '@ohos.net.connection' + + // 获取所有处于连接状态的网络列表 + connection.getAllNets((err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + if (data) { + this.netList = data; + } + }) +``` + +## 根据数据网络查询网络的能力信息及连接信息 + +### 开发步骤 + +1. 从@ohos.net.connection.d.ts中导入connection命名空间。 + +2. 通过调用getDefaultNet方法，获取默认的数据网络(NetHandle)；或者通过调用getAllNets方法，获取所有处于连接状态的网络列表(Array\)。 + +3. 调用getNetCapabilities方法，获取NetHandle对应网络的能力信息。能力信息包含了网络类型(蜂窝网络、Wi-Fi网络、以太网网络等)、网络具体能力等网络信息。 + +4. 调用getConnectionProperties方法，获取NetHandle对应网络的连接信息。 + +```js + // 引入包名 + import connection from '@ohos.net.connection' + + // 调用getDefaultNet方法，获取默认的数据网络(NetHandle) + connection.getDefaultNet((err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + if (data) { + this.netHandle = data; + } + }) + + // 获取netHandle对应网络的能力信息。能力信息包含了网络类型、网络具体能力等网络信息 + connection.getNetCapabilities(this.netHandle, (err, data) => { + console.log(JSON.stringify(err)); + + // 获取网络类型(bearerTypes) + for (let item of data.bearerTypes) { + if (item == 0) { + // 蜂窝网 + console.log(JSON.stringify("BEARER_CELLULAR")); + } else if (item == 1) { + // Wi-Fi网络 + console.log(JSON.stringify("BEARER_WIFI")); + } else if (item == 3) { + // 以太网网络 + console.log(JSON.stringify("BEARER_ETHERNET")); + } + } + + // 获取网络具体能力(networkCap) + for (let item of data.networkCap) { + if (item == 0) { + // 表示网络可以访问运营商的MMSC（Multimedia Message Service，多媒体短信服务）发送和接收彩信 + console.log(JSON.stringify("NET_CAPABILITY_MMS")); + } else if (item == 11) { + // 表示网络流量未被计费 + console.log(JSON.stringify("NET_CAPABILITY_NOT_METERED")); + } else if (item == 12) { + // 表示该网络应具有访问Internet的能力，该能力由网络提供者设置 + console.log(JSON.stringify("NET_CAPABILITY_INTERNET")); + } else if (item == 15) { + // 表示网络不使用VPN（Virtual Private Network，虚拟专用网络） + console.log(JSON.stringify("NET_CAPABILITY_NOT_VPN")); + } else if (item == 16) { + // 表示该网络访问Internet的能力被网络管理成功验证，该能力由网络管理模块设置 + console.log(JSON.stringify("NET_CAPABILITY_VALIDATED")); + } + } + }) + + // 获取netHandle对应网络的连接信息。连接信息包含了链路信息、路由信息等 + connection.getConnectionProperties(this.netHandle, (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + }) + + // 调用getAllNets,获取所有处于连接状态的网络列表(Array) + connection.getAllNets((err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + if (data) { + this.netList = data; + } + }) + + for (let item of this.netList) { + // 循环获取网络列表每个netHandle对应网络的能力信息 + connection.getNetCapabilities(item, (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + }) + + // 循环获取网络列表每个netHandle对应的网络的连接信息 + connection.getConnectionProperties(item, (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + }) + } +``` + +## 使用对应网络解析域名，获取所有IP + +### 开发步骤 + +1. 从@ohos.net.connection.d.ts中导入connection命名空间。 + +2. 调用getAddressesByName方法，使用默认网络解析主机名以获取所有IP地址。 + +```js + // 引入包名 + import connection from '@ohos.net.connection' + + // 使用默认网络解析主机名以获取所有IP地址 + connection.getAddressesByName(this.host, (err, data) => { + console.log(JSON.stringify(err)); + console.log(JSON.stringify(data)); + }) +``` diff --git a/zh-cn/application-dev/connectivity/net-ethernet.md b/zh-cn/application-dev/connectivity/net-ethernet.md new file mode 100644 index 0000000000..8ab9e0e775 --- /dev/null +++ b/zh-cn/application-dev/connectivity/net-ethernet.md @@ -0,0 +1,145 @@ +# 以太网连接 + +## 简介 +以太网连接的功能是提供支持设备通过硬件接口，以插入网线的形式访问互联网的能力。 +设备接入网线后，可以获取动态分配的IP地址，xxx等一系列网络属性；也可以通过静态模式，手动配置与获取设备的网络属性。 + +> **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 约束 +- 开发语言：C++ JS +- 系统：linux内核 + +## 场景介绍 +以太网连接的典型场景有： +- DHCP模式，通过动态分配IP地址，子网掩码，Gateway，DNS等一系列网络属性，使能访问网络。 +- 静态模式，通过静态配置IP地址，子网掩码，Gateway，DNS等一系列网络属性，使能访问网络。 + +以下分别介绍具体开发方式。 + +## 接口说明 +完整的JS API说明以及实例代码请参考：[以太网连接](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md)。 + +| 类型 | 接口 | 功能说明 | +| ---- | ---- | ---- | +| ohos.net.ethernet | function setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallback\): void | 配置指定以太网的网络属性，iface为网口名称，ic为配置信息，调用callback | +| ohos.net.ethernet | function setIfaceConfig(iface: string, ic: InterfaceConfiguration): Promise\; | 配置指定以太网的网络属性，iface为网口名称，ic为配置信息，返回promise | +| ohos.net.ethernet | function getIfaceConfig(iface: string, callback: AsyncCallback\): void | 获取指定以太网的网络属性，iface为网口名称，调用callback | +| ohos.net.ethernet | function getIfaceConfig(iface: string): Promise\; | 获取指定以太网的网络属性，iface为网口名称，返回promise | +| ohos.net.ethernet | function isIfaceActive(iface: string, callback: AsyncCallback\): void | 判断指定网口是否已激活，iface为网卡名称（无参为是否有激活网口），调用callback | +| ohos.net.ethernet | function isIfaceActive(iface: string): Promise\; | 判断指定网口是否已激活，iface为网卡名称（无参为是否有激活网口），返回promise | +| ohos.net.ethernet | function getAllActiveIfaces(callback: AsyncCallback\>): void; | 获取所有活动的网络接口，调用callback | +| ohos.net.ethernet | function getAllActiveIfaces(): Promise\>; | 获取所有活动的网络接口，返回promise | + +## 以太网连接-DHCP模式 + +### 开发步骤 + +1. 设备通过硬件接口，插入网线。 +2. 从@ohos.net.ethernet中导入ethernet命名空间。 +3. 调用getAllActiveIfaces方法，获取所有激活的有线网卡名称，如：“eth0”，“eth1”。 +4. 用户态通过isIfaceActive方法，来判断网口“eth0”是否已激活。 +5. 用户态通过getIfaceConfig方法，来获取指定网口“eth0”的网络属性，未设置过的以太网络默认为DHCP模式，获取自动分配的网络属性。 + +```js + // 从@ohos.net.ethernet中导入ethernet命名空间 + import ethernet from '@ohos.net.ethernet' + + // getAllActiveIfaces获取所有活动的网络设备名称 + ethernet.getAllActiveIfaces((error, data) => { + if (error) { + console.log("getAllActiveIfaces callback error = " + error); + } else { + console.log("getAllActiveIfaces callback data.length = " + data.length); + for (let i = 0; i < data.length; i++) { + console.log("getAllActiveIfaces callback = " + data[i]); + } + } + }); + + // isIfaceActive判断指定网口是否已激活 + ethernet.isIfaceActive("eth0", (error, data) => { + if (error) { + console.log("isIfaceActive callback error = " + error); + } else { + console.log("isIfaceActive callback = " + data); + } + }); + + // getIfaceConfig获取指定以太网的网络属性 + ethernet.getIfaceConfig("eth0", (error, data) => { + if (error) { + console.log("getIfaceConfig callback error = " + error); + } else { + console.log("getIfaceConfig callback mode = " + data.mode); + console.log("getIfaceConfig callback ipAddr = " + data.ipAddr); + console.log("getIfaceConfig callback routeAddr = " + data.routeAddr); + console.log("getIfaceConfig callback gateAddr = " + data.gateAddr); + console.log("getIfaceConfig callback maskAddr = " + data.maskAddr); + console.log("getIfaceConfig callback dns0Addr = " + data.dns0Addr); + console.log("getIfaceConfig callback dns1Addr = " + data.dns1Addr); + } + }); +``` +## 以太网连接-静态模式 + +### 开发步骤 + +1. 设备通过硬件接口，插入网线。 +2. 从@ohos.net.ethernet中导入ethernet命名空间。 +3. 用户态通过getAllActiveIfaces方法，来获取所有活动的网络设备名称，如：“eth0”，“eth1”。 +4. 用户态通过isIfaceActive方法，来判断网口“eth0”是否已激活。 +5. 用户态调用setIfaceConfig方法，来设置指定网口"eth0"为静态模式，手动IP地址，子网掩码，Gateway，DNS等网络属性。 +6. 用户态通过getIfaceConfig方法，来获取指定网口“eth0”的静态网络属性。 + +```js + // 从@ohos.net.ethernet中导入ethernet命名空间 + import ethernet from '@ohos.net.ethernet' + + // getAllActiveIfaces获取所有活动的网络设备名称 + ethernet.getAllActiveIfaces((error, data) => { + if (error) { + console.log("getAllActiveIfaces callback error = " + error); + } else { + console.log("getAllActiveIfaces callback data.length = " + data.length); + for (let i = 0; i < data.length; i++) { + console.log("getAllActiveIfaces callback = " + data[i]); + } + } + }); + + // isIfaceActive判断指定网口是否已激活 + ethernet.isIfaceActive("eth0", (error, data) => { + if (error) { + console.log("isIfaceActive callback error = " + error); + } else { + console.log("isIfaceActive callback = " + data); + } + }); + + // setIfaceConfig配置指定以太网的网络属性 + ethernet.setIfaceConfig("eth0", {mode:ethernet.STATIC,ipAddr:"192.168.xx.xx", routeAddr:"192.168.xx.xx", + gateAddr:"192.168.xx.xx", maskAddr:"255.255.xx.xx", dnsAddr0:"1.1.xx.xx", dnsAddr1:"2.2.xx.xx"},(error) => { + if (error) { + console.log("setIfaceConfig callback error = " + error); + } else { + console.log("setIfaceConfig callback ok "); + } + }); + + // getIfaceConfig获取指定以太网的网络属性 + ethernet.getIfaceConfig("eth0", (error, data) => { + if (error) { + console.log("getIfaceConfig callback error = " + error); + } else { + console.log("getIfaceConfig callback mode = " + data.mode); + console.log("getIfaceConfig callback ipAddr = " + data.ipAddr); + console.log("getIfaceConfig callback routeAddr = " + data.routeAddr); + console.log("getIfaceConfig callback gateAddr = " + data.gateAddr); + console.log("getIfaceConfig callback maskAddr = " + data.maskAddr); + console.log("getIfaceConfig callback dns0Addr = " + data.dns0Addr); + console.log("getIfaceConfig callback dns1Addr = " + data.dns1Addr); + } + }); +``` diff --git a/zh-cn/application-dev/connectivity/net-mgmt-overview.md b/zh-cn/application-dev/connectivity/net-mgmt-overview.md index dcb27c69e0..30846a21c5 100644 --- a/zh-cn/application-dev/connectivity/net-mgmt-overview.md +++ b/zh-cn/application-dev/connectivity/net-mgmt-overview.md @@ -5,6 +5,10 @@ - [HTTP数据请求](http-request.md)：通过HTTP发起一个数据请求。 - [WebSocket连接](websocket-connection.md)：使用WebSocket建立服务器与客户端的双向连接。 - [Socket连接](socket-connection.md)：通过Socket进行数据传输。 +- [网络策略管理](net-policy-management.md)：提供一些限制网络的基础能力，包括蜂窝网络策略、休眠/省电模式策略、后台网络策略、重置网络策略等功能。 +- [网络共享](net-sharing.md)：分享设备已有网络给其他连接设备，支持Wi-Fi热点共享、蓝牙共享和USB共享，同时提供网络共享状态、共享流量查询功能。 +- [以太网连接](net-ethernet.md)：以太网连接主要提供有线网络能力，提供设置有线网络的IP地址，子网掩码，网关，DNS等信息。 +- [网络连接管理](net-connection-manager.md)：网络连接管理提供管理网络一些基础能力，包括WiFi/蜂窝/Ethernet等多网络连接优先级管理、网络质量评估、订阅默认/指定网络连接状态变化、查询网络连接信息、DNS解析等功能。 ## 约束与限制 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 0000000000..0a11acc68e --- /dev/null +++ b/zh-cn/application-dev/connectivity/net-policy-management.md @@ -0,0 +1,421 @@ +# 网络策略管理部件 + +## 简介 + +网络策略管理提供一些限制网络的基础能力，包括蜂窝网络策略、休眠/省电模式策略、后台网络策略、重置网络策略等功能。 + +> **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 基本概念 + +- 休眠模式：设备在不需要工作的时候把一些部件、外设关掉(进入低功耗模式)，并限制部分应用对网络的访问。 +- 省电模式：省电模式是系统里的一个开关，开启后会降低设备的性能，并限制部分应用对网络的访问。 +- 省流量模式：即后台网络策略，对处于后台的使用计量网络的应用进行限制。 +- 蜂窝网络：移动通信网络。 +- 计量网络：设置了流量配额的电话卡网络、Wlan网络以及以太网。 + +## 约束 + +- 开发语言：C++ JS +- 系统：linux内核 + +## 场景介绍 + +网络策略管理的典型场景有： + +- 设置计量网络配额/获取已经设置的计量网络策略 +- 后台网络限制开关/获取后台网络限制状态/获取指定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 setBackgroundPolicy(isAllowed: boolean): Promise\ |设置后台网络策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function isBackgroundAllowed(callback: AsyncCallback\): void; |获取后台网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function isBackgroundAllowed(): Promise\; |获取后台网络策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function setPolicyByUid(uid: number, policy: NetUidPolicy, callback: AsyncCallback\): void; |设置对应uid应用的访问计量网络的策略，使用callback方式作为异步方法 | +| ohos.net.policy | function setPolicyByUid(uid: number, policy: NetUidPolicy): Promise\;| 设置对应uid应用的访问计量网络的策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function getPolicyByUid(uid: number, callback: AsyncCallback\): void;| 通过应用uid获取策略，使用callback方式作为异步方法 | +| ohos.net.policy | function getPolicyByUid(uid: number): Promise\; | 通过应用uid获取策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function getUidsByPolicy(policy: NetUidPolicy, callback: AsyncCallback\>): void; | 通过策略获取设置这一策略的应用uid数组，使用callback方式作为异步方法 | +| ohos.net.policy | function getUidsByPolicy(policy: NetUidPolicy): Promise\>; | 通过策略获取设置这一策略的应用uid数组，使用Promise方式作为异步方法 | +| ohos.net.policy | function getNetQuotaPolicies(callback: AsyncCallback\>): void; |获取计量网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function getNetQuotaPolicies(): Promise\>; |获取计量网络策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function setNetQuotaPolicies(quotaPolicies: Array\, callback: AsyncCallback\): void; |设置计量网络策略，使用callback方式作为异步方法 | +| ohos.net.policy | function setNetQuotaPolicies(quotaPolicies: Array\): Promise\; | 设置计量网络策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function restoreAllPolicies(iccid: string, callback: AsyncCallback\): void; | 重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用callback方式作为异步方法 | +| ohos.net.policy | function restoreAllPolicies(iccid: string): Promise\; | 重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function isUidNetAllowed(uid: number, isMetered: boolean, callback: AsyncCallback\): void; | 获取对应uid能否访问计量或非计量网络，使用callback方式作为异步方法 | +| ohos.net.policy | function isUidNetAllowed(uid: number, isMetered: boolean): Promise\; | 获取对应uid能否访问计量或非计量网络，使用Promise方式作为异步方法 | +| ohos.net.policy | function isUidNetAllowed(uid: number, iface: string, callback: AsyncCallback\): void; | 获取对应uid能否访问指定的iface的网络，使用callback方式作为异步方法 | +| ohos.net.policy | function isUidNetAllowed(uid: number, iface: string): Promise\; | 获取对应uid能否访问指定的iface的网络，使用Promise方式作为异步方法 | +| ohos.net.policy | function setDeviceIdleAllowList(uid: number, isAllowed: boolean, callback: AsyncCallback\): void; | 设置指定uid应用是否在休眠防火墙的白名单，使用callback方式作为异步方法 | +| ohos.net.policy | function setDeviceIdleAllowList(uid: number, isAllowed: boolean): Promise\; | 设置指定uid应用是否在休眠防火墙的白名单，使用Promise方式作为异步方法 | +| ohos.net.policy | function getDeviceIdleAllowList(callback: AsyncCallback\>): void; | 获取休眠模式白名单所包含的uid数组，使用callback方式作为异步方法 | +| ohos.net.policy | function getDeviceIdleAllowList(): Promise\>; | 获取休眠模式白名单所包含的uid数组，使用Promise方式作为异步方法 | +| ohos.net.policy | function getBackgroundPolicyByUid(uid: number, callback: AsyncCallback\): void; | 获取指定uid能否访问后台网络，使用callback方式作为异步方法 | +| ohos.net.policy | function getBackgroundPolicyByUid(uid: number): Promise\; | 获取指定uid能否访问后台网络，使用Promise方式作为异步方法 | +| ohos.net.policy | function resetPolicies(iccid: string, callback: AsyncCallback\): void; | 重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用callback方式作为异步方法 | +| ohos.net.policy | function resetPolicies(iccid: string): Promise\; | 重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用Promise方式作为异步方法 | +| ohos.net.policy | function updateRemindPolicy(netType: NetBearType, iccid: string, remindType: RemindType, callback: AsyncCallback\): void; | 更新提醒策略，使用callback方式作为异步方法 | +| ohos.net.policy | function updateRemindPolicy(netType: NetBearType, iccid: string, remindType: RemindType): Promise\; | 更新提醒策略，使用Promise方式作为异步方法。 | +| ohos.net.policy | function setPowerSaveAllowList(uid: number, isAllowed: boolean, callback: AsyncCallback\): void; | 设置指定uid应用是否在省电防火墙的白名单，使用callback方式作为异步方法 | +| ohos.net.policy | function setPowerSaveAllowList(uid: number, isAllowed: boolean): Promise\; | 设置指定uid应用是否在省电防火墙的白名单，使用Promise方式作为异步方法 | +| ohos.net.policy | function getPowerSaveAllowList(callback: AsyncCallback\>): void; | 获取省电模式白名单所包含的uid数组，使用callback方式作为异步方法 | +| ohos.net.policy | function getPowerSaveAllowList(): Promise\>; | 获取休眠模式白名单所包含的uid数组，使用Promise方式作为异步方法 | +| 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'; + + addNetQuotaPolicy(){ + let param = { + // netType值详见 [NetBearType](../reference/apis/js-apis-net-connection.md#netbeartype) + netType:Number.parseInt(this.netType), + + // 计量蜂窝网络的SIM卡的标识值。以太网，wifi网络不会用到 + iccid:this.iccid, + + // 计量蜂窝网络中配合iccid联合使用。以太网，wifi网络单独使用。用于标记类型 + ident:this.ident, + + // 计量开始时间。例如M1、D1、Y1等 + periodDuration:this.periodDuration, + + // 发出警告的流量阈值 大于0的整数即可 + warningBytes:Number.parseInt(this.warningBytes), + + // 流量设置的配额 大于0的整数即可 + limitBytes:Number.parseInt(this.limitBytes), + + // 是否为计量网络 true为计量网络 false为非计量网络 + metered:Boolean(Number.parseInt(this.metered)), + + // 到达流量限制后的动作 详见[LimitAction](../reference/apis/js-apis-net-policy.md#limitaction) + limitAction:Number.parseInt(this.limitAction) + }; + this.netQuotaPolicyList.push(param); + }, + + // 订阅计量网络iface发生改变时的回调 + policy.on('netMeteredIfacesChange', (data) => { + this.log('on netMeteredIfacesChange：' + JSON.stringify(data)); + }); + + // 订阅计量网络策略发生改变时的回调 + policy.on('netQuotaPolicyChange', (data) => { + this.log('on netQuotaPolicyChange：' + JSON.stringify(data)); + }); + + // 调用setNetQuotaPolicies方法，设置计量网络策略 + setNetQuotaPolicies(){ + this.dialogType = DialogType.HIDE; + policy.setNetQuotaPolicies(this.netQuotaPolicyList, (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data))； + }); + }, + + // 调用getNetQuotaPolicies方法，获取计量网络策略 + getNetQuotaPolicies(){ + policy.getNetQuotaPolicies((err, data) => { + this.callBack(err, data); + if(data){ + this.netQuotaPolicyList = data; + } + }); + }, + + // 取消订阅计量网络iface发生改变时的回调 + policy.off('netMeteredIfacesChange', (data) => { + this.log('off netMeteredIfacesChange：' + JSON.stringify(data)); + }); + + // 取消订阅计量网络策略发生改变时的回调 + policy.off('netQuotaPolicyChange', (data) => { + this.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) => { + this.log('on netBackgroundPolicyChange：' + JSON.stringify(data)); + }); + + // 调用setBackgroundAllowed方法，设置开启后台省流量或关闭后台省流量 + setBackgroundAllowed() { + policy.setBackgroundAllowed(Boolean(Number.parseInt(this.isBoolean)), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 调用isBackgroundAllowed方法，获取后台网络限制状态（省流量）是开启还是关闭。 + isBackgroundAllowed() { + policy.isBackgroundAllowed((err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 调用getBackgroundPolicyByUid方法，获取指定uid在后台状态下能否访问网络。 + getBackgroundPolicyByUid() { + policy.getBackgroundPolicyByUid(Number.parseInt(this.firstParam), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 取消订阅后台网络策略发生改变时的回调 + policy.off('netBackgroundPolicyChange', (data) => { + this.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) => { + this.log('on netUidPolicyChange：' + JSON.stringify(data)); + }); + + // 订阅uid的rule发生改变时的回调 + policy.on('netUidRuleChange', (data) => { + this.log('on netUidRuleChange：' + JSON.stringify(data)); + }); + + // 调用setPolicyByUid方法，设置指定uid是否可以访问后台网络 + setPolicyByUid() { + let param = { + uid: Number.parseInt(this.firstParam), policy: Number.parseInt(this.currentNetUidPolicy) + } + policy.setPolicyByUid(Number.parseInt(this.firstParam), Number.parseInt(this.currentNetUidPolicy), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 调用getPolicyByUid方法，获取指定uid的策略 + getPolicyByUid() { + policy.getPolicyByUid(Number.parseInt(this.firstParam), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 调用getUidsByPolicy方法，获取使用指定策略的uids + getUidsByPolicy(){ + policy.getUidsByPolicy(Number.parseInt(this.currentNetUidPolicy), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 取消订阅uid的policy发生改变时的回调 + policy.off('netUidPolicyChange', (data) => { + this.log('off netUidPolicyChange：' + JSON.stringify(data)); + }); + + // 取消订阅uid的rule发生改变时的回调 + policy.off('netUidRuleChange', (data) => { + this.log('off netUidRuleChange：' + JSON.stringify(data)); + }); + +``` + +## 重置网络策略 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用restoreAllPolicies方法，重置网络策略。 + +```js + // 引入包名 + import policy from '@ohos.net.policy' + + // 调用restoreAllPolicies方法，重置网络策略 + restoreAllPolicies(){ + policy.restoreAllPolicies(this.firstParam, (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, +``` + +## 判断uid能否访问计量/非计量网络 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用isUidNetAllowed方法，获取uid能否访问计量/非计量网络。 + +```js + // 引入包名 + import policy from '@ohos.net.policy' + + // 调用isUidNetAllowed方法，获取uid能否访问计量/非计量网络 + isUidNetAllowedIsMetered(){ + let param = { + uid: Number.parseInt(this.firstParam), isMetered: Boolean(Number.parseInt(this.isBoolean)) + } + policy.isUidNetAllowed(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean)), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, +``` + +## 将对应uid从休眠白名单里添加、移除/获取休眠模式的白名单列表 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用setDeviceIdleAllowList方法，设置uid是否添加到休眠模式白名单。 + +3. 调用getDeviceIdleAllowList方法，获取添加在休眠模式白名单的uids。 + +```js + // 引入包名 + import policy from '@ohos.net.policy' + + // 调用setDeviceIdleAllowList方法，设置uid是否添加到休眠模式白名单 + setDeviceIdleAllowList(){ + let param = { + uid: Number.parseInt(this.firstParam), isAllowed: Boolean(Number.parseInt(this.isBoolean)) + } + policy.setDeviceIdleAllowList(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean)), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 调用getDeviceIdleAllowList方法，获取添加在休眠模式白名单的uids + getDeviceIdleAllowList(){ + policy.getDeviceIdleAllowList((err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, +``` + +## 将对应uid从省电白名单里添加、移除/获取省电模式的白名单列表 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 +2. 调用setPowerSaveAllowList方法，设置uid是否添加到省电模式白名单。 +3. 调用getPowerSaveAllowList方法，获取添加在省电模式白名单的uids。 + +```js + // 引入包名 + import policy from '@ohos.net.policy' + + // 调用setPowerSaveAllowList方法，设置uid是否添加到省电模式白名单 + setPowerSaveAllowList(){ + let param = { + uid: Number.parseInt(this.firstParam), isAllowed: Boolean(Number.parseInt(this.isBoolean)) + } + policy.setPowerSaveAllowList(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean)), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, + + // 调用getPowerSaveAllowList方法，获取添加在省电模式白名单的uids + getPowerSaveAllowList(){ + policy.getPowerSaveAllowList((err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, +``` + +## 更新网络提醒策略 + +### 开发步骤 + +1. 从@ohos.net.policy.d.ts中导入policy命名空间。 + +2. 调用updateRemindPolicy，更新网络提醒策略。 + +```js + // 引入包名 + import policy from '@ohos.net.policy' + + // 调用updateRemindPolicy，更新网络提醒策略 + updateRemindPolicy() { + let param = { + netType: Number.parseInt(this.netType), iccid: this.firstParam, remindType: this.currentRemindType + } + policy.updateRemindPolicy(Number.parseInt(this.netType), this.firstParam, Number.parseInt(this.currentRemindType), (err, data) => { + console.log(JSON.stringify(err))； + console.log(JSON.stringify(data)) + }); + }, +``` \ No newline at end of file diff --git a/zh-cn/application-dev/connectivity/net-sharing.md b/zh-cn/application-dev/connectivity/net-sharing.md new file mode 100644 index 0000000000..376e31df29 --- /dev/null +++ b/zh-cn/application-dev/connectivity/net-sharing.md @@ -0,0 +1,141 @@ +# 网络共享 + +## 简介 +网络共享管理分享设备已有网络给其他连接设备，支持Wi-Fi热点共享、蓝牙共享和USB共享，同时提供网络共享状态、共享流量查询功能。 + +> **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 基本概念 +- WIFI共享：通过WIFI热点共享网络。 +- 蓝牙共享：通过蓝牙共享网络。 +- USB共享：通过USB共享网络。 + +## 约束 +- 开发语言：C++ JS +- 系统：linux内核 + +## 场景介绍 +网络共享的典型场景有： +- 开启网络共享 +- 停止网络共享 +- 获取共享网络的数据流量 + +以下分别介绍具体开发方式。 +## 接口说明 +完整的JS API说明以及实例代码请参考：[网络共享](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-net-sharing.md)。 + +| 类型 | 接口 | 功能说明 | +| ---- | ---- | ---- | +| ohos.net.sharing | function isSharingSupported(callback: AsyncCallback\): void; | 获取当前系统是否支持网络共享，使用callback方式作为异步方法 | +| ohos.net.sharing | function isSharingSupported(): Promise\; | 获取当前系统是否支持网络共享，使用Promise方式作为异步方法 | +| ohos.net.sharing | function isSharing(callback: AsyncCallback\): void; | 获取当前共享状态，使用callback方式作为异步方法 | +| ohos.net.sharing | function isSharing(): Promise\; | 获取当前共享状态，使用Promise方式作为异步方法 | +| ohos.net.sharing | function startSharing(type: SharingIfaceType, callback: AsyncCallback\): void; | 开启共享，type为共享类型，目前支持Wifi热点、蓝牙、USB，使用callback方式作为异步方法 | +| ohos.net.sharing | function startSharing(type: SharingIfaceType): Promise\; | 开启共享，type为共享类型，目前支持Wifi热点、蓝牙、USB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function stopSharing(type: SharingIfaceType, callback: AsyncCallback\): void; | 停止指定类型共享，type为共享类型，包括Wifi热点、蓝牙、USB，使用callback方式作为异步方法 | +| ohos.net.sharing | function stopSharing(type: SharingIfaceType): Promise\; | 停止指定类型共享，type为共享类型，包括Wifi热点、蓝牙、USB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function getStatsRxBytes(callback: AsyncCallback\): void; | 获取共享接收数据量，单位KB，使用callback方式作为异步方法 | +| ohos.net.sharing | function getStatsRxBytes(): Promise\; | 获取共享接收数据量，单位KB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function getStatsTxBytes(callback: AsyncCallback\): void; | 获取共享发送数据量，单位KB，使用callback方式作为异步方法 | +| ohos.net.sharing | function getStatsTxBytes(): Promise\; | 获取共享发送数据量，单位KB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function getStatsTotalBytes(callback: AsyncCallback\): void; | 获取共享总数据流量，单位KB，使用callback方式作为异步方法 | +| ohos.net.sharing | function getStatsTotalBytes(): Promise\; | 获取共享总数据流量，单位KB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function getSharingIfaces(state: SharingIfaceState, callback: AsyncCallback\>): void; | 获取指定状态的网卡名称，state为状态，包括正在共享、可共享、共享错误，使用callback方式作为异步方法 | +| ohos.net.sharing | function getSharingIfaces(state: SharingIfaceState): Promise\>; | 获取指定状态的网卡名称，state为状态，包括正在共享、可共享、共享错误，使用Promise方式作为异步方法 | +| ohos.net.sharing | function getSharingState(type: SharingIfaceType, callback: AsyncCallback\): void; | 获取指定类型共享状态，type为类型，目前支持Wifi热点、蓝牙、USB，使用callback方式作为异步方法 | +| ohos.net.sharing | function getSharingState(type: SharingIfaceType): Promise\; | 获取指定类型共享状态，type为类型，目前支持Wifi热点、蓝牙、USB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function getSharableRegexes(type: SharingIfaceType, callback: AsyncCallback\>): void; | 获取与指定类型匹配的网卡正则表达式列表，type为类型，目前支持Wifi热点、蓝牙、USB，使用callback方式作为异步方法 | +| ohos.net.sharing | function getSharableRegexes(type: SharingIfaceType): Promise\>; | 获取与指定类型匹配的网卡正则表达式列表，type为类型，目前支持Wifi热点、蓝牙、USB，使用Promise方式作为异步方法 | +| ohos.net.sharing | function on(type: 'sharingStateChange', callback: Callback\): void; | 注册共享状态改变监听，返回网络共享的状态。 | +| ohos.net.sharing | function off(type: 'sharingStateChange', callback?: Callback\): void; | 注销共享状态改变监听，返回网络共享的状态。 | +| ohos.net.sharing | unction on(type: 'interfaceSharingStateChange', callback: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void; | 注册指定网卡共享状态改变监听 | +| ohos.net.sharing | function off(type: 'interfaceSharingStateChange', callback?: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void; | 注销指定网卡共享状态改变监听 | +| ohos.net.sharing | function on(type: 'sharingUpstreamChange', callback: Callback\): void; | 注册上行网卡改变监听 | +| ohos.net.sharing | function off(type: 'sharingUpstreamChange', callback?: Callback\): void; | 注销上行网卡改变监听 | + +## 开启网络共享 + +### 开发步骤 + +1. 从@ohos.net.sharing中导入sharing命名空间。 +2. 注册监听共享状态的改变。 +3. 调用startSharing方法，来开启指定类型共享。 +4. 接收到共享状态开启的回调，开启共享成功。 + +```js + // 从@ohos.net.sharing中导入sharing命名空间 + import sharing from '@ohos.net.sharing' + + // 注册监听共享状态的改变 + sharing.on('sharingStateChange', (error, data) => { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); + }); + + // 调用startSharing方法，来开启指定类型共享 + sharing.startSharing(SharingIfaceType.SHARING_WIFI, (error) => { + console.log(JSON.stringify(error)); + }); +``` + +## 停止网络共享 + +### 开发步骤 + +1. 从@ohos.net.sharing中导入sharing命名空间。 +2. 注册监听共享状态的改变。 +3. 调用stopSharing方法，来停止指定类型共享。 +4. 接收到共享状态关闭的回调，停止共享成功。 + +```js + // 从@ohos.net.sharing中导入sharing命名空间 + import sharing from '@ohos.net.sharing' + + // 注册监听共享状态的改变 + sharing.on('sharingStateChange', (error, data) => { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); + }); + + // 调用stopSharing方法，来停止指定类型共享 + sharing.stopSharing(SharingIfaceType.SHARING_WIFI, (error) => { + console.log(JSON.stringify(error)); + }); +``` + +## 获取共享网络的数据流量 + +### 开发步骤 + +1. 从@ohos.net.sharing中导入sharing命名空间。 +2. 调用startSharing方法，来开启指定类型共享。 +3. 调用getStatsTotalBytes方法，来获取共享网络数据量。 +4. 调用stopSharing方法，来停止指定类型共享，共享网络数据量清零。 + +```js + // 从@ohos.net.sharing中导入sharing命名空间 + import sharing from '@ohos.net.sharing' + + // 调用startSharing方法，来开启指定类型共享 + sharing.startSharing(SharingIfaceType.SHARING_WIFI, (error) => { + console.log(JSON.stringify(error)); + }); + + // 调用getStatsTotalBytes方法，来获取共享网络数据量 + sharing.getStatsTotalBytes((error, data) => { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); + }); + + // 调用stopSharing方法，来停止指定类型共享，共享网络数据量清零 + sharing.stopSharing(SharingIfaceType.SHARING_WIFI, (error) => { + console.log(JSON.stringify(error)); + }); + + // 再次调用getStatsTotalBytes方法，共享网络数据量已清零 + sharing.getStatsTotalBytes((error, data) => { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); + }); +``` diff --git a/zh-cn/application-dev/connectivity/socket-connection.md b/zh-cn/application-dev/connectivity/socket-connection.md index 815b0fde28..3d6e77fdeb 100644 --- a/zh-cn/application-dev/connectivity/socket-connection.md +++ b/zh-cn/application-dev/connectivity/socket-connection.md @@ -1,13 +1,27 @@ # Socket连接 +## 简介 + +Socket连接主要是通过Socket进行数据传输，支持TCP/UDP/TLS协议。 + +## 基本概念 + +- Socket：套接字，就是对网络中不同主机上的应用进程之间进行双向通信的端点的抽象。 +- TCP：传输控制协议(Transmission Control Protocol)。是一种面向连接的、可靠的、基于字节流的传输层通信协议。 +- UDP：用户数据报协议协议(User Datagram Protocol)。是一个简单的面向消息的传输层，不需要连接。 +- TLS：安全传输层协议(Transport Layer Security)。用于在两个通信应用程序之间提供保密性和数据完整性。 ## 场景介绍 -应用通过Socket进行数据传输，支持TCP和UDP两种协议。 +应用通过Socket进行数据传输，支持TCP/UDP/TLS协议。主要场景有： +- 应用通过TCP/UDP Socket进行数据传输 +- 应用通过TLS Socket进行加密数据传输 ## 接口说明 +完整的JS API说明以及实例代码请参考：[Socket连接](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-socket.md)。 + Socket连接主要由socket模块提供。具体接口说明如下表。 | 接口名 | 功能描述 | @@ -31,8 +45,32 @@ Socket连接主要由socket模块提供。具体接口说明如下表。 | on(type: 'connect') | 订阅TCPSocket的连接事件（仅TCP支持）。 | | off(type: 'connect') | 取消订阅TCPSocket的连接事件（仅TCP支持）。 | +TLS Socket连接主要由tls_socket模块提供。具体接口说明如下表。 -## 开发步骤 +| 接口名 | 功能描述 | +| -------- | -------- | +| bind() | 绑定IP地址和端口号。 | +| close(type: 'error') | 关闭连接。 | +| connect() | 连接到指定的IP地址和端口。 | +| getCertificate() | 返回表示本地证书的对象。 | +| getCipherSuite() | 返回包含协商的密码套件信息的列表。 | +| getProtocol() | 返回包含当前连接协商的SSL/TLS协议版本的字符串。 | +| getRemoteAddress() | 获取TLSSocket连接的对端地址。 | +| getRemoteCertificate() | 返回表示对等证书的对象。 | +| getSignatureAlgorithms() | 在服务器和客户端之间共享的签名算法列表，按优先级降序排列。 | +| getState() | 获取TLSSocket连接的状态。 | +| off(type: 'close') | 取消订阅TLSSocket连接的关闭事件。 | +| off(type: 'error') | 取消订阅TLSSocket连接的Error事件。 | +| off(type: 'message') | 取消订阅TLSSocket连接的接收消息事件。 | +| on(type: 'close') | 订阅TLSSocket连接的关闭事件。 | +| on(type: 'error') | 订阅TLSSocket连接的Error事件。 | +| on(type: 'message') | 订阅TLSSocket连接的接收消息事件。 | +| send() | 发送数据。 | +| setExtraOptions() | 设置TLSSocket连接的其他属性。 | + +## 应用TCP/UDP协议进行通信 + +### 开发步骤 UDP与TCP流程大体类似，下面以TCP为例： @@ -49,13 +87,13 @@ UDP与TCP流程大体类似，下面以TCP为例： 6. 发送数据。 7. Socket连接使用完毕后，主动关闭。 - + ```js import socket from '@ohos.net.socket' - + // 创建一个TCPSocket连接，返回一个TCPSocket对象。 let tcp = socket.constructTCPSocketInstance(); - + // 订阅TCPSocket相关的订阅事件 tcp.on('message', value => { console.log("on message") @@ -73,7 +111,7 @@ UDP与TCP流程大体类似，下面以TCP为例： tcp.on('close', () => { console.log("on close") }); - + // 绑定本地IP地址和端口。 let bindAddress = { address: '192.168.xx.xx', @@ -86,6 +124,7 @@ UDP与TCP流程大体类似，下面以TCP为例： return; } console.log('bind success'); + // 连接到指定的IP地址和端口。 let connectAddress = { address: '192.168.xx.xx', @@ -100,6 +139,7 @@ UDP与TCP流程大体类似，下面以TCP为例： return; } console.log('connect success'); + // 发送数据 tcp.send({ data: 'Hello, server!' @@ -112,6 +152,7 @@ UDP与TCP流程大体类似，下面以TCP为例： }) }); }); + // 连接使用完毕后，主动关闭。取消相关事件的订阅。 setTimeout(() => { tcp.close((err) => { @@ -123,8 +164,166 @@ UDP与TCP流程大体类似，下面以TCP为例： }, 30 * 1000); ``` +## 应用通过TLS Socket进行加密数据传输 + +### 开发步骤 + +客户端TLS Socket流程： + +1. import需要的socket模块。 + +2. 绑定服务器IP和端口号。 + +3. 双向认证上传客户端CA证书及数字证书；单向认证上传客户端CA证书。 + +4. 创建一个TLSSocket连接，返回一个TLSSocket对象。 + +5. （可选）订阅TLSSocket相关的订阅事件。 + +6. 发送数据。 + +7. TLSSocket连接使用完毕后，主动关闭。 + +```js + import socket from '@ohos.net.socket' + + // 创建一个（双向认证）TLS Socket连接，返回一个TLS Socket对象。 + let tlsTwoWay = socket.constructTLSSocketInstance(); + + // 订阅TLS Socket相关的订阅事件 + tcp.on('message', value => { + console.log("on message") + let buffer = value.message + let dataView = new DataView(buffer) + let str = "" + for (let i = 0; i < dataView.byteLength; ++i) { + str += String.fromCharCode(dataView.getUint8(i)) + } + console.log("on connect received:" + str) + }); + tcp.on('connect', () => { + console.log("on connect") + }); + tcp.on('close', () => { + console.log("on close") + }); + + // 绑定本地IP地址和端口。 + tlsTwoWay.bind({address: '192.168.xxx.xxx', port: xxxx, family: 1}, err => { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + }); + + // 设置通信过程中使用参数 + let options = { + ALPNProtocols: ["spdy/1", "http/1.1"], + + // 连接到指定的IP地址和端口。 + address: { + address: "192.168.xx.xxx", + port: xxxx, // 端口 + family: 1, + }, + + // 设置用于通信过程中完成校验的参数。 + secureOptions: { + key: "xxxx", // 密钥 + cert: "xxxx", // 数字证书 + ca: ["xxxx"], // CA证书 + passwd: "xxxx", // 生成密钥时的密码 + protocols: [socket.Protocol.TLSv12], // 通信协议 + useRemoteCipherPrefer: true, // 是否优先使用对端密码套件 + signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256", // 签名算法 + cipherSuite: "AES256-SHA256", // 密码套件 + }, + }; + + // 建立连接 + tlsTwoWay.connect(options, (err, data) => { + console.error(err); + console.log(data); + }); + + // 连接使用完毕后，主动关闭。取消相关事件的订阅。 + tls.close((err) => { + if (err) { + console.log("close callback error = " + err); + } else { + console.log("close success"); + } + tls.off('message'); + tls.off('connect'); + tls.off('close'); + }); + + // 创建一个（单向认证）TLS Socket连接，返回一个TLS Socket对象。 + let tlsOneWay = socket.constructTLSSocketInstance(); // One way authentication + + // 订阅TLS Socket相关的订阅事件 + tcp.on('message', value => { + console.log("on message") + let buffer = value.message + let dataView = new DataView(buffer) + let str = "" + for (let i = 0;i < dataView.byteLength; ++i) { + str += String.fromCharCode(dataView.getUint8(i)) + } + console.log("on connect received:" + str) + }); + tcp.on('connect', () => { + console.log("on connect") + }); + tcp.on('close', () => { + console.log("on close") + }); + + // 绑定本地IP地址和端口。 + tlsOneWay.bind({address: '192.168.xxx.xxx', port: xxxx, family: 1}, err => { + if (err) { + console.log('bind fail'); + return; + } + console.log('bind success'); + }); + + // 设置通信过程中使用参数 + let oneWayOptions = { + address: { + address: "192.168.xxx.xxx", + port: xxxx, + family: 1, + }, + secureOptions: { + ca: ["xxxx","xxxx"], // CA证书 + cipherSuite: "AES256-SHA256", // 密码套件 + }, + }; + + // 建立连接 + tlsOneWay.connect(oneWayOptions, (err, data) => { + console.error(err); + console.log(data); + }); + + // 连接使用完毕后，主动关闭。取消相关事件的订阅。 + tls.close((err) => { + if (err) { + console.log("close callback error = " + err); + } else { + console.log("close success"); + } + tls.off('message'); + tls.off('connect'); + tls.off('close'); + }); +``` + ## 相关实例 + 针对Socket连接开发，有以下相关实例可供参考： - [`Socket`：Socket 连接（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/Network/Socket) - [使用UDP实现与服务端通信（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/UdpDemoOH) -- [使用TCP实现与服务端通信（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/TcpSocketDemo) \ No newline at end of file +- [使用TCP实现与服务端通信（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/TcpSocketDemo) diff --git a/zh-cn/application-dev/reference/apis/js-apis-http.md b/zh-cn/application-dev/reference/apis/js-apis-http.md index 16696b77fd..d9378e76a1 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-http.md +++ b/zh-cn/application-dev/reference/apis/js-apis-http.md @@ -440,7 +440,7 @@ request方法回调函数的返回值类型。 | resultType9+ | [HttpDataType](#httpdatatype9) | 是 | 返回值类型。 | | responseCode | [ResponseCode](#responsecode) \| number | 是 | 回调函数执行成功时，此字段为[ResponseCode](#responsecode)。若执行失败，错误码将会从AsyncCallback中的err字段返回。错误码参考[Response错误码](#response常用错误码)。 | | header | Object | 是 | 发起HTTP请求返回来的响应头。当前返回的是JSON格式字符串，如需具体字段内容，需开发者自行解析。常见字段及解析方式如下：
- Content-Type：header['Content-Type']；
- Status-Line：header['Status-Line']；
- Date：header.Date/header['Date']；
- Server：header.Server/header['Server']； | -| cookies8+ | Array\ | 是 | 服务器返回的 cookies。 | +| cookies8+ | string | 是 | 服务器返回的 cookies。 | ## http.createHttpResponseCache9+ diff --git a/zh-cn/application-dev/reference/apis/js-apis-net-connection.md b/zh-cn/application-dev/reference/apis/js-apis-net-connection.md index 4b02345124..ced01bba2f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-net-connection.md +++ b/zh-cn/application-dev/reference/apis/js-apis-net-connection.md @@ -1,9 +1,8 @@ -# @ohos.net.connection (网络连接管理) +# 网络连接管理 网络连接管理提供管理网络一些基础能力，包括获取默认激活的数据网络、获取所有激活数据网络列表、开启关闭飞行模式、获取网络能力信息等功能。 -> **说明：** -> +> ![](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 @@ -11,6 +10,40 @@ ```js import connection from '@ohos.net.connection' ``` +## connection.createNetConnection + +createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection + +返回一个NetConnection对象，netSpecifier指定关注的网络的各项特征，timeout是超时时间(单位是毫秒)，netSpecifier是timeout的必要条件，两者都没有则表示关注默认网络。 + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| netSpecifier | [NetSpecifier](#netspecifier) | 否 | 指定网络的各项特征，不指定则关注默认网络。 | +| timeout | number | 否 | 获取netSpecifier指定的网络时的超时时间，仅netSpecifier存在时生效。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------- | -------------------- | +| [NetConnection](#netconnection) | 所关注的网络的句柄。 | + +**示例：** + +```js +// 关注默认网络 +let netConnection = connection.createNetConnection() + +// 关注蜂窝网络 +let netConnectionCellular = connection.createNetConnection({ + netCapabilities: { + bearerTypes: [connection.NetBearType.BEARER_CELLULAR] + } +}) +``` ## connection.getDefaultNet @@ -26,14 +59,22 @@ getDefaultNet(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\<[NetHandle](#nethandle)> | 是 | 回调函数。 | +| callback | AsyncCallback\<[NetHandle](#nethandle)> | 是 | 回调函数。当成功获取默认激活的数据网络时，err为undefined，data为默认激活的数据网络；否则为错误对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -connection.getDefaultNet(function (error, netHandle) { +connection.getDefaultNet(function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(netHandle)) + console.log(JSON.stringify(data)) }) ``` @@ -53,85 +94,348 @@ getDefaultNet(): Promise\ | --------------------------------- | ------------------------------------- | | Promise\<[NetHandle](#nethandle)> | 以Promise形式返回默认激活的数据网络。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js -connection.getDefaultNet().then(function (netHandle) { - console.log(JSON.stringify(netHandle)) +connection.getDefaultNet().then(function (data) { + console.log(JSON.stringify(data)) }) ``` -## connection.getDefaultNetSync9+ +## connection.getGlobalHttpProxy10+ -getDefaultNetSync(): NetHandle; +getGlobalHttpProxy(callback: AsyncCallback\): void; -使用同步方法获取默认激活的数据网络。可以使用[getNetCapabilities](#connectiongetnetcapabilities)去获取网络的类型、拥有的能力等信息。 +获取网络的全局代理配置信息，使用callback方式作为异步方法。 -**需要权限**：ohos.permission.GET_NETWORK_INFO +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ---------------- | +| callback | AsyncCallback\<[HttpProxy](#httpproxy)> | 是 | 回调函数。当成功获取网络的全局代理配置信息时，err为undefined，data为网络的全局代理配置信息；否则为错误对象| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.getGlobalHttpProxy((error,data) => { + console.info(JSON.stringify(error)); + console.info(JSON.stringify(data)); +}) +``` + +## connection.getGlobalHttpProxy10+ + +getGlobalHttpProxy(): Promise\; + +获取网络的全局代理配置信息，使用Promise方式作为异步方法。 **系统能力**：SystemCapability.Communication.NetManager.Core **返回值：** -| 类型 | 说明 | -| --------- | ---------------------------------- | -| NetHandle | 以同步方式返回默认激活的数据网络。 | +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\<[HttpProxy](#httpproxy)> | 以Promise形式返回网络的全局代理配置信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -let netHandle = connection.getDefaultNetSync(); +connection.getGlobalHttpProxy().then((data) => { + console.info(JSON.stringify(data)); +}).catch(error => { + console.info(JSON.stringify(error)); +}) ``` -## connection.hasDefaultNet +## connection.setGlobalHttpProxy10+ -hasDefaultNet(callback: AsyncCallback\): void +setGlobalHttpProxy(httpProxy: HttpProxy, callback: AsyncCallback\): void; -检查默认数据网络是否被激活，使用callback方式作为异步方法。如果有默认数据网路，可以使用[getDefaultNet](#connectiongetdefaultnet)去获取。 +设置网络全局Http代理配置信息，使用callback方式作为异步方法。 -**需要权限**：ohos.permission.GET_NETWORK_INFO +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL **系统能力**：SystemCapability.Communication.NetManager.Core **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ---- | -------------------------------------- | -| callback | AsyncCallback\ | 是 | 回调函数，默认数据网络被激活返回true。 | +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ---------------- | +| httpProxy | [HttpProxy](#httpproxy) | 是 | 网络全局Http代理配置信息 | +| callback | AsyncCallback\ | 是 | 回调函数。当成功设置网络全局Http代理配置信息时，err为undefined，否则为错误对象| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -connection.hasDefaultNet(function (error, has) { - console.log(JSON.stringify(error)) - console.log('has: ' + has) +let ExclusionList="" +let array = ExclusionList.split(','); +let httpProxy = { + host: "host", + port: 1, + parsedExclusionList: array +} +connection.setGlobalHttpProxy(httpProxy, (error, data) => { + console.info(JSON.stringify(error)); + console.info(JSON.stringify(data)); +}); +``` + +## connection.setGlobalHttpProxy10+ + +setGlobalHttpProxy(httpProxy: HttpProxy): Promise\; + +设置网络全局Http代理配置信息，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ---------------- | +| httpProxy | [HttpProxy](#httpproxy) | 是 | 网络全局Http代理配置信息。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------- | ----------------------------- | +| Promise\ | 无返回值的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let ExclusionList="" +let array = ExclusionList.split(','); +let httpProxy = { + host: "host", + port: 1, + parsedExclusionList: array +} +connection.setGlobalHttpProxy(httpProxy).then((error, data) => { + console.info(JSON.stringify(data)); +}).catch(error=>{ + console.info(JSON.stringify(error)); }) ``` -## connection.hasDefaultNet +## connection.getAppNet9+ -hasDefaultNet(): Promise\ +getAppNet(callback: AsyncCallback\): void; -检查默认数据网络是否被激活，使用Promise方式作为异步方法。如果有默认数据网路，可以使用[getDefaultNet](#connectiongetdefaultnet)去获取。 +获取App绑定的网络信息，使用callback方式作为异步方法。 -**需要权限**：ohos.permission.GET_NETWORK_INFO +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ---------------- | +| callback | AsyncCallback\<[NetHandle](#nethandle)> | 是 | 回调函数。当成功获取App绑定的网络信息时，err为undefined，data为获取到App绑定的网络信息；否则为错误对象| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.getAppNet(function(error, data)) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +} +``` + +## connection.getAppNet9+ + +getAppNet(): Promise\; + +获取App绑定的网络信息，使用Promise方式作为异步方法。 **系统能力**：SystemCapability.Communication.NetManager.Core **返回值：** -| 类型 | 说明 | -| ----------------- | ----------------------------------------------- | -| Promise\ | 以Promise形式返回，默认数据网络被激活返回true。 | +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\<[NetHandle](#nethandle)> | 以Promise形式返回App绑定的网络信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -connection.hasDefaultNet().then(function (has) { - console.log('has: ' + has) +connection.getAppNet().then((data) => { + console.info(JSON.stringify(data)); +}).catch(error => { + console.info(JSON.stringify(error)); }) ``` +## connection.SetAppNet9+ + +setAppNet(netHandle: NetHandle, callback: AsyncCallback\): void; + +绑定App到指定网络，绑定后的App只能通过指定网络访问外网，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ---------------- | +| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | +| callback | AsyncCallback\ | 是 | 回调函数。当成功绑定App到指定网络时，err为undefined，否则为错误对象| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.getDefaultNet(function (error, netHandle) { + connection.setAppNet(netHandle, (error, data) => { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) + }); +}) +``` + +## connection.SetAppNet9+ + +setAppNet(netHandle: NetHandle): Promise\; + +绑定App到指定网络，绑定后的App只能通过指定网络访问外网，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.INTERNET + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ---------------- | +| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------- | ----------------------------- | +| Promise\ | 无返回值的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.getDefaultNet().then(function (netHandle) { + connection.setAppNet(netHandle).then((error, data) => { + console.log(JSON.stringify(data)) + }).catch(error => { + console.log(JSON.stringify(error)) + }) +}) +``` + +## connection.getDefaultNetSync9+ + +getDefaultNetSync(): NetHandle; + +使用同步方法获取默认激活的数据网络。可以使用[getNetCapabilities](#connectiongetnetcapabilities)去获取网络的类型、拥有的能力等信息。 + +**需要权限**：ohos.permission.GET_NETWORK_INFO + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------- | +| NetHandle | 以同步方式返回默认激活的数据网络。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let netHandle = connection.getDefaultNetSync(); +``` + ## connection.getAllNets getAllNets(callback: AsyncCallback<Array<NetHandle>>): void @@ -146,14 +450,22 @@ getAllNets(callback: AsyncCallback<Array<NetHandle>>): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<Array<[NetHandle](#nethandle)>> | 是 | 回调函数。 | +| callback | AsyncCallback<Array<[NetHandle](#nethandle)>> | 是 | 回调函数。当成功获取所有处于连接状态的网络列表时，err为undefined，data为激活的数据网络列表；否则为错误对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -connection.getAllNets(function (error, nets) { +connection.getAllNets(function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(nets)) + console.log(JSON.stringify(data)) }); ``` @@ -173,11 +485,19 @@ getAllNets(): Promise<Array<NetHandle>> | -------- | -------- | | Promise<Array<[NetHandle](#nethandle)>> | 以Promise形式返回激活的数据网络列表。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js -connection.getAllNets().then(function (nets) { - console.log(JSON.stringify(nets)) +connection.getAllNets().then(function (data) { + console.log(JSON.stringify(data)) }); ``` @@ -196,15 +516,25 @@ getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback\ | 是 | 回调函数。 | +| callback | AsyncCallback\<[ConnectionProperties](#connectionproperties)> | 是 | 回调函数。当成功获取netHandle对应的网络的连接信息时，err为undefined，data为获取的网络连接信息；否则为错误对象| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js connection.getDefaultNet().then(function (netHandle) { - connection.getConnectionProperties(netHandle, function (error, info) { + connection.getConnectionProperties(netHandle, function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(info)) + console.log(JSON.stringify(data)) }) }) ``` @@ -231,12 +561,22 @@ getConnectionProperties(netHandle: NetHandle): Promise\ | ------------------------------------------------------- | --------------------------------- | | Promise\<[ConnectionProperties](#connectionproperties)> | 以Promise形式返回网络的连接信息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js connection.getDefaultNet().then(function (netHandle) { - connection.getConnectionProperties(netHandle).then(function (info) { - console.log(JSON.stringify(info)) + connection.getConnectionProperties(netHandle).then(function (data) { + console.log(JSON.stringify(data)) }) }) ``` @@ -256,15 +596,25 @@ getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback\ | 是 | 回调函数。 | +| callback | AsyncCallback\<[NetCapabilities](#netcapabilities)> | 是 | 回调函数。当成功获取netHandle对应的网络的能力信息时，err为undefined，data为获取到的网络能力信息；否则为错误对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js connection.getDefaultNet().then(function (netHandle) { - connection.getNetCapabilities(netHandle, function (error, info) { + connection.getNetCapabilities(netHandle, function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(info)) + console.log(JSON.stringify(data)) }) }) ``` @@ -291,12 +641,22 @@ getNetCapabilities(netHandle: NetHandle): Promise\ | --------------------------------------------- | --------------------------------- | | Promise\<[NetCapabilities](#netcapabilities)> | 以Promise形式返回网络的能力信息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js connection.getDefaultNet().then(function (netHandle) { - connection.getNetCapabilities(netHandle).then(function (info) { - console.log(JSON.stringify(info)) + connection.getNetCapabilities(netHandle).then(function (data) { + console.log(JSON.stringify(data)) }) }) ``` @@ -315,14 +675,22 @@ isDefaultNetMetered(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------- | ---- | -------------------------------------- | -| callback | AsyncCallback\ | 是 | 回调函数，当前网络上的数据流量使用被计量返回true。 | +| callback | AsyncCallback\ | 是 | 回调函数。当前网络上的数据流量使用被计量返回true。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -connection.isDefaultNetMetered(function (error, has) { +connection.isDefaultNetMetered(function (error, data) { console.log(JSON.stringify(error)) - console.log('has: ' + has) + console.log('data: ' + data) }) ``` @@ -342,11 +710,208 @@ isDefaultNetMetered(): Promise\ | ----------------- | ----------------------------------------------- | | Promise\ | 以Promise形式返回，当前网络上的数据流量使用被计量true。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.isDefaultNetMetered().then(function (data) { + console.log('data: ' + data) +}) +``` + +## connection.hasDefaultNet + +hasDefaultNet(callback: AsyncCallback\): void + +检查默认数据网络是否被激活，使用callback方式作为异步方法。如果有默认数据网路，可以使用[getDefaultNet](#connectiongetdefaultnet)去获取。 + +**需要权限**：ohos.permission.GET_NETWORK_INFO + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------------- | +| callback | AsyncCallback\ | 是 | 回调函数。默认数据网络被激活返回true。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.hasDefaultNet(function (error, data) { + console.log(JSON.stringify(error)) + console.log('data: ' + data) +}) +``` + +## connection.hasDefaultNet + +hasDefaultNet(): Promise\ + +检查默认数据网络是否被激活，使用Promise方式作为异步方法。如果有默认数据网路，可以使用[getDefaultNet](#connectiongetdefaultnet)去获取。 + +**需要权限**：ohos.permission.GET_NETWORK_INFO + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ----------------------------------------------- | +| Promise\ | 以Promise形式返回，默认数据网络被激活返回true。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.hasDefaultNet().then(function (data) { + console.log('data: ' + data) +}) +``` + +## connection.enableAirplaneMode + +enableAirplaneMode(callback: AsyncCallback\): void + +开启飞行模式，使用callback方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | ------------------ | +| callback | AsyncCallback\ | 是 | 回调函数。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js -connection.isDefaultNetMetered().then(function (has) { - console.log('has: ' + has) +connection.enableAirplaneMode(function (error) { + console.log(JSON.stringify(error)) +}) +``` + +## connection.enableAirplaneMode + +enableAirplaneMode(): Promise\ + +开启飞行模式，使用Promise方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------- | ----------------------------- | +| Promise\ | 无返回值的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.enableAirplaneMode().then(function (error) { + console.log(JSON.stringify(error)) +}) +``` + +## connection.disableAirplaneMode + +disableAirplaneMode(callback: AsyncCallback\): void + +关闭飞行模式，使用callback方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | ------------------ | +| callback | AsyncCallback\ | 是 | 回调函数。当关闭飞行模式成功，err为undefined，否则为错误对象。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.disableAirplaneMode(function (error) { + console.log(JSON.stringify(error)) +}) +``` + +## connection.disableAirplaneMode + +disableAirplaneMode(): Promise\ + +关闭飞行模式，使用Promise方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------- | ----------------------------- | +| Promise\ | 无返回值的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +connection.disableAirplaneMode().then(function (error) { + console.log(JSON.stringify(error)) }) ``` @@ -366,7 +931,17 @@ reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): v | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄，参考[NetHandle](#nethandle)。 | -| callback | AsyncCallback<void> | 是 | 回调函数。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当向网络管理报告网络处于可用状态成功，err为undefined，否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** @@ -400,6 +975,16 @@ reportNetConnected(netHandle: NetHandle): Promise<void> | -------- | -------- | | Promise<void> | 无返回值的Promise对象。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js @@ -426,7 +1011,17 @@ reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>) | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄，参考[NetHandle](#nethandle)。 | -| callback | AsyncCallback<void> | 是 | 回调函数。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当向网络管理报告网络处于不可用状态成功，err为undefined，否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** @@ -460,6 +1055,16 @@ reportNetDisconnected(netHandle: NetHandle): Promise<void> | -------- | -------- | | Promise<void> | 无返回值的Promise对象。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js @@ -485,15 +1090,25 @@ getAddressesByName(host: string, callback: AsyncCallback\>): | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------- | ---- | ------------------ | | host | string | 是 | 需要解析的主机名。 | -| callback | AsyncCallback\> | 是 | 回调函数。 | +| callback | AsyncCallback\> | 是 | 回调函数。当使用默认网络解析主机名成功获取所有IP地址，err为undefined，data为获取到的所有IP地址；否则为错误对象。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js let host = "xxxx"; -connection.getAddressesByName(host, function (error, addresses) { +connection.getAddressesByName(host, function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(addresses)) + console.log(JSON.stringify(data)) }) ``` @@ -519,156 +1134,102 @@ getAddressesByName(host: string): Promise\> | ------------------------------------------- | ----------------------------- | | Promise\> | 以Promise形式返回所有IP地址。 | -**示例：** - -```js -let host = "xxxx"; -connection.getAddressesByName(host).then(function (addresses) { - console.log(JSON.stringify(addresses)) -}) -``` - -## connection.enableAirplaneMode - -enableAirplaneMode(callback: AsyncCallback\): void - -开启飞行模式，使用callback方式作为异步方法。 - -**系统接口**：此接口为系统接口。 - -**系统能力**：SystemCapability.Communication.NetManager.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------- | ---- | ------------------ | -| callback | AsyncCallback\ | 是 | 回调函数。 | - -**示例：** - -```js -connection.enableAirplaneMode(function (error) { - console.log(JSON.stringify(error)) -}) -``` - -## connection.enableAirplaneMode - -enableAirplaneMode(): Promise\ - -开启飞行模式，使用Promise方式作为异步方法。 - -**系统接口**：此接口为系统接口。 - -**系统能力**：SystemCapability.Communication.NetManager.Core - -**返回值：** - -| 类型 | 说明 | -| ------------------------------------------- | ----------------------------- | -| Promise\ | 无返回值的Promise对象。 | - -**示例：** - -```js -connection.enableAirplaneMode().then(function (error) { - console.log(JSON.stringify(error)) -}) -``` - -## connection.disableAirplaneMode - -disableAirplaneMode(callback: AsyncCallback\): void - -关闭飞行模式，使用callback方式作为异步方法。 - -**系统接口**：此接口为系统接口。 - -**系统能力**：SystemCapability.Communication.NetManager.Core - -**参数：** +**错误码：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------- | ---- | ------------------ | -| callback | AsyncCallback\ | 是 | 回调函数。 | +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js -connection.disableAirplaneMode(function (error) { - console.log(JSON.stringify(error)) +let host = "xxxx"; +connection.getAddressesByName(host).then(function (data) { + console.log(JSON.stringify(data)) }) ``` -## connection.disableAirplaneMode +## NetConnection -disableAirplaneMode(): Promise\ +网络连接的句柄。 -关闭飞行模式，使用Promise方式作为异步方法。 +### register -**系统接口**：此接口为系统接口。 +register(callback: AsyncCallback\): void + +订阅指定网络状态变化的通知。 + +**需要权限**：ohos.permission.GET_NETWORK_INFO **系统能力**：SystemCapability.Communication.NetManager.Core -**返回值：** +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数。当订阅指定网络状态变化的通知成功，err为undefined，否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | +| 2101008 | The callback is not exists. | +| 2101022 | The number of requests exceeded the maximum. | -| 类型 | 说明 | -| ------------------------------------------- | ----------------------------- | -| Promise\ | 无返回值的Promise对象。 | **示例：** ```js -connection.disableAirplaneMode().then(function (error) { +netConnection.register(function (error) { console.log(JSON.stringify(error)) }) ``` -## connection.createNetConnection +### unregister -createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection +unregister(callback: AsyncCallback\): void -返回一个NetConnection对象，netSpecifier指定关注的网络的各项特征，timeout是超时时间(单位是毫秒)，netSpecifier是timeout的必要条件，两者都没有则表示关注默认网络。 +取消订阅默认网络状态变化的通知。 **系统能力**：SystemCapability.Communication.NetManager.Core **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | -| netSpecifier | [NetSpecifier](#netspecifier) | 否 | 指定网络的各项特征，不指定则关注默认网络。 | -| timeout | number | 否 | 获取netSpecifier指定的网络时的超时时间，仅netSpecifier存在时生效。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数。当取消订阅指定网络状态变化的通知成功，err为undefined，否则为错误对象。 | -**返回值：** +**错误码：** -| 类型 | 说明 | -| ------------------------------- | -------------------- | -| [NetConnection](#netconnection) | 所关注的网络的句柄。 | +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | +| 2101007 | The same callback exists. | **示例：** ```js -// 关注默认网络 -let netConnection = connection.createNetConnection() - -// 关注蜂窝网络 -let netConnectionCellular = connection.createNetConnection({ - netCapabilities: { - bearerTypes: [connection.NetBearType.BEARER_CELLULAR] - } +netConnection.unregister(function (error) { + console.log(JSON.stringify(error)) }) ``` -## NetConnection - -网络连接的句柄。 - ### on('netAvailable') on(type: 'netAvailable', callback: Callback\): void 订阅网络可用事件。 +**模型约束**：此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 + **系统能力**：SystemCapability.Communication.NetManager.Core **参数：** @@ -676,21 +1237,37 @@ on(type: 'netAvailable', callback: Callback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 订阅事件，固定为'netAvailable'。
netAvailable：数据网络可用事件。 | -| callback | Callback\<[NetHandle](#nethandle)> | 是 | 回调函数。 | +| callback | Callback\<[NetHandle](#nethandle)> | 是 | 回调函数，返回数据网络句柄。| **示例：** ```js -netConnection.on('netAvailable', function (data) { +// 创建NetConnection对象 +let netCon = connection.createNetConnection() + +// 先使用register接口注册订阅事件 +netCon.register(function (error) { + console.log(JSON.stringify(error)) +}) + +// 订阅网络可用事件。调用register后，才能接收到此事件通知 +netCon.on('netAvailable', function (data) { console.log(JSON.stringify(data)) }) + +// 使用unregister接口取消订阅 +netCon.unregister(function (error) { + console.log(JSON.stringify(error)) +}) ``` -### on('netCapabilitiesChange') +### on('netBlockStatusChange') -on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void +on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void -订阅网络能力变化事件。 +订阅网络阻塞状态事件，使用callback方式作为异步方法。 + +**模型约束**：此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 **系统能力**：SystemCapability.Communication.NetManager.Core @@ -698,22 +1275,38 @@ on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, net | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | string | 是 | 订阅事件，固定为'netCapabilitiesChange'。
netCapabilitiesChange：网络能力变化事件。 | -| callback | Callback<{ netHandle: [NetHandle](#nethandle), netCap: [NetCapabilities](#netcapabilities) }> | 是 | 回调函数。 | +| type | string | 是 | 订阅事件，固定为'netBlockStatusChange'。
netBlockStatusChange：网络阻塞状态事件。 | +| callback | Callback<{ netHandle: [NetHandle](#nethandle), blocked: boolean }> | 是 | 回调函数，返回数据网络句柄(netHandle),及网络堵塞状态(blocked)。| **示例：** ```js -netConnection.on('netCapabilitiesChange', function (data) { +// 创建NetConnection对象 +let netCon = connection.createNetConnection() + +// 先使用register接口注册订阅事件 +netCon.register(function (error) { + console.log(JSON.stringify(error)) +}) + +// 订阅网络阻塞状态事件。调用register后，才能接收到此事件通知 +netCon.on('netBlockStatusChange', function (data) { console.log(JSON.stringify(data)) }) + +// 使用unregister接口取消订阅 +netCon.unregister(function (error) { + console.log(JSON.stringify(error)) +}) ``` -### on('netConnectionPropertiesChange') +### on('netCapabilitiesChange') -on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void +on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void -订阅网络连接信息变化事件。 +订阅网络能力变化事件。 + +**模型约束**：此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 **系统能力**：SystemCapability.Communication.NetManager.Core @@ -721,22 +1314,38 @@ on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHan | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | string | 是 | 订阅事件，固定为'netConnectionPropertiesChange'。
netConnectionPropertiesChange：网络连接信息变化事件。 | -| callback | Callback<{ netHandle: [NetHandle](#nethandle), connectionProperties: [ConnectionProperties](#connectionproperties) }> | 是 | 回调函数。 | +| type | string | 是 | 订阅事件，固定为'netCapabilitiesChange'。
netCapabilitiesChange：网络能力变化事件。 | +| callback | Callback<{ netHandle: [NetHandle](#nethandle), netCap: [NetCapabilities](#netcapabilities) }> | 是 | 回调函数，返回数据网络句柄(netHandle)和网络的能力信息(netCap)。| **示例：** ```js -netConnection.on('netConnectionPropertiesChange', function (data) { +// 创建NetConnection对象 +let netCon = connection.createNetConnection() + +// 先使用register接口注册订阅事件 +netCon.register(function (error) { + console.log(JSON.stringify(error)) +}) + +// 订阅网络能力变化事件。调用register后，才能接收到此事件通知 +netCon.on('netCapabilitiesChange', function (data) { console.log(JSON.stringify(data)) }) + +// 使用unregister接口取消订阅 +netCon.unregister(function (error) { + console.log(JSON.stringify(error)) +}) ``` -### on('netBlockStatusChange') +### on('netConnectionPropertiesChange') -on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void +on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void -订阅网络阻塞状态事件，使用callback方式作为异步方法。 +订阅网络连接信息变化事件。 + +**模型约束**：此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 **系统能力**：SystemCapability.Communication.NetManager.Core @@ -744,15 +1353,29 @@ on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, b | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | string | 是 | 订阅事件，固定为'netBlockStatusChange'。
netBlockStatusChange：网络阻塞状态事件。 | -| callback | Callback<{ netHandle: [NetHandle](#nethandle), blocked: boolean }> | 是 | 回调函数。 | +| type | string | 是 | 订阅事件，固定为'netConnectionPropertiesChange'。
netConnectionPropertiesChange：网络连接信息变化事件。 | +| callback | Callback<{ netHandle: [NetHandle](#nethandle), connectionProperties: [ConnectionProperties](#connectionproperties) }> | 是 | 回调函数，返回数据网络句柄(netHandle)和网络的连接信息(connectionProperties)| **示例：** ```js -netConnection.on('netBlockStatusChange', function (data) { +// 创建NetConnection对象 +let netCon = connection.createNetConnection() + +// 先使用register接口注册订阅事件 +netCon.register(function (error) { + console.log(JSON.stringify(error)) +}) + +// 订阅网络连接信息变化事件。调用register后，才能接收到此事件通知 +netCon.on('netConnectionPropertiesChange', function (data) { console.log(JSON.stringify(data)) }) + +// 使用unregister接口取消订阅 +netCon.unregister(function (error) { + console.log(JSON.stringify(error)) +}) ``` ### on('netLost') @@ -761,6 +1384,8 @@ on(type: 'netLost', callback: Callback\): void 订阅网络丢失事件。 +**模型约束**：此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 + **系统能力**：SystemCapability.Communication.NetManager.Core **参数：** @@ -768,15 +1393,28 @@ on(type: 'netLost', callback: Callback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 订阅事件，固定为'netLost'。
netLost：网络严重中断或正常断开事件。 | -| callback | Callback\<[NetHandle](#nethandle)> | 是 | 回调函数。 | +| callback | Callback\<[NetHandle](#nethandle)> | 是 | 回调函数，数据网络句柄(netHandle)| **示例：** ```js -let netConnection1 = connection.createNetConnection() -netConnection1.on('netLost', function (data) { +// 创建NetConnection对象 +let netCon = connection.createNetConnection() + +// 先使用register接口注册订阅事件 +netCon.register(function (error) { + console.log(JSON.stringify(error)) +}) + +// 订阅网络丢失事件。调用register后，才能接收到此事件通知 +netCon.on('netLost', function (data) { console.log(JSON.stringify(data)) }) + +// 使用unregister接口取消订阅 +netCon.unregister(function (error) { + console.log(JSON.stringify(error)) +}) ``` ### on('netUnavailable') @@ -785,6 +1423,8 @@ on(type: 'netUnavailable', callback: Callback\): void 订阅网络不可用事件。 +**模型约束**：此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 + **系统能力**：SystemCapability.Communication.NetManager.Core **参数：** @@ -792,58 +1432,26 @@ on(type: 'netUnavailable', callback: Callback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 订阅事件，固定为'netUnavailable'。
netUnavailable：网络不可用事件。 | -| callback | Callback\ | 是 | 回调函数。 | +| callback | Callback\ | 是 | 回调函数，无返回结果。| **示例：** ```js -netConnection.on('netUnavailable', function (data) { - console.log(JSON.stringify(data)) -}) -``` - -### register - -register(callback: AsyncCallback\): void - -订阅指定网络状态变化的通知。 - -**需要权限**：ohos.permission.GET_NETWORK_INFO - -**系统能力**：SystemCapability.Communication.NetManager.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| callback | AsyncCallback\ | 是 | 回调函数。 | +// 创建NetConnection对象 +let netCon = connection.createNetConnection() -**示例：** - -```js -netConnection.register(function (error) { +// 先使用register接口注册订阅事件 +netCon.register(function (error) { console.log(JSON.stringify(error)) }) -``` - -### unregister - -unregister(callback: AsyncCallback\): void - -取消订阅默认网络状态变化的通知。 - -**系统能力**：SystemCapability.Communication.NetManager.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| callback | AsyncCallback\ | 是 | 回调函数。 | -**示例：** +// 订阅网络不可用事件。调用register后，才能接收到此事件通知 +netCon.on('netUnavailable', function (data) { + console.log(JSON.stringify(data)) +}) -```js -netConnection.unregister(function (error) { +// 使用unregister接口取消订阅 +netCon.unregister(function (error) { console.log(JSON.stringify(error)) }) ``` @@ -875,7 +1483,16 @@ bindSocket(socketParam: TCPSocket \| UDPSocket, callback: AsyncCallback\): | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------------------------ | ---- | -------------------------------| | socketParam | [TCPSocket](js-apis-socket.md#tcpsocket) \| [UDPSocket](js-apis-socket.md#udpsocket) | 是 | 待绑定的TCPSocket或UDPSocket对象。| -| callback | AsyncCallback\ | 是 | 回调函数 | +| callback | AsyncCallback\ | 是 | 回调函数。当TCPSocket或UDPSocket成功绑定到当前网络，err为undefined，否则为错误对象。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** @@ -946,6 +1563,15 @@ bindSocket(socketParam: TCPSocket \| UDPSocket): Promise\; | -------------- | ---------------------- | | Promise\ | 无返回值的Promise对象。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js @@ -1010,16 +1636,26 @@ getAddressesByName(host: string, callback: AsyncCallback\>): | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------- | ---- | ------------------ | | host | string | 是 | 需要解析的主机名。 | -| callback | AsyncCallback\> | 是 | 回调函数 | +| callback | AsyncCallback\> | 是 | 回调函数。当使用对应网络解析主机名成功获取所有IP地址，err为undefined，data为获取到的所有IP地址；否则为错误对象。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js connection.getDefaultNet().then(function (netHandle) { let host = "xxxx"; - netHandle.getAddressesByName(host, function (error, addresses) { + netHandle.getAddressesByName(host, function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(addresses)) + console.log(JSON.stringify(data)) }) }) ``` @@ -1046,13 +1682,23 @@ getAddressesByName(host: string): Promise\> | ------------------------------------------- | ----------------------------- | | Promise\> | 以Promise形式返回所有IP地址。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js connection.getDefaultNet().then(function (netHandle) { let host = "xxxx"; - netHandle.getAddressesByName(host).then(function (addresses) { - console.log(JSON.stringify(addresses)) + netHandle.getAddressesByName(host).then(function (data) { + console.log(JSON.stringify(data)) }) }) ``` @@ -1072,16 +1718,26 @@ getAddressByName(host: string, callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------- | ---- | ------------------ | | host | string | 是 | 需要解析的主机名。 | -| callback | AsyncCallback\<[NetAddress](#netaddress)> | 是 | 回调函数。 | +| callback | AsyncCallback\<[NetAddress](#netaddress)> | 是 | 回调函数。当使用对应网络解析主机名获取第一个IP地址成功，err为undefined，data为获取的第一个IP地址；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | **示例：** ```js connection.getDefaultNet().then(function (netHandle) { let host = "xxxx"; - netHandle.getAddressByName(host, function (error, address) { + netHandle.getAddressByName(host, function (error, data) { console.log(JSON.stringify(error)) - console.log(JSON.stringify(address)) + console.log(JSON.stringify(data)) }) }) ``` @@ -1108,41 +1764,27 @@ getAddressByName(host: string): Promise\ | ----------------------------------- | ------------------------------- | | Promise\<[NetAddress](#netaddress)> | 以Promise形式返回第一个IP地址。 | +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + **示例：** ```js connection.getDefaultNet().then(function (netHandle) { let host = "xxxx"; - netHandle.getAddressByName(host).then(function (address) { - console.log(JSON.stringify(address)) + netHandle.getAddressByName(host).then(function (data) { + console.log(JSON.stringify(data)) }) }) ``` -## NetSpecifier - -提供承载数据网络能力的实例。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 - -| 名称 | 类型 | 必填 | 说明 | -| ----------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | -| netCapabilities | [NetCapabilities](#netcapabilities) | 是 | 存储数据网络的传输能力和承载类型。 | -| bearerPrivateIdentifier | string | 否 | 网络标识符，Wi-Fi网络的标识符是"wifi"，蜂窝网络的标识符是"slot0"（对应SIM卡1）。 | - -## NetCapabilities - -网络的能力集。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 - -| 名称 | 类型 | 必填 | 说明 | -| --------------------- | ---------------------------------- | --- | ------------------------ | -| linkUpBandwidthKbps | number | 否 | 上行（设备到网络）带宽。 | -| linkDownBandwidthKbps | number | 否 | 下行（网络到设备）带宽。 | -| networkCap | Array\<[NetCap](#netcap)> | 否 | 网络具体能力。 | -| bearerTypes | Array\<[NetBearType](#netbeartype)> | 是 | 网络类型。 | - ## NetCap 网络具体能力。 @@ -1169,6 +1811,42 @@ connection.getDefaultNet().then(function (netHandle) { | BEARER_WIFI | 1 | Wi-Fi网络。 | | BEARER_ETHERNET | 3 | 以太网网络。 | +## HttpProxy + +网络全局代理配置信息 + +**系统能力**：SystemCapability.Communication.NetManager.Core + +| 名称 | 类型 | 必填 | 说明 | +| ------ | ------ | --- |------------------------- | +| host | string | 否 | 代理服务器主机名。 | +| port | number | 否 | 主机端口。 | +| parsedExclusionList | Array | 否 | 不使用代理服务器的屏蔽列表。 | + +## NetSpecifier + +提供承载数据网络能力的实例。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 名称 | 类型 | 必填 | 说明 | +| ----------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | +| netCapabilities | [NetCapabilities](#netcapabilities) | 是 | 存储数据网络的传输能力和承载类型。 | +| bearerPrivateIdentifier | string | 否 | 网络标识符，Wi-Fi网络的标识符是"wifi"，蜂窝网络的标识符是"slot0"（对应SIM卡1）。 | + +## NetCapabilities + +网络的能力集。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 名称 | 类型 | 必填 | 说明 | +| --------------------- | ---------------------------------- | --- | ------------------------ | +| linkUpBandwidthKbps | number | 否 | 上行（设备到网络）带宽。 | +| linkDownBandwidthKbps | number | 否 | 下行（网络到设备）带宽。 | +| networkCap | Array\<[NetCap](#netcap)> | 否 | 网络具体能力。 | +| bearerTypes | Array\<[NetBearType](#netbeartype)> | 是 | 网络类型。 | + ## ConnectionProperties 网络连接信息。 @@ -1181,20 +1859,9 @@ connection.getDefaultNet().then(function (netHandle) { | domains | string | 是 |所属域，默认""。 | | linkAddresses | Array\<[LinkAddress](#linkaddress)> | 是 |链路信息。 | | routes | Array\<[RouteInfo](#routeinfo)> | 是 |路由信息。 | -| dnses | Array\<[NetAddress](#netaddress)>; | 是 |网络地址，参考[NetAddress](#netaddress)。 | +| dnses | Array\<[NetAddress](#netaddress)> | 是 |网络地址，参考[NetAddress](#netaddress)。 | | mtu | number | 是 |最大传输单元。 | -## LinkAddress - -网络链路信息。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 - -| 名称 | 类型 | 必填 |说明 | -| ------------ | ----------------------- |---- |-------------------- | -| address | [NetAddress](#netaddress) | 是 | 链路地址。 | -| prefixLength | number | 是 |链路地址前缀的长度。 | - ## RouteInfo 网络路由信息。 @@ -1209,6 +1876,17 @@ connection.getDefaultNet().then(function (netHandle) { | hasGateway | boolean | 是 |是否有网关。 | | isDefaultRoute | boolean | 是 |是否为默认路由。 | +## LinkAddress + +网络链路信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 名称 | 类型 | 必填 |说明 | +| ------------ | ----------------------- |---- |-------------------- | +| address | [NetAddress](#netaddress) | 是 | 链路地址。 | +| prefixLength | number | 是 |链路地址前缀的长度。 | + ## NetAddress 网络地址。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md b/zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md index a451b5cf79..efc6eb2410 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md +++ b/zh-cn/application-dev/reference/apis/js-apis-net-ethernet.md @@ -1,9 +1,8 @@ -# @ohos.net.ethernet (以太网连接管理) +# 以太网连接 以太网连接管理主要提供有线网络能力，提供设置有线网络的IP地址，子网掩码，网关，DNS等信息 -> **说明：** -> +> ![](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 @@ -35,8 +34,8 @@ setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallbac **示例：** ```js -ethernet.setIfaceConfig("eth0", {mode:ethernet.STATIC,ipAddr:"192.168.1.123", routeAddr:"192.168.1.1", - gateAddr:"192.168.1.1", maskAddr:"255.255.255.0", dnsAddr0:"1.1.1.1", dnsAddr1:"2.2.2.2"}, +ethernet.setIfaceConfig("eth0", {mode:ethernet.STATIC,ipAddr:"192.168.xx.xx", routeAddr:"192.168.xx.xx", + gateAddr:"192.168.xx.xx", maskAddr:"255.255.xx.xx", dnsAddr0:"1.1.xx.xx", dnsAddr1:"2.2.xx.xx"}, (error) => { if (error) { console.log("setIfaceConfig callback error = " + error); @@ -74,8 +73,8 @@ setIfaceConfig(iface: string, ic: InterfaceConfiguration): Promise\ **示例：** ```js -ethernet.setIfaceConfig("eth0", {mode:ethernet.STATIC,ipAddr:"192.168.1.123", routeAddr:"192.168.1.1", - gateAddr:"192.168.1.1", maskAddr:"255.255.255.0", dnsAddr0:"1.1.1.1", dnsAddr1:"2.2.2.2"}).then(() => { +ethernet.setIfaceConfig("eth0", {mode:ethernet.STATIC,ipAddr:"192.168.xx.xx", routeAddr:"192.168.xx.xx", + gateAddr:"192.168.xx.xx", maskAddr:"255.255.xx.xx", dnsAddr0:"1.1.xx.xx", dnsAddr1:"2.2.xx.xx"}).then(() => { console.log("setIfaceConfig promiss ok "); }).catch((error) => { console.log("setIfaceConfig promiss error = " + error); diff --git a/zh-cn/application-dev/reference/apis/js-apis-net-policy.md b/zh-cn/application-dev/reference/apis/js-apis-net-policy.md new file mode 100644 index 0000000000..3766d4517b --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-net-policy.md @@ -0,0 +1,1558 @@ +# 网络策略管理 + +网络策略管理通过对用户使用数据流量进行控制管理，采用防火墙技术实现网络策略的管理。 + +> **说明：** +> +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```js +import policy from '@ohos.net.policy' +``` + +## policy.setBackgroundPolicy + +setBackgroundPolicy(isAllowed: boolean, callback: AsyncCallback\): void + +设置后台网络策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| isAllowed | boolean | 是 | 是否允许应用后台使用数据 | +| callback | AsyncCallback\ | 是 | 回调函数，成功返回设置后台网络策略的结果，失败返回错误码错误信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.setBackgroundPolicy(Boolean(Number.parseInt(this.isBoolean))), (error, data) => { + this.callBack(error, data); + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); +``` + +## policy.setBackgroundPolicy + +setBackgroundPolicy(isAllowed: boolean): Promise\ + +设置后台网络策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| isAllowed | boolean | 是 | 是否允许应用后台使用数据 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果，失败返回错误码错误信息。 | + +**示例：** + +```js +policy.setBackgroundPolicy(Boolean(Number.parseInt(this.isBoolean))).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) +``` + +## policy.isBackgroundAllowed + +isBackgroundAllowed(callback: AsyncCallback\): void; + +获取后台网络策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数，返回true代表后台策略为允许。失败返回错误码错误信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.isBackgroundAllowed((error, data) => { + this.callBack(error, data); + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}); +``` + +## policy.isBackgroundAllowed + +isBackgroundAllowed(): Promise\; + +获取后台网络策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。失败返回错误码错误信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.isBackgroundAllowed().then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.setPolicyByUid + +setPolicyByUid(uid: number, policy: NetUidPolicy, callback: AsyncCallback\): void; + +设置对应uid应用的访问计量网络的策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | 应用的唯一标识符 | +| policy | [NetUidPolicy](#netuidpolicy) | 是 | 应用对应的策略 | +| callback | AsyncCallback\ | 是 | 回调函数，成功返回设定结果。失败返回错误码错误信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), policy: Number.parseInt(this.currentNetUidPolicy) +} +policy.setPolicyByUid(Number.parseInt(this.firstParam), Number.parseInt(this.currentNetUidPolicy), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.setPolicyByUid + +setPolicyByUid(uid: number, policy: NetUidPolicy): Promise\; + +设置对应uid应用的访问计量网络的策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | 应用的唯一标识符 | +| policy | [NetUidPolicy](#netuidpolicy) | 是 | 应用对应的策略 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。失败返回错误码错误信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), policy: Number.parseInt(this.currentNetUidPolicy) +} +policy.setPolicyByUid(Number.parseInt(this.firstParam), Number.parseInt(this.currentNetUidPolicy)).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.getPolicyByUid + +getPolicyByUid(uid: number, callback: AsyncCallback\): void; + +通过应用uid获取策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| callback | AsyncCallback\<[NetUidPolicy](#netuidpolicy)> | 是 | 回调函数，成功返回获取策略结果，失败返回错误码错误信息。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getPolicyByUid(Number.parseInt(this.firstParam), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.getPolicyByUid + +getPolicyByUid(uid: number): Promise\; + +通过应用uid获取策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\<[NetUidPolicy](#netuidpolicy)> | 以Promise形式返回获取策略结果。失败返回错误码错误信息。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getPolicyByUid(Number.parseInt(this.firstParam)).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.getUidsByPolicy + +getUidsByPolicy(policy: NetUidPolicy, callback: AsyncCallback\>): void; + +通过策略获取设置这一策略的应用uid数组，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| policy | [NetUidPolicy](#netuidpolicy) | 是 | 应用对应的计量网络下的策略 | +| callback | AsyncCallback\> | 是 | 回调函数，成功返回应用的uid数组，失败返回错误码错误信息。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getUidsByPolicy(Number.parseInt(this.currentNetUidPolicy), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.getUidsByPolicy + +function getUidsByPolicy(policy: NetUidPolicy): Promise\>; + +通过策略获取设置这一策略的应用uid数组，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| policy | [NetUidPolicy](#netuidpolicy) | 是 | app对应的计量网络下的策略 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回应用的uid数组，失败返回错误码错误信息。| + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getUidsByPolicy(Number.parseInt(this.firstParam)).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.getNetQuotaPolicies + +getNetQuotaPolicies(callback: AsyncCallback\>): void; + +获取计量网络策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\> | 是 | 回调函数，返回获取结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getNetQuotaPolicies((error, data) => { + this.callBack(error, data); +}); +``` + +## policy.getNetQuotaPolicies + +getNetQuotaPolicies(): Promise\>; + +获取计量网络策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getNetQuotaPolicies().then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.setNetQuotaPolicies + +setNetQuotaPolicies(quotaPolicies: Array\, callback: AsyncCallback\): void; + +设置计量网络策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| quotaPolicies | Array\<[NetQuotaPolicy](#netquotapolicy)> | 是 | 计量网络策略 | +| callback | AsyncCallback\ | 是 | 回调函数，返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = {netType:Number.parseInt(this.netType), iccid:this.iccid, ident:this.ident, periodDuration:this.periodDuration, warningBytes:Number.parseInt(this.warningBytes), + limitBytes:Number.parseInt(this.limitBytes), lastWarningRemind:this.lastWarningRemind, lastLimitRemind:this.lastLimitRemind, metered:Boolean(Number.parseInt(this.metered)), limitAction:this.limitAction}; +this.netQuotaPolicyList.push(param); + +policy.setNetQuotaPolicies(this.netQuotaPolicyList, (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.setNetQuotaPolicies + +setNetQuotaPolicies(quotaPolicies: Array\): Promise\; + +设置计量网络策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| quotaPolicies | Array\<[NetQuotaPolicy](#netquotapolicy)> | 是 | 计量网络策略 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**示例：** + +```js +let param = {netType:Number.parseInt(this.netType), iccid:this.iccid, ident:this.ident, periodDuration:this.periodDuration, warningBytes:Number.parseInt(this.warningBytes), + limitBytes:Number.parseInt(this.limitBytes), lastWarningRemind:this.lastWarningRemind, lastLimitRemind:this.lastLimitRemind, metered:Boolean(Number.parseInt(this.metered)), limitAction:this.limitAction}; +this.netQuotaPolicyList.push(param); + +policy.setNetQuotaPolicies(this.netQuotaPolicyList).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) +``` + +## policy.restoreAllPolicies + +restoreAllPolicies(iccid: string, callback: AsyncCallback\): void; + +重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| iccid | string | 是 | SIM卡ID| +| callback | AsyncCallback\ | 是 | 回调函数，返回重置结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +this.firstParam = iccid; +policy.restoreAllPolicies(this.firstParam, (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.restoreAllPolicies + +restoreAllPolicies(iccid: string): Promise\; + +重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| iccid | string | 是 | SIM卡ID| + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +this.firstParam = iccid; +policy.restoreAllPolicies(this.firstParam).then((error, data){ + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.isUidNetAllowed + +isUidNetAllowed(uid: number, isMetered: boolean, callback: AsyncCallback\): void; + +获取对应uid能否访问计量或非计量网络，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| isMetered | boolean | 是 | 是否为计量网络 | +| callback | AsyncCallback\ | 是 | 回调函数，返回true表示这个uid可以访问对应的计量网络。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js + +let param = { + uid: Number.parseInt(this.firstParam), isMetered: Boolean(Number.parseInt(this.isBoolean)) +} +policy.isUidNetAllowed(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean)), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.isUidNetAllowed + +isUidNetAllowed(uid: number, isMetered: boolean): Promise\; + +获取对应uid能否访问计量或非计量网络，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| isMetered | boolean | 是 | 是否为计量网络 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js + +let param = { + uid: Number.parseInt(this.firstParam), isMetered: Boolean(Number.parseInt(this.isBoolean)) +} +policy.isUidNetAllowed(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean))).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.isUidNetAllowed + +isUidNetAllowed(uid: number, iface: string, callback: AsyncCallback\): void; + +获取对应uid能否访问指定的iface的网络，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| iface | string | 是 | 网络对应的名称 | +| callback | AsyncCallback\ | 是 | 回调函数，返回true表示这个uid可以访问对应iface的网络。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js + +let param = { + uid: Number.parseInt(this.firstParam), iface: this.secondParam +} +policy.isUidNetAllowed(Number.parseInt(this.firstParam), this.secondParam, (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.isUidNetAllowed + +isUidNetAllowed(uid: number, iface: string): Promise\; + +获取对应uid能否访问指定的iface的网络，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| iface | string | 是 | 网络对应的名称 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), iface: this.secondParam +} +policy.isUidNetAllowed(Number.parseInt(this.firstParam), this.secondParam).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.setDeviceIdleAllowList + +setDeviceIdleAllowList(uid: number, isAllowed: boolean, callback: AsyncCallback\): void; + +设置指定uid应用是否在休眠防火墙的白名单，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| isAllowed | boolean | 是 | 是否加入白名单 | +| callback | callback: AsyncCallback\ | 是 | 回调函数，返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), isAllowed: Boolean(Number.parseInt(this.isBoolean)) +} +policy.setDeviceIdleAllowList(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean)), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.setDeviceIdleAllowList + +setDeviceIdleAllowList(uid: number, isAllowed: boolean): Promise\; + +设置指定uid应用是否在休眠防火墙的白名单，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| isAllowed | boolean | 是 | 是否加入白名单 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), isAllowed: Boolean(Number.parseInt(this.isBoolean)) +} +policy.setDeviceIdleAllowList(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean))).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.getDeviceIdleAllowList + +getDeviceIdleAllowList(callback: AsyncCallback\>): void; + +获取休眠模式白名单所包含的uid数组，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\> | 是 | 回调函数，返回获取结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getDeviceIdleAllowList((error, data) => { + this.callBack(error, data); +}); +``` + +## policy.getDeviceIdleAllowList + +getDeviceIdleAllowList(): Promise\>; + +获取休眠模式白名单所包含的uid数组，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getDeviceIdleAllowList().then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) +``` + +## policy.getBackgroundPolicyByUid + +getBackgroundPolicyByUid(uid: number, callback: AsyncCallback\): void; + +获取指定uid能否访问后台网络，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| callback | AsyncCallback\<[NetBackgroundPolicy](#netbackgroundpolicy)> | 是 | 回调函数，返回获取结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +this.firstParam = uid +policy.getBackgroundPolicyByUid(Number.parseInt(this.firstParam), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.getBackgroundPolicyByUid + +getBackgroundPolicyByUid(uid: number): Promise\; + +获取指定uid能否访问后台网络，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\<[NetBackgroundPolicy](#netbackgroundpolicy)> | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +this.firstParam = uid +policy.getBackgroundPolicyByUid(Number.parseInt(this.firstParam)).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) +``` + +## policy.resetPolicies + +resetPolicies(iccid: string, callback: AsyncCallback\): void; + +重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| iccid | string | 是 | SIM卡ID| +| callback | AsyncCallback\ | 是 | 回调函数，返回重置结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +this.firstParam = iccid +policy.resetPolicies(this.firstParam, (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.resetPolicies + +resetPolicies(iccid: string): Promise\; + +重置对应sim卡id的蜂窝网络、后台网络策略、防火墙策略、应用对应的策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| iccid | string | 是 | SIM卡ID| + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getUidsByPolicy(Number.parseInt(this.firstParam)).then((error, data) { + +}) +this.firstParam = iccid +policy.resetPolicies(this.firstParam).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.updateRemindPolicy + +updateRemindPolicy(netType: NetBearType, iccid: string, remindType: RemindType, callback: AsyncCallback\): void; + +更新提醒策略，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| netType | [NetBearType](js-apis-net-connection.md#netbeartype) | 是 | 网络类型 | +| iccid | string | 是 | SIM卡ID| +| remindType | [RemindType](#remindtype) | 是 | 提醒类型 | +| callback | AsyncCallback\ | 是 | 回调函数，返回更新结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + netType: Number.parseInt(this.netType), iccid: this.firstParam, remindType: this.currentRemindType +} +policy.updateRemindPolicy(Number.parseInt(this.netType), this.firstParam, Number.parseInt(this.currentRemindType), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.updateRemindPolicy + +updateRemindPolicy(netType: NetBearType, iccid: string, remindType: RemindType): Promise\; + +更新提醒策略，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| netType | [NetBearType](js-apis-net-connection.md#netbeartype) | 是 | 网络类型 | +| iccid | string | 是 | SIM卡ID| +| remindType | [RemindType](#remindtype) | 是 | 提醒类型 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + netType: Number.parseInt(this.netType), iccid: this.firstParam, remindType: this.currentRemindType +} +policy.updateRemindPolicy(Number.parseInt(this.netType), this.firstParam, Number.parseInt(this.currentRemindType)).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.setPowerSaveAllowList + +setPowerSaveAllowList(uid: number, isAllowed: boolean, callback: AsyncCallback\): void; + +设置指定uid应用是否在省电防火墙的白名单，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| isAllowed | boolean | 是 | 是否加入白名单 | +| callback | callback: AsyncCallback\ | 是 | 回调函数，返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), isAllowed: Boolean(Number.parseInt(this.isBoolean)) +} +policy.setPowerSaveAllowList(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean)), (error, data) => { + this.callBack(error, data); +}); +``` + +## policy.setPowerSaveAllowList + +setPowerSaveAllowList(uid: number, isAllowed: boolean): Promise\; + +设置指定uid应用是否在省电防火墙的白名单，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| uid | number | 是 | app唯一标识符 | +| isAllowed | boolean | 是 | 是否加入白名单 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 2100001 | Invalid parameter value. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +let param = { + uid: Number.parseInt(this.firstParam), isAllowed: Boolean(Number.parseInt(this.isBoolean)) +} +policy.setPowerSaveAllowList(Number.parseInt(this.firstParam), Boolean(Number.parseInt(this.isBoolean))).then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) + +``` + +## policy.getPowerSaveAllowList + +getPowerSaveAllowList(callback: AsyncCallback\>): void; + +获取省电模式白名单所包含的uid数组，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ---------- | +| callback | AsyncCallback\> | 是 | 回调函数，返回获取结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getPowerSaveAllowList((error, data) => { + this.callBack(error, data); +}); +``` + +## policy.getPowerSaveAllowList + +getPowerSaveAllowList(): Promise\>; + +获取休眠模式白名单所包含的uid数组，使用Promise方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\> | 以Promise形式返回设定结果。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| ------- | -------------------------------------------- | +| 201 | Permission denied. | +| 2100002 | Operation failed. Cannot connect to service.| +| 2100003 | System internal error. | + +**示例：** + +```js +policy.getPowerSaveAllowList().then((error, data) { + console.log(JSON.stringify(error)) + console.log(JSON.stringify(data)) +}) +``` + +## policy.on + +网络策略的句柄。 + +### on('netUidPolicyChange') + +on(type: "netUidPolicyChange", callback: Callback\<{ uid: number, policy: NetUidPolicy }>): void; + +注册policy发生改变时的回调，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | +| type | netUidPolicyChange | 是 | policy发生改变的类型 | +| callback | Callback\<{ uid: number, policy: [NetUidPolicy](#netuidpolicy) }> | 是 | 回调函数。注册policy发生改变时调用。 | + +**示例：** + +```js +policy.on('netUidPolicyChange', (data) => { + this.log('on netUidPolicyChange：' + JSON.stringify(data)); +}) +``` + +### on('netUidRuleChange') + +on(type: "netUidRuleChange", callback: Callback\<{ uid: number, rule: NetUidRule }>): void; + +注册rule发生改变时的回调，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | +| type | netUidRuleChange | 是 | rule发生改变的类型 | +| callback | Callback\<{ uid: number, rule: [NetUidRule](#netuidrule) }> | 是 | 回调函数。注册rule发生改变时的调用。 | + +**示例：** + +```js +policy.on('netUidRuleChange', (data) => { + this.log('on netUidRuleChange：' + JSON.stringify(data)); +}) +``` + +### on('netMeteredIfacesChange') + +on(type: "netMeteredIfacesChange", callback: Callback\>): void; + +注册计量iface发生改变时的回调，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | +| type | netMeteredIfacesChange | 是 | 计量iface发生改变的类型 | +| callback | Callback\> | 是 | 回调函数。注册计量iface发生改变时调用。 | + +**示例：** + +```js +policy.on('netMeteredIfacesChange', (data) => { + this.log('on netMeteredIfacesChange：' + JSON.stringify(data)); +}) +``` + +### on('netQuotaPolicyChange') + +on(type: "netQuotaPolicyChange", callback: Callback\>): void; + +注册计量网络策略发生改变时的回调，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | +| type | netQuotaPolicyChange | 是 | 计量网络策略发生改变的类型 | +| callback | Callback\> | 是 | 回调函数。注册计量网络策略发生改变时调用。 | + +**示例：** + +```js +policy.on('netQuotaPolicyChange', (data) => { + this.log('on netQuotaPolicyChange：' + JSON.stringify(data)); +}) +``` + +### on('netBackgroundPolicyChange') + +on(type: "netBackgroundPolicyChange", callback: Callback\): void; + +注册后台网络策略发生改变时的回调，使用callback方式作为异步方法。 + +**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL + +**系统能力**：SystemCapability.Communication.NetManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | +| type | netBackgroundPolicyChange | 是 | 后台网络策略发生改变的类型 | +| callback | Callback\ | 是 | 回调函数。注册后台网络策略发生改变时调用。 | + +**示例：** + +```js +policy.on('netBackgroundPolicyChange', (data) => { + this.log('on netBackgroundPolicyChange：' + JSON.stringify(data)); +}) +``` + +## NetBackgroundPolicy + +后台网络策略。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 参数名 | 值 | 说明 | +| ------------------------ | ---- | ---------------------- | +| NET_BACKGROUND_POLICY_NONE | 0 | 默认值。 | +| NET_BACKGROUND_POLICY_ENABLE | 1 | 应用在后台可以使用计量网路。 | +| NET_BACKGROUND_POLICY_DISABLE | 2 | 应用在后台不可以使用计量网路。 | +| NET_BACKGROUND_POLICY_ALLOW_LIST | 3 | 只有应用指定的列表在后台可以使用计量网络。 | + +## NetQuotaPolicy + +计量网络策略。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 参数名 | 类型 | 说明 | +| ----------------------- | ----------------------------------- | ------------------------------------------------------------ | +| netType | [NetBearType](js-apis-net-connection.md#netbeartype) | 网络类型。 | +| iccid | string | 计量蜂窝网络的SIM卡的标识值。以太网，wifi网络不会用到 | +| ident | string | 计量蜂窝网络中配合iccid联合使用。以太网，wifi网络单独使用。用于标记类型。 | +| periodDuration | string | 计量开始时间。 | +| warningBytes | number | 发出警告的流量阈值。 | +| limitBytes | number | 流量设置的配额。 | +| lastWarningRemind | string | 最新一次发出警告的时间。 | +| lastLimitRemind | string | 最新一次配额耗尽的时间。 | +| metered | string | 是否为计量网络。 | +| limitAction | [LimitAction](#limitaction) | 到达流量限制后的动作。 | + +## LimitAction + +限制动作。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 参数名 | 值 | 说明 | +| ---------------------- | ----- | ------------ | +| LIMIT_ACTION_NONE | -1 | 默认值。 | +| LIMIT_ACTION_DISABLE | 0 | 当配额策略达到限制时，访问被禁用。 | +| LIMIT_ACTION_AUTO_BILL| 1 | 当配额策略达到限制时，用户将自动计费。 | + +## NetUidRule + +计量网络规则。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 参数名 | 值 | 说明 | +| ---------------------- | ----- | ------------ | +| NET_RULE_NONE | 0 | 默认规则 | +| NET_RULE_ALLOW_METERED_FOREGROUND | 1 | 允许前台访问计量网络 | +| NET_RULE_ALLOW_METERED | 2 | 允许访问计量网络 | +| NET_RULE_REJECT_METERED | 4 | 拒绝访问计量网络 | +| NET_RULE_ALLOW_ALL | 32 | 允许访问所有网络 | +| NET_RULE_REJECT_ALL | 64 | 拒绝访问所有网络 | + +## RemindType + +提醒类型。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 参数名 | 值 | 说明 | +| ---------------------- | - | ------- | +| REMIND_TYPE_WARNING | 1 | 警告提醒 | +| REMIND_TYPE_LIMIT | 2 | 限制提醒 | + +## NetUidPolicy + +应用对应的网络策略。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetManager.Core。 + +| 参数名 | 值 | 说明 | +| ---------------------- | ----- | ------------ | +| NET_POLICY_NONE | 0 | 默认网络策略 | +| NET_POLICY_ALLOW_METERED_BACKGROUND | 1 | 允许应用在后台访问计量网络 | +| NET_POLICY_REJECT_METERED_BACKGROUND | 2 | 拒绝应用在后台访问计量网络 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-net-sharing.md b/zh-cn/application-dev/reference/apis/js-apis-net-sharing.md index cefbc4d648..2afcc85e79 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-net-sharing.md +++ b/zh-cn/application-dev/reference/apis/js-apis-net-sharing.md @@ -1,6 +1,6 @@ # @ohos.net.sharing (网络共享管理) -网络共享管理分享设备已有网络给其他连接设备，支持Wi-Fi热点共享和蓝牙共享，同时提供网络共享状态、共享流量查询功能。 +网络共享管理分享设备已有网络给其他连接设备，支持Wi-Fi热点共享、蓝牙共享和USB共享，同时提供网络共享状态、共享流量查询功能。 > **说明：** > @@ -789,7 +789,7 @@ sharing.off('sharingUpstreamChange', (error, data) => { ## SharingIfaceType -网络共享类型（暂不支持USB共享）。 +网络共享类型。 **系统接口**：此接口为系统接口。 -- GitLab