1# Ethernet Connection (For System Applications Only) 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 promise mode. For details about the APIs, see [API Reference](../reference/apis-network-kit/js-apis-net-ethernet-sys.md). 9 10## **Constraints** 11 12- Programming language: JS 13- 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. 14 15## Scenario 16 17Typical application scenarios of Ethernet connection are as follows: 18 19- Dynamically assigning a series of network attributes, such as the IP address, subnet mask, gateway, and DNS in DHCP mode to enable network access 20- Configuring a series of network attributes, such as the IP address, subnet mask, gateway, and DNS, in static mode to enable network access. 21 22The following describes the development procedure specific to each application scenario. 23 24## Available APIs 25 26For the complete list of APIs and example code, see [Ethernet Connection](../reference/apis-network-kit/js-apis-net-ethernet-sys.md). 27 28| Type| API| Description| 29| ---- | ---- | ---- | 30| 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.| 31| 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.| 32| 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.| 33| getAllActiveIfaces(callback: AsyncCallback\<Array\<string>>): void | Obtains the list of all active network ports. This API uses an asynchronous callback to return the result.| 34| on(type: 'interfaceStateChange', callback: Callback\<{ iface: string, active: boolean }\>): void | Subscribes to interface state change events.| 35| off(type: 'interfaceStateChange', callback?: Callback\<{ iface: string, active: boolean }\>): void | Unsubscribes from interface state change events.| 36 37## Ethernet Connection – DHCP Mode 38 391. Use a network cable to connect the device to a network port. 402. Import the **ethernet** namespace from **@kit.NetworkKit**. 413. Call **getAllActiveIfaces** to obtain the list of all active network ports, for example, **eth0** and **eth1**. 424. Call **isIfaceActive** in user mode to check whether the **eth0** port is active. 435. 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. 44 45```ts 46// Import the ethernet namespace from @kit.NetworkKit. 47import { ethernet } from '@kit.NetworkKit'; 48import { BusinessError } from '@kit.BasicServicesKit'; 49 50// Call getAllActiveIfaces to obtain the list of all active network ports. 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// Call isIfaceActive to check whether the specified network port is active. 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// Call getIfaceConfig to obtain the network attributes of the specified Ethernet network. 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## Ethernet Connection – Static Mode 81 82### How to Develop 83 841. Use a network cable to connect the device to a network port. 852. Import the **ethernet** namespace from **@kit.NetworkKit**. 863. Call **getAllActiveIfaces** in user mode to obtain the list of all active network ports, for example, **eth0** and **eth1**. 874. Call **isIfaceActive** in user mode to check whether the **eth0** port is active. 885. 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). 896. Call **getIfaceConfig** in user mode to obtain the static network attributes of the **eth0** port. 90 91```ts 92// Import the ethernet namespace from @kit.NetworkKit. 93import { ethernet } from '@kit.NetworkKit'; 94import { BusinessError } from '@kit.BasicServicesKit'; 95 96// Call getAllActiveIfaces to obtain the list of all active network ports. 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// Call isIfaceActive to check whether the specified network port is active. 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// Call setIfaceConfig to configure the network attributes of the specified Ethernet network. 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// Call getIfaceConfig to obtain the network attributes of the specified Ethernet network. 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## Subscribes the status change of network device interfaces. 145 146### How to Develop 147 1481. Import the **ethernet** namespace from **@kit.NetworkKit**. 1492. Call the **on()** method to subscribe to **interfaceStateChange** events. It is up to you whether to listen for **interfaceStateChange** events. 1503. Check whether an **interfaceStateChange** event is triggered when the interface state changes. 1514. Call the **off()** method to unsubscribe from **interfaceStateChange** events. 152 153```ts 154// Import the ethernet namespace from @kit.NetworkKit. 155import { ethernet } from '@kit.NetworkKit'; 156 157// Subscribe to interfaceStateChange events. 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// Unsubscribe from interfaceStateChange events. 168ethernet.off('interfaceStateChange'); 169``` 170