1# 以太网连接（仅对系统应用开放）
2
3## 简介
4
5以太网连接的功能是提供支持设备通过硬件接口，以插入网线的形式访问互联网的能力。 设备接入网线后，可以获取动态分配的IP地址，子网掩码，Gateway，DNS等一系列网络属性；通过静态模式，手动配置与获取设备的网络属性。
6
7> **说明：**
8> 为了保证应用的运行效率，大部分API调用都是异步的，对于异步调用的API均提供了callback和Promise两种方式，以下示例均采用promise函数，更多方式可以查阅[API参考](../reference/apis-network-kit/js-apis-net-ethernet-sys.md)。
9
10## 约束
11
12- 开发语言：JS
13- 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
14
15## 场景介绍
16
17以太网连接的典型场景有：
18
19- DHCP模式，通过动态分配IP地址，子网掩码，Gateway，DNS等一系列网络属性，使能访问网络。
20- 静态模式，通过静态配置IP地址，子网掩码，Gateway，DNS等一系列网络属性，使能访问网络。
21
22以下分别介绍具体开发方式。
23
24## 接口说明
25
26完整的JS API说明以及实例代码请参考：[以太网连接](../reference/apis-network-kit/js-apis-net-ethernet-sys.md)。
27
28| 类型 | 接口 | 功能说明 |
29| ---- | ---- | ---- |
30| setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallback\<void>): void | 配置指定以太网的网络属性，iface为网口名称，ic为配置信息，调用callback ||
31| getIfaceConfig(iface: string, callback: AsyncCallback\<InterfaceConfiguration>): void | 获取指定以太网的网络属性，iface为网口名称，调用callback ||
32| isIfaceActive(iface: string, callback: AsyncCallback\<number>): void | 判断指定网口是否已激活，iface为网卡名称（无参为是否有激活网口），调用callback ||
33| getAllActiveIfaces(callback: AsyncCallback\<Array\<string>>): void | 获取所有活动的网络接口，调用callback ||
34| on(type: 'interfaceStateChange', callback: Callback\<{ iface: string, active: boolean }\>): void | 注册网络接口监听函数 ||
35| off(type: 'interfaceStateChange', callback?: Callback\<{ iface: string, active: boolean }\>): void | 解除注册网络接口监听函数 ||
36
37## 以太网连接-DHCP模式
38
391. 设备通过硬件接口，插入网线。
402. 从@kit.NetworkKit中导入ethernet命名空间。
413. 调用getAllActiveIfaces方法，获取所有激活的有线网卡名称，如：“eth0”，“eth1”。
424. 用户态通过isIfaceActive方法，来判断网口“eth0”是否已激活。
435. 用户态通过getIfaceConfig方法，来获取指定网口“eth0”的网络属性，未设置过的以太网络默认为DHCP模式，获取自动分配的网络属性。
44
45```ts
46// 从@kit.NetworkKit中导入ethernet命名空间
47import { ethernet } from '@kit.NetworkKit';
48import { BusinessError } from '@kit.BasicServicesKit';
49
50// getAllActiveIfaces获取所有活动的网络设备名称
51ethernet.getAllActiveIfaces().then((data: string[]) => {
52  console.log("getAllActiveIfaces promise data.length = " + JSON.stringify(data.length));
53  for (let i = 0; i < data.length; i++) {
54    console.log("getAllActiveIfaces promise  = " + JSON.stringify(data[i]));
55  }
56}).catch((error:BusinessError) => {
57  console.log("getAllActiveIfaces promise error = " + JSON.stringify(error));
58});
59
60// isIfaceActive判断指定网口是否已激活
61ethernet.isIfaceActive("eth0").then((data: number) => {
62  console.log("isIfaceActive promise = " + JSON.stringify(data));
63}).catch((error: BusinessError) => {
64  console.log("isIfaceActive promise error = " + JSON.stringify(error));
65});
66
67// getIfaceConfig获取指定以太网的网络属性
68ethernet.getIfaceConfig("eth0").then((data: ethernet.InterfaceConfiguration) => {
69  console.log("getIfaceConfig promise mode = " + JSON.stringify(data.mode));
70  console.log("getIfaceConfig promise ipAddr = " + JSON.stringify(data.ipAddr));
71  console.log("getIfaceConfig promise route = " + JSON.stringify(data.route));
72  console.log("getIfaceConfig promise gateway = " + JSON.stringify(data.gateway));
73  console.log("getIfaceConfig promise netMask = " + JSON.stringify(data.netMask));
74  console.log("getIfaceConfig promise dnsServers = " + JSON.stringify(data.dnsServers));
75}).catch((error: BusinessError) => {
76  console.log("getIfaceConfig promise error = " + JSON.stringify(error));
77});
78```
79
80## 以太网连接-静态模式
81
82### 开发步骤
83
841. 设备通过硬件接口，插入网线。
852. 从@kit.NetworkKit中导入ethernet命名空间。
863. 用户态通过getAllActiveIfaces方法，来获取所有活动的网络设备名称，如：“eth0”，“eth1”。
874. 用户态通过isIfaceActive方法，来判断网口“eth0”是否已激活。
885. 用户态调用setIfaceConfig方法，来设置指定网口"eth0"为静态模式，手动IP地址，子网掩码，Gateway，DNS等网络属性。
896. 用户态通过getIfaceConfig方法，来获取指定网口“eth0”的静态网络属性。
90
91```ts
92// 从@kit.NetworkKit中导入ethernet命名空间
93import { ethernet } from '@kit.NetworkKit';
94import { BusinessError } from '@kit.BasicServicesKit';
95
96// getAllActiveIfaces获取所有活动的网络设备名称
97ethernet.getAllActiveIfaces().then((data: string[]) => {
98  console.log("getAllActiveIfaces promise data.length = " + JSON.stringify(data.length));
99  for (let i = 0; i < data.length; i++) {
100    console.log("getAllActiveIfaces promise  = " + JSON.stringify(data[i]));
101  }
102}).catch((error:BusinessError) => {
103  console.log("getAllActiveIfaces promise error = " + JSON.stringify(error));
104});
105
106// isIfaceActive判断指定网口是否已激活
107ethernet.isIfaceActive("eth0").then((data: number) => {
108  console.log("isIfaceActive promise = " + JSON.stringify(data));
109}).catch((error: BusinessError) => {
110  console.log("isIfaceActive promise error = " + JSON.stringify(error));
111});
112
113// setIfaceConfig配置指定以太网的网络属性
114let config: ethernet.InterfaceConfiguration = {
115  mode: 0,
116  ipAddr: "192.168.xx.xxx",
117  route: "192.168.xx.xxx",
118  gateway: "192.168.xx.xxx",
119  netMask: "255.255.255.0",
120  dnsServers: "1.1.1.1"
121};
122
123const setConfigPromise = ethernet.setIfaceConfig("eth0", config);
124
125setConfigPromise.then(() => {
126  console.log("setIfaceConfig promise ok");
127}).catch((error: BusinessError)  => {
128  console.log("setIfaceConfig promise error = " + JSON.stringify(error));
129});
130
131// getIfaceConfig获取指定以太网的网络属性
132ethernet.getIfaceConfig("eth0").then((data: ethernet.InterfaceConfiguration) => {
133  console.log("getIfaceConfig promise mode = " + JSON.stringify(data.mode));
134  console.log("getIfaceConfig promise ipAddr = " + JSON.stringify(data.ipAddr));
135  console.log("getIfaceConfig promise route = " + JSON.stringify(data.route));
136  console.log("getIfaceConfig promise gateway = " + JSON.stringify(data.gateway));
137  console.log("getIfaceConfig promise netMask = " + JSON.stringify(data.netMask));
138  console.log("getIfaceConfig promise dnsServers = " + JSON.stringify(data.dnsServers));
139}).catch((error: BusinessError) => {
140  console.log("getIfaceConfig promise error = " + JSON.stringify(error));
141});
142```
143
144## 监听网络设备接口状态变化
145
146### 开发步骤
147
1481. 从@kit.NetworkKit中导入ethernet命名空间。
1492. 调用该对象的on()方法，订阅interfaceStateChange事件。可以根据业务需要订阅此消息。
1503. 订阅interfaceStateChange事件后，回调函数会在网卡设备的接口状态发生变化时触发。
1514. 调用该对象的off()方法，取消订阅interfaceStateChange事件。
152
153```ts
154// 从@kit.NetworkKit中导入ethernet命名空间
155import { ethernet } from '@kit.NetworkKit';
156
157// 订阅interfaceStateChange事件
158class EthernetData{
159  iface: string = ""
160  active: boolean = false
161}
162
163ethernet.on('interfaceStateChange', (data: EthernetData) => {
164  console.log(JSON.stringify(data));
165});
166
167// 取消事件订阅
168ethernet.off('interfaceStateChange');
169```
170