• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 网络连接管理
2
3## 简介
4
5网络连接管理提供管理网络一些基础能力，包括WiFi/蜂窝/Ethernet等多网络连接优先级管理、网络质量评估、订阅默认/指定网络连接状态变化、查询网络连接信息、DNS解析等功能。
6
7> **说明：**
8> 为了保证应用的运行效率，大部分API调用都是异步的，对于异步调用的API均提供了callback和Promise两种方式，以下示例均采用callback函数，更多方式可以查阅[API参考](../reference/apis/js-apis-net-connection.md)。
9
10## 基本概念
11
12- 网络生产者：数据网络的提供方，比如WiFi、蜂窝、Ethernet等。
13- 网络消费者：数据网络的使用方，比如应用或系统服务。
14- 网络探测：检测网络有效性，避免将网络从可用网络切换到不可用网络。内容包括绑定网络探测、DNS探测、HTTP探测及HTTPS探测。
15- 网络优选：处理多网络共存时选择最优网络。在网络状态、网络信息及评分发生变化时被触发。
16
17## 约束
18
19- 开发语言：JS
20- 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
21
22## 场景介绍
23
24网络连接管理的典型场景有：
25
26- 接收指定网络的状态变化通知
27- 获取所有注册的网络
28- 根据数据网络查询网络的连接信息
29- 使用对应网络解析域名，获取所有IP
30
31以下分别介绍具体开发方式。
32
33## 接口说明
34
35完整的JS API说明以及实例代码请参考：[网络连接管理](../reference/apis/js-apis-net-connection.md)。
36
37| 接口名 | 描述 |
38| ---- | ---- |
39| getDefaultNet(callback: AsyncCallback\<NetHandle>): void; |获取一个含有默认网络的netId的NetHandle对象，使用callback回调 |
40| getGlobalHttpProxy(callback: AsyncCallback\<HttpProxy>): void;| 获取网络的全局代理设置，使用callback回调 |
41| setGlobalHttpProxy(httpProxy: HttpProxy, callback: AsyncCallback\<void>): void;| 设置网络全局Http代理配置信息，使用callback回调 |
42| getAppNet(callback: AsyncCallback\<NetHandle>): void;| 获取一个App绑定的包含了网络netId的NetHandle对象，使用callback回调 |
43| setAppNet(netHandle: NetHandle, callback: AsyncCallback\<void>): void;| 绑定App到指定网络，绑定后的App只能通过指定网络访问外网。使用callback回调 |
44| getDefaultNetSync(): NetHandle; |使用同步方法获取默认激活的数据网络。可以使用getNetCapabilities去获取网络的类型、拥有的能力等信息。|
45| hasDefaultNet(callback: AsyncCallback\<boolean>): void; |检查默认数据网络是否被激活，使用callback回调 |
46| getAllNets(callback: AsyncCallback\<Array\<NetHandle>>): void;| 获取所处于连接状态的网络的MetHandle对象列表，使用callback回调 |
47| getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback\<ConnectionProperties>): void; |查询netHandle对应的网络的连接信息，使用callback回调 |
48| getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback\<NetCapabilities>): void; |获取netHandle对应的网络的能力信息，使用callback回调 |
49| isDefaultNetMetered(callback: AsyncCallback\<boolean>): void; |检查当前网络上的数据流量使用是否被计量，使用callback方式作为异步方法 |
50| reportNetConnected(netHandle: NetHandle, callback: AsyncCallback\<void>): void;| 向网络管理报告网络处于可用状态，调用此接口说明应用程序认为网络的可用性（ohos.net.connection.NetCap.NET_CAPABILITY_VAILDATED）与网络管理不一致。使用callback回调 |
51| reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback\<void>): void;| 向网络管理报告网络处于不可用状态，调用此接口说明应用程序认为网络的可用性（ohos.net.connection.NetCap.NET_CAPABILITY_VAILDATED）与网络管理不一致。使用callback回调 |
52| getAddressesByName(host: string, callback: AsyncCallback\<Array\<NetAddress>>): void; |使用对应网络解析域名，获取所有IP，使用callback回调 |
53| enableAirplaneMode(callback: AsyncCallback\<void>): void; | 设置网络为飞行模式，使用callback回调 |
54| disableAirplaneMode(callback: AsyncCallback\<void>): void;| 关闭网络飞行模式，使用callback回调 |
55| createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection; | 返回一个NetConnection对象，netSpecifier指定关注的网络的各项特征，timeout是超时时间(单位是毫秒)，netSpecifier是timeout的必要条件，两者都没有则表示关注默认网络 |
56| bindSocket(socketParam: TCPSocket \| UDPSocket, callback: AsyncCallback\<void>): void; | 将TCPSocket或UDPSockett绑定到当前网络，使用callback回调 |
57| getAddressesByName(host: string, callback: AsyncCallback\<Array\<NetAddress>>): void; |使用对应网络解析域名，获取所有IP，使用callback回调 |
58| getAddressByName(host: string, callback: AsyncCallback\<NetAddress>): void; |使用对应网络解析域名，获取一个IP，调用callbac |
59| on(type: 'netAvailable', callback: Callback\<NetHandle>): void;                   |订阅网络可用事件 |
60| on(type: 'netCapabilitiesChange', callback: Callback\<NetCapabilityInfo\>): void; |订阅网络能力变化事件 |
61| on(type: 'netConnectionPropertiesChange', callback: Callback\<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void; |订阅网络连接信息变化事件 |
62| on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void; |订阅网络阻塞状态事件，使用callback方式作为异步方法 |
63| on(type: 'netLost', callback: Callback\<NetHandle>): void; |订阅网络丢失事件 |
64| on(type: 'netUnavailable', callback: Callback\<void>): void; |订阅网络不可用事件 |
65| register(callback: AsyncCallback\<void>): void; |订阅指定网络状态变化的通知 |
66| unregister(callback: AsyncCallback\<void>): void; |取消订阅默认网络状态变化的通知 |
67
68## 接收指定网络的状态变化通知
69
701. 声明接口调用所需要的权限：ohos.permission.GET_NETWORK_INFO。
71此权限级别为system_basic，在申请权限前，请保证符合[权限使用的基本原则](../security/accesstoken-overview.md#权限使用的基本原则)。然后参考[配置文件权限声明指导文档](../security/accesstoken-guidelines.md#配置文件权限声明)声明对应权限。
72
732. 从@ohos.net.connection.d.ts中导入connection命名空间。
74
753. 调用createNetConnection方法，指定网络能力、网络类型和超时时间（可选，如不传入代表默认网络；创建不同于默认网络时可通过指定这些参数完成），创建一个NetConnection对象。
76
774. 调用该对象的on()方法，传入type和callback，订阅关心的事件。
78
795. 调用该对象的register()方法，订阅指定网络状态变化的通知。
80
816. 当网络可用时，会收到netAvailable事件的回调；当网络不可用时，会收到netUnavailable事件的回调。
82
837. 当不使用该网络时，可以调用该对象的unregister()方法，取消订阅。
84
85```ts
86// 引入包名
87import connection from '@ohos.net.connection';
88import { BusinessError } from '@ohos.base';
89
90let netSpecifier: connection.NetSpecifier = {
91  netCapabilities: {
92    // 假设当前默认网络是WiFi，需要创建蜂窝网络连接，可指定网络类型为蜂窝网
93    bearerTypes: [connection.NetBearType.BEARER_CELLULAR],
94    // 指定网络能力为Internet
95    networkCap: [connection.NetCap.NET_CAPABILITY_INTERNET]
96  },
97};
98
99// 指定超时时间为10s(默认值为0)
100let timeout = 10 * 1000;
101
102// 创建NetConnection对象
103let conn = connection.createNetConnection(netSpecifier, timeout);
104
105// 订阅事件，如果当前指定网络可用，通过on_netAvailable通知用户
106conn.on('netAvailable', ((data: connection.NetHandle) => {
107  console.log("net is available, netId is " + data.netId);
108}));
109
110// 订阅事件，如果当前指定网络不可用，通过on_netUnavailable通知用户
111conn.on('netUnavailable', ((data: void) => {
112  console.log("net is unavailable, data is " + JSON.stringify(data));
113}));
114
115// 订阅指定网络状态变化的通知
116conn.register((err: BusinessError, data: void) => {
117});
118
119// 当不使用该网络时，可以调用该对象的unregister()方法，取消订阅
120conn.unregister((err: BusinessError, data: void) => {
121});
122```
123
124## 获取所有注册的网络
125
126### 开发步骤
127
1281. 声明接口调用所需要的权限：ohos.permission.GET_NETWORK_INFO。
129此权限级别为system_basic，在申请权限前，请保证符合[权限使用的基本原则](../security/accesstoken-overview.md#权限使用的基本原则)。然后参考[配置文件权限声明指导文档](../security/accesstoken-guidelines.md#配置文件权限声明)声明对应权限。
130
1312. 从@ohos.net.connection.d.ts中导入connection命名空间。
132
1333. 调用getAllNets方法，获取所有处于连接状态的网络列表。
134
135```ts
136// 引入包名
137import connection from '@ohos.net.connection';
138import { BusinessError } from '@ohos.base';
139
140// 构造单例对象
141export class GlobalContext {
142  public netList: connection.NetHandle[] = [];
143  private constructor() {}
144  private static instance: GlobalContext;
145  private _objects = new Map<string, Object>();
146
147  public static getContext(): GlobalContext {
148    if (!GlobalContext.instance) {
149      GlobalContext.instance = new GlobalContext();
150    }
151    return GlobalContext.instance;
152  }
153
154  getObject(value: string): Object | undefined {
155    return this._objects.get(value);
156  }
157
158  setObject(key: string, objectClass: Object): void {
159    this._objects.set(key, objectClass);
160  }
161}
162
163// 获取所有处于连接状态的网络列表
164connection.getAllNets((err: BusinessError, data: connection.NetHandle[]) => {
165  console.log(JSON.stringify(err));
166  console.log(JSON.stringify(data));
167  if (data) {
168    GlobalContext.getContext().netList = data;
169  }
170})
171```
172
173## 根据数据网络查询网络的能力信息及连接信息
174
175### 开发步骤
176
1771. 声明接口调用所需要的权限：ohos.permission.GET_NETWORK_INFO。
178此权限级别为system_basic，在申请权限前，请保证符合[权限使用的基本原则](../security/accesstoken-overview.md#权限使用的基本原则)。然后参考[配置文件权限声明指导文档](../security/accesstoken-guidelines.md#配置文件权限声明)声明对应权限。
179
1802. 从@ohos.net.connection.d.ts中导入connection命名空间。
181
1823. 通过调用getDefaultNet方法，获取默认的数据网络(NetHandle)；或者通过调用getAllNets方法，获取所有处于连接状态的网络列表(Array\<NetHandle>)。
183
1844. 调用getNetCapabilities方法，获取NetHandle对应网络的能力信息。能力信息包含了网络类型(蜂窝网络、Wi-Fi网络、以太网网络等)、网络具体能力等网络信息。
185
1865. 调用getConnectionProperties方法，获取NetHandle对应网络的连接信息。
187
188```ts
189import connection from '@ohos.net.connection';
190import { BusinessError } from '@ohos.base';
191
192// 构造单例对象
193export class GlobalContext {
194  public netList: connection.NetHandle[] = [];
195  public netHandle: connection.NetHandle|null = null;
196  private constructor() {}
197  private static instance: GlobalContext;
198  private _objects = new Map<string, Object>();
199
200  public static getContext(): GlobalContext {
201    if (!GlobalContext.instance) {
202      GlobalContext.instance = new GlobalContext();
203    }
204    return GlobalContext.instance;
205  }
206
207  getObject(value: string): Object | undefined {
208    return this._objects.get(value);
209  }
210
211  setObject(key: string, objectClass: Object): void {
212    this._objects.set(key, objectClass);
213  }
214}
215
216// 调用getDefaultNet方法，获取默认的数据网络(NetHandle)
217connection.getDefaultNet((err: BusinessError, data:connection.NetHandle) => {
218  console.log(JSON.stringify(err));
219  console.log(JSON.stringify(data));
220  if (data) {
221    GlobalContext.getContext().netHandle = data;
222  }
223})
224
225// 获取netHandle对应网络的能力信息。能力信息包含了网络类型、网络具体能力等网络信息
226connection.getNetCapabilities(GlobalContext.getContext().netHandle, (err: BusinessError, data: connection.NetCapabilities) => {
227  console.log(JSON.stringify(err));
228
229  // 获取网络类型(bearerTypes)
230  let bearerTypes: Set<number> = new Set(data.bearerTypes);
231  let bearerTypesNum = Array.from(bearerTypes.values());
232  for (let item of bearerTypesNum) {
233    if (item == 0) {
234      // 蜂窝网
235      console.log(JSON.stringify("BEARER_CELLULAR"));
236    } else if (item == 1) {
237      // Wi-Fi网络
238      console.log(JSON.stringify("BEARER_WIFI"));
239    } else if (item == 3) {
240      // 以太网网络
241      console.log(JSON.stringify("BEARER_ETHERNET"));
242    }
243  }
244
245  // 获取网络具体能力(networkCap)
246  let itemNumber : Set<number> = new Set([0, 11, 12, 15, 16]);
247  let dataNumber = Array.from(itemNumber.values());
248  for (let item of dataNumber) {
249    if (item == 0) {
250      // 表示网络可以访问运营商的MMSC（Multimedia Message Service，多媒体短信服务）发送和接收彩信
251      console.log(JSON.stringify("NET_CAPABILITY_MMS"));
252    } else if (item == 11) {
253      // 表示网络流量未被计费
254      console.log(JSON.stringify("NET_CAPABILITY_NOT_METERED"));
255    } else if (item == 12) {
256      // 表示该网络应具有访问Internet的能力，该能力由网络提供者设置
257      console.log(JSON.stringify("NET_CAPABILITY_INTERNET"));
258    } else if (item == 15) {
259      // 表示网络不使用VPN（Virtual Private Network，虚拟专用网络）
260      console.log(JSON.stringify("NET_CAPABILITY_NOT_VPN"));
261    } else if (item == 16) {
262      // 表示该网络访问Internet的能力被网络管理成功验证，该能力由网络管理模块设置
263      console.log(JSON.stringify("NET_CAPABILITY_VALIDATED"));
264    }
265  }
266})
267
268// 获取netHandle对应网络的连接信息。连接信息包含了链路信息、路由信息等
269connection.getConnectionProperties(GlobalContext.getContext().netHandle, (err: BusinessError, data: connection.ConnectionProperties) => {
270  console.log(JSON.stringify(err));
271  console.log(JSON.stringify(data));
272})
273
274// 调用getAllNets,获取所有处于连接状态的网络列表(Array<NetHandle>)
275connection.getAllNets((err: BusinessError, data: connection.NetHandle[]) => {
276  console.log(JSON.stringify(err));
277  console.log(JSON.stringify(data));
278  if (data) {
279    GlobalContext.getContext().netList = data;
280  }
281})
282
283let itemNumber : Set<connection.NetHandle> = new Set(GlobalContext.getContext().netList);
284let dataNumber = Array.from(itemNumber.values());
285for (let item of dataNumber) {
286  // 循环获取网络列表每个netHandle对应网络的能力信息
287  connection.getNetCapabilities(item, (err: BusinessError, data: connection.NetCapabilities) => {
288    console.log(JSON.stringify(err));
289    console.log(JSON.stringify(data));
290  })
291
292  // 循环获取网络列表每个netHandle对应的网络的连接信息
293  connection.getConnectionProperties(item, (err: BusinessError, data: connection.ConnectionProperties) => {
294    console.log(JSON.stringify(err));
295    console.log(JSON.stringify(data));
296  })
297}
298```
299
300## 使用对应网络解析域名，获取所有IP
301
302### 开发步骤
303
3041. 声明接口调用所需要的权限：ohos.permission.INTERNET
305此权限级别为system_basic，在申请权限前，请保证符合[权限使用的基本原则](../security/accesstoken-overview.md#权限使用的基本原则)。然后参考[配置文件权限声明指导文档](../security/accesstoken-guidelines.md#配置文件权限声明)声明对应权限。
306
3072. 从@ohos.net.connection.d.ts中导入connection命名空间。
308
3093. 调用getAddressesByName方法，使用默认网络解析主机名以获取所有IP地址。
310
311```ts
312// 引入包名
313import connection from '@ohos.net.connection';
314import { BusinessError } from '@ohos.base';
315
316// 使用默认网络解析主机名以获取所有IP地址
317connection.getAddressesByName(this.host, (err: BusinessError, data: connection.NetAddress[]) => {
318  console.log(JSON.stringify(err));
319  console.log(JSON.stringify(data));
320})
321```
322