1# Ethernet Connection 2 3## Overview 4 5The Ethernet Connection module allows a device to access the Internet through a network cable. After a device is connected to the Ethernet through a network cable, the device can obtain a series of network attributes, such as the dynamically allocated IP address, subnet mask, gateway, and DNS. You can manually configure and obtain the network attributes of the device in static mode. 6 7> **NOTE** 8> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see [sms API Reference](../reference/apis/js-apis-net-ethernet.md). 9 10## **Constraints** 11 12- Programming language: C++ and JS 13- System: Linux kernel 14- The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15 16## Scenario 17 18Typical application scenarios of Ethernet connection are as follows: 19 20- Dynamically assigning a series of network attributes, such as the IP address, subnet mask, gateway, and DNS in DHCP mode to enable network access 21- Configuring a series of network attributes, such as the IP address, subnet mask, gateway, and DNS, in static mode to enable network access. 22 23The following describes the development procedure specific to each application scenario. 24 25## Available APIs 26 27For the complete list of APIs and example code, see [Ethernet Connection](../reference/apis/js-apis-net-ethernet.md). 28 29| Type| API| Description| 30| ---- | ---- | ---- | 31| ohos.net.ethernet | function setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallback\<void>): void | Configures the network attributes of the specified Ethernet network. This API uses an asynchronous callback to return the result.| 32| ohos.net.ethernet | function getIfaceConfig(iface: string, callback: AsyncCallback\<InterfaceConfiguration>): void | Obtains the network attributes of the specified Ethernet network. This API uses an asynchronous callback to return the result.| 33| ohos.net.ethernet | function isIfaceActive(iface: string, callback: AsyncCallback\<number>): void | Checks whether the specified network port is active. This API uses an asynchronous callback to return the result.| 34| ohos.net.ethernet | function getAllActiveIfaces(callback: AsyncCallback\<Array\<string>>): void; | Obtains the list of all active network ports. This API uses an asynchronous callback to return the result.| 35| ohos.net.ethernet | function on(type: 'interfaceStateChange', callback: Callback\<{ iface: string, active: boolean }\>): void; | Subscribes to interface state change events.| 36| ohos.net.ethernet | function off(type: 'interfaceStateChange', callback?: Callback\<{ iface: string, active: boolean }\>): void; | Unsubscribes from interface state change events.| 37 38## Ethernet Connection – DHCP Mode 39 401. Use a network cable to connect the device to a network port. 412. Import the **ethernet** namespace from **@ohos.net.ethernet**. 423. Call **getAllActiveIfaces** to obtain the list of all active network ports, for example, **eth0** and **eth1**. 434. Call **isIfaceActive** in user mode to check whether the **eth0** port is active. 445. Call **getIfaceConfig** in user mode to obtain the static network attributes of the **eth0** port. By default, an unconfigured Ethernet network uses the DHCP mode, in which the Ethernet network obtains the automatically assigned network attributes. 45 46```ts 47// Import the ethernet namespace from @ohos.net.ethernet. 48import ethernet from '@ohos.net.ethernet' 49import { BusinessError } from '@ohos.base'; 50 51// Call getAllActiveIfaces to obtain the list of all active network ports. 52ethernet.getAllActiveIfaces((error: BusinessError, data: string[]) => { 53 if (error) { 54 console.log("getAllActiveIfaces callback error = " + error); 55 } else { 56 console.log("getAllActiveIfaces callback data.length = " + data.length); 57 for (let i = 0; i < data.length; i++) { 58 console.log("getAllActiveIfaces callback = " + data[i]); 59 } 60 } 61}); 62 63// Call isIfaceActive to check whether the specified network port is active. 64ethernet.isIfaceActive("eth0", (error: BusinessError, data: number) => { 65 if (error) { 66 console.log("isIfaceActive callback error = " + error); 67 } else { 68 console.log("isIfaceActive callback = " + data); 69 } 70}); 71 72// Call getIfaceConfig to obtain the network attributes of the specified Ethernet network. 73ethernet.getIfaceConfig("eth0", (error: BusinessError, data: ethernet.InterfaceConfiguration) => { 74 if (error) { 75 console.log("getIfaceConfig callback error = " + error); 76 } else { 77 console.log("getIfaceConfig callback mode = " + data.mode); 78 console.log("getIfaceConfig callback ipAddr = " + data.ipAddr); 79 console.log("getIfaceConfig callback routeAddr = " + data.routeAddr); 80 console.log("getIfaceConfig callback gateAddr = " + data.gateAddr); 81 console.log("getIfaceConfig callback maskAddr = " + data.maskAddr); 82 console.log("getIfaceConfig callback dns0Addr = " + data.dns0Addr); 83 console.log("getIfaceConfig callback dns1Addr = " + data.dns1Addr); 84 } 85}); 86``` 87 88## Ethernet Connection – Static Mode 89 90### How to Develop 91 921. Use a network cable to connect the device to a network port. 932. Import the **ethernet** namespace from **@ohos.net.ethernet**. 943. Call **getAllActiveIfaces** in user mode to obtain the list of all active network ports, for example, **eth0** and **eth1**. 954. Call **isIfaceActive** in user mode to check whether the **eth0** port is active. 965. Call **setIfaceConfig** in user mode to set the **eth0** port to the static mode, in which you need to manually assign the network attributes (including the IP address, subnet mask, gateway, and DNS). 976. Call **getIfaceConfig** in user mode to obtain the static network attributes of the **eth0** port. 98 99```ts 100// Import the ethernet namespace from @ohos.net.ethernet. 101import ethernet from '@ohos.net.ethernet' 102import { BusinessError } from '@ohos.base'; 103 104// Call getAllActiveIfaces to obtain the list of all active network ports. 105ethernet.getAllActiveIfaces((error: BusinessError, data: string[]) => { 106 if (error) { 107 console.log("getAllActiveIfaces callback error = " + error); 108 } else { 109 console.log("getAllActiveIfaces callback data.length = " + data.length); 110 for (let i = 0; i < data.length; i++) { 111 console.log("getAllActiveIfaces callback = " + data[i]); 112 } 113 } 114}); 115 116// Call isIfaceActive to check whether the specified network port is active. 117ethernet.isIfaceActive("eth0", (error: BusinessError, data: number) => { 118 if (error) { 119 console.log("isIfaceActive callback error = " + error); 120 } else { 121 console.log("isIfaceActive callback = " + data); 122 } 123}); 124 125let ethernetParam: ethernet.InterfaceConfiguration = { 126 mode: ethernet.IPSetMode.STATIC, 127 ipAddr: "192.168.xx.xx", 128 routeAddr: "192.168.xx.xx", 129 gateAddr: "192.168.xx.xx", 130 maskAddr: "255.255.xx.xx", 131 dnsAddr0: "1.1.xx.xx", 132 dnsAddr1: "2.2.xx.xx" 133} 134 135// Call setIfaceConfig to configure the network attributes of the specified Ethernet network. 136ethernet.setIfaceConfig("eth0", ethernetParam, (error: BusinessError) => { 137 if (error) { 138 console.log("setIfaceConfig callback error = " + error); 139 } else { 140 console.log("setIfaceConfig callback ok "); 141 } 142}); 143 144// Call getIfaceConfig to obtain the network attributes of the specified Ethernet network. 145ethernet.getIfaceConfig("eth0", (error: BusinessError, data: ethernet.InterfaceConfiguration) => { 146 if (error) { 147 console.log("getIfaceConfig callback error = " + error); 148 } else { 149 console.log("getIfaceConfig callback mode = " + data.mode); 150 console.log("getIfaceConfig callback ipAddr = " + data.ipAddr); 151 console.log("getIfaceConfig callback routeAddr = " + data.routeAddr); 152 console.log("getIfaceConfig callback gateAddr = " + data.gateAddr); 153 console.log("getIfaceConfig callback maskAddr = " + data.maskAddr); 154 console.log("getIfaceConfig callback dns0Addr = " + data.dns0Addr); 155 console.log("getIfaceConfig callback dns1Addr = " + data.dns1Addr); 156 } 157}); 158``` 159 160## Subscribes the status change of network device interfaces. 161 162### How to Develop 163 1641. Import the **ethernet** namespace from **@ohos.net.ethernet**. 1652. Call the **on()** method to subscribe to **interfaceStateChange** events. It is up to you whether to listen for **interfaceStateChange** events. 1663. Check whether an **interfaceStateChange** event is triggered when the interface state changes. 1674. Call the **off()** method to unsubscribe from **interfaceStateChange** events. 168 169```ts 170// Import the ethernet namespace from @ohos.net.ethernet. 171import ethernet from '@ohos.net.ethernet' 172 173// Subscribe to interfaceStateChange events. 174class EthernetData{ 175 iface: string = "" 176 active: boolean = false 177} 178 179ethernet.on('interfaceStateChange', (data: EthernetData) => { 180 console.log(JSON.stringify(data)); 181}); 182 183// Unsubscribe from interfaceStateChange events. 184ethernet.off('interfaceStateChange'); 185``` 186