1# # @ohos.net.ethernet (Ethernet Connection Management) 2 3The **ethernet** module provides wired network capabilities, which allow users to set the IP address, subnet mask, gateway, and Domain Name System (DNS) server of a wired network. 4 5> **NOTE** 6> 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. 7 8## Modules to Import 9 10```js 11import ethernet from '@ohos.net.ethernet' 12``` 13 14## ethernet.setIfaceConfig 15 16setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallback\<void>): void 17 18Sets the network interface configuration. This API uses an asynchronous callback to return the result. 19 20**System API**: This is a system API. 21 22**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL 23 24**System capability**: SystemCapability.Communication.NetManager.Ethernet 25 26**Parameters** 27 28| Name | Type | Mandatory| Description | 29| -------- | ------------------------------------------------- | ---- | ------------------------------------------ | 30| iface | string | Yes | Interface name. | 31| ic | [InterfaceConfiguration](#interfaceconfiguration) | Yes | Network interface configuration to set. | 32| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, the return result is empty. If the operation fails, an error code is returned.| 33 34**Error codes** 35 36| ID| Error Message | 37| ------- | ----------------------------------------| 38| 201 | Permission denied. | 39| 401 | Parameter error. | 40| 2200001 | Invalid parameter value. | 41| 2200002 | Operation failed. Cannot connect to service.| 42| 2200003 | System internal error. | 43| 2201005 | The device information does not exist. | 44| 2201006 | Device disconnected. | 45| 2201007 | Failed to write the user configuration. | 46 47**Example** 48 49```js 50ethernet.setIfaceConfig("eth0", { 51 mode: 0, 52 ipAddr: "192.168.xx.xxx", 53 route: "192.168.xx.xxx", 54 gateway: "192.168.xx.xxx", 55 netMask: "255.255.255.0", 56 dnsServers: "1.1.1.1" 57}, (error) => { 58 if (error) { 59 console.log("setIfaceConfig callback error = " + JSON.stringify(error)); 60 } else { 61 console.log("setIfaceConfig callback ok "); 62 } 63}); 64``` 65 66## ethernet.setIfaceConfig 67 68setIfaceConfig(iface: string, ic: InterfaceConfiguration): Promise\<void> 69 70Sets the network interface configuration. This API uses a promise to return the result. 71 72**System API**: This is a system API. 73 74**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL 75 76**System capability**: SystemCapability.Communication.NetManager.Ethernet 77 78**Parameters** 79 80| Name| Type | Mandatory| Description | 81| ------ | ------------------------------------------------- | ---- | ------------------------ | 82| iface | string | Yes | Interface name. | 83| ic | [InterfaceConfiguration](#interfaceconfiguration) | Yes | Network interface configuration to set.| 84 85**Return value** 86 87| Type | Description | 88| ------------------- | ----------------------------------------------------------- | 89| Promise\<void> | Promise used to return the result. If the operation is successful, the return result is empty. If the operation fails, an error code is returned.| 90 91**Error codes** 92 93| ID| Error Message | 94| ------- | ----------------------------------------| 95| 201 | Permission denied. | 96| 401 | Parameter error. | 97| 2200001 | Invalid parameter value. | 98| 2200002 | Operation failed. Cannot connect to service.| 99| 2200003 | System internal error. | 100| 2201005 | The device information does not exist. | 101| 2201006 | Device disconnected. | 102| 2201007 | Failed to write the user configuration. | 103 104**Example** 105 106```js 107ethernet.setIfaceConfig("eth0", { 108 mode: 0, 109 ipAddr: "192.168.xx.xxx", 110 route: "192.168.xx.xxx", 111 gateway: "192.168.xx.xxx", 112 netMask: "255.255.255.0", 113 dnsServers: "1.1.1.1" 114}).then(() => { 115 console.log("setIfaceConfig promise ok "); 116}).catch(error => { 117 console.log("setIfaceConfig promise error = " + JSON.stringify(error)); 118}); 119``` 120 121## ethernet.getIfaceConfig 122 123getIfaceConfig(iface: string, callback: AsyncCallback\<InterfaceConfiguration>): void 124 125Obtains the configuration of a network interface. This API uses an asynchronous callback to return the result. 126 127**System API**: This is a system API. 128 129**Required permission**: ohos.permission.GET_NETWORK_INFO 130 131**System capability**: SystemCapability.Communication.NetManager.Ethernet 132 133**Parameters** 134 135| Name | Type | Mandatory | Description | 136| -------- | ----------------------------------------------- | ----- | ------------ | 137| iface | string | Yes | Interface name.| 138| callback | AsyncCallback\<[InterfaceConfiguration](#interfaceconfiguration)> | Yes | Callback used to return the result. | 139 140**Error codes** 141 142| ID| Error Message | 143| ------- | ----------------------------------------| 144| 201 | Permission denied. | 145| 401 | Parameter error. | 146| 2200001 | Invalid parameter value. | 147| 2200002 | Operation failed. Cannot connect to service.| 148| 2200003 | System internal error. | 149| 2201005 | The device information does not exist. | 150 151**Example** 152 153```js 154ethernet.getIfaceConfig("eth0", (error, value) => { 155 if (error) { 156 console.log("getIfaceConfig callback error = " + JSON.stringify(error)); 157 } else { 158 console.log("getIfaceConfig callback mode = " + JSON.stringify(value.mode)); 159 console.log("getIfaceConfig callback ipAddr = " + JSON.stringify(value.ipAddr)); 160 console.log("getIfaceConfig callback route = " + JSON.stringify(value.route)); 161 console.log("getIfaceConfig callback gateway = " + JSON.stringify(value.gateway)); 162 console.log("getIfaceConfig callback netMask = " + JSON.stringify(value.netMask)); 163 console.log("getIfaceConfig callback dnsServers = " + JSON.stringify(value.dnsServers)); 164 } 165}); 166``` 167 168## ethernet.getIfaceConfig 169 170getIfaceConfig(iface: string): Promise\<InterfaceConfiguration> 171 172Obtains the configuration of a network interface. This API uses a promise to return the result. 173 174**System API**: This is a system API. 175 176**Required permission**: ohos.permission.GET_NETWORK_INFO 177 178**System capability**: SystemCapability.Communication.NetManager.Ethernet 179 180**Parameters** 181 182| Name | Type | Mandatory| Description | 183| -------- | --------------------------------------- | ---- | ------------ | 184| iface | string | Yes | Interface name.| 185 186**Return value** 187 188| Type | Description | 189| --------------------------------- | ---------------------------------- | 190| Promise\<[InterfaceConfiguration](#interfaceconfiguration)> | Promise used to return the result. | 191 192**Error codes** 193 194| ID| Error Message | 195| ------- | ----------------------------------------| 196| 201 | Permission denied. | 197| 401 | Parameter error. | 198| 2200001 | Invalid parameter value. | 199| 2200002 | Operation failed. Cannot connect to service.| 200| 2200003 | System internal error. | 201| 2201005 | The device information does not exist. | 202 203**Example** 204 205```js 206ethernet.getIfaceConfig("eth0").then((data) => { 207 console.log("getIfaceConfig promise mode = " + JSON.stringify(data.mode)); 208 console.log("getIfaceConfig promise ipAddr = " + JSON.stringify(data.ipAddr)); 209 console.log("getIfaceConfig promise route = " + JSON.stringify(data.route)); 210 console.log("getIfaceConfig promise gateway = " + JSON.stringify(data.gateway)); 211 console.log("getIfaceConfig promise netMask = " + JSON.stringify(data.netMask)); 212 console.log("getIfaceConfig promise dnsServers = " + JSON.stringify(data.dnsServers)); 213}).catch(error => { 214 console.log("getIfaceConfig promise error = " + JSON.stringify(error)); 215}); 216``` 217 218## ethernet.isIfaceActive 219 220isIfaceActive(iface: string, callback: AsyncCallback\<number>): void 221 222Checks whether a network interface is active. This API uses an asynchronous callback to return the result. 223 224**System API**: This is a system API. 225 226**Required permission**: ohos.permission.GET_NETWORK_INFO 227 228**System capability**: SystemCapability.Communication.NetManager.Ethernet 229 230**Parameters** 231 232| Name | Type | Mandatory| Description | 233| -------- | --------------------------- | ---- | -------------------------------------------------- | 234| iface | string | Yes | Interface name. If this parameter is left empty, the API checks for any active network interface. | 235| callback | AsyncCallback\<number> | Yes | Callback used to return the result. The value **1** means that the network interface is active, **0** means that the network interface is inactive, and any other value means that an error has occurred.| 236 237**Error codes** 238 239| ID| Error Message | 240| ------- | ----------------------------------------| 241| 201 | Permission denied. | 242| 401 | Parameter error. | 243| 2200001 | Invalid parameter value. | 244| 2200002 | Operation failed. Cannot connect to service.| 245| 2200003 | System internal error. | 246| 2201005 | The device information does not exist. | 247 248**Example** 249 250```js 251ethernet.isIfaceActive("eth0", (error, value) => { 252 if (error) { 253 console.log("whether2Activate callback error = " + JSON.stringify(error)); 254 } else { 255 console.log("whether2Activate callback = " + JSON.stringify(value)); 256 } 257}); 258``` 259 260## ethernet.isIfaceActive 261 262isIfaceActive(iface: string): Promise\<number> 263 264Checks whether a network interface is active. This API uses a promise to return the result. 265 266**System API**: This is a system API. 267 268**Required permission**: ohos.permission.GET_NETWORK_INFO 269 270**System capability**: SystemCapability.Communication.NetManager.Ethernet 271 272**Parameters** 273 274| Name| Type | Mandatory| Description | 275| ------ | ------ | ---- | -------------------------------------- | 276| iface | string | Yes | Interface name. If this parameter is left empty, the API checks for any active network interface.| 277 278**Return value** 279 280| Type | Description | 281| ----------------| ------------------------------------------------------------------ | 282| Promise\<number> | Promise used to return the result. The value **1** means that the network interface is active, **0** means that the network interface is inactive, and any other value means that an error has occurred.| 283 284**Error codes** 285 286| ID| Error Message | 287| ------- | ----------------------------------------| 288| 201 | Permission denied. | 289| 401 | Parameter error. | 290| 2200001 | Invalid parameter value. | 291| 2200002 | Operation failed. Cannot connect to service.| 292| 2200003 | System internal error. | 293| 2201005 | The device information does not exist. | 294 295**Example** 296 297```js 298ethernet.isIfaceActive("eth0").then((data) => { 299 console.log("isIfaceActive promise = " + JSON.stringify(data)); 300}).catch(error => { 301 console.log("isIfaceActive promise error = " + JSON.stringify(error)); 302}); 303``` 304 305## ethernet.getAllActiveIfaces 306 307getAllActiveIfaces(callback: AsyncCallback\<Array\<string>>): void 308 309Obtains the list of all active network interfaces. This API uses an asynchronous callback to return the result. 310 311**System API**: This is a system API. 312 313**Required permission**: ohos.permission.GET_NETWORK_INFO 314 315**System capability**: SystemCapability.Communication.NetManager.Ethernet 316 317**Parameters** 318 319| Name | Type | Mandatory| Description | 320| -------- | ------------------------------------ | ---- | ------------------------------ | 321| callback | AsyncCallback\<Array\<string>> | Yes | Callback used to return the result.| 322 323**Error codes** 324 325| ID| Error Message | 326| ------- | ----------------------------------------| 327| 201 | Permission denied. | 328| 2200002 | Operation failed. Cannot connect to service.| 329| 2200003 | System internal error. | 330 331**Example** 332 333```js 334ethernet.getAllActiveIfaces((error, value) => { 335 if (error) { 336 console.log("getAllActiveIfaces callback error = " + JSON.stringify(error)); 337 } else { 338 console.log("getAllActiveIfaces callback value.length = " + JSON.stringify(value.length)); 339 for (let i = 0; i < value.length; i++) { 340 console.log("getAllActiveIfaces callback = " + JSON.stringify(value[i])); 341 } 342 } 343}); 344``` 345 346## ethernet.getAllActiveIfaces 347 348getAllActiveIfaces(): Promise\<Array\<string>> 349 350Obtains the list of all active network interfaces. This API uses a promise to return the result. 351 352**System API**: This is a system API. 353 354**Required permission**: ohos.permission.GET_NETWORK_INFO 355 356**System capability**: SystemCapability.Communication.NetManager.Ethernet 357 358**Return value** 359 360| Type | Description | 361| ------------------------------ | ----------------------------------------------- | 362| Promise\<Array\<string>> | Promise used to return the result. | 363 364**Error codes** 365 366| ID| Error Message | 367| ------- | ----------------------------------------| 368| 201 | Permission denied. | 369| 2200002 | Operation failed. Cannot connect to service.| 370| 2200003 | System internal error. | 371 372**Example** 373 374```js 375ethernet.getAllActiveIfaces().then((data) => { 376 console.log("getAllActiveIfaces promise data.length = " + JSON.stringify(data.length)); 377 for (let i = 0; i < data.length; i++) { 378 console.log("getAllActiveIfaces promise = " + JSON.stringify(data[i])); 379 } 380}).catch(error => { 381 console.log("getAllActiveIfaces promise error = " + JSON.stringify(error)); 382}); 383``` 384 385## InterfaceConfiguration 386 387Defines the network configuration for the Ethernet connection. 388 389**System API**: This is a system API. 390 391**System capability**: SystemCapability.Communication.NetManager.Ethernet 392 393| Name | Type | Mandatory| Description | 394| ------------ | ----------------------- | ---|------------------------------------------------------------ | 395| mode | [IPSetMode](#ipsetmode) | Yes| Configuration mode of the Ethernet connection.| 396| ipAddr | string | Yes| Static IP address of the Ethernet connection. The value must be an IPv4 address, which is a 32-bit number displayed in dotted decimal notation and each 8-bit field ranges from 0 to 255. This parameter does not need to be configured in Dynamic Host Configuration Protocol (DHCP) mode.| 397| route | string | Yes| Route of the Ethernet connection. The value must be an IPv4 address, which is a 32-bit number displayed in dotted decimal notation and each 8-bit field ranges from 0 to 255. This parameter does not need to be configured in DHCP mode.| 398| gateway | string | Yes| Gateway of the Ethernet connection. The value must be an IPv4 address, which is a 32-bit number displayed in dotted decimal notation and each 8-bit field ranges from 0 to 255. This parameter does not need to be configured in DHCP mode.| 399| netMask | string | Yes| Subnet mask of the Ethernet connection. The value must be an IPv4 address, which is a 32-bit number displayed in dotted decimal notation and each 8-bit field ranges from 0 to 255. This parameter does not need to be configured in DHCP mode.| 400| dnsServers | string | Yes| DNS server addresses of the Ethernet connection. The value must be an IPv4 address. This parameter does not need to be configured in DHCP mode. Multiple addresses are separated by commas (,).| 401 402## IPSetMode 403 404Defines the configuration mode of the Ethernet connection. 405 406**System API**: This is a system API. 407 408**System capability**: SystemCapability.Communication.NetManager.Ethernet 409 410| Name | Value | Description | 411| ------------------------ | ---- | ---------------------- | 412| STATIC | 0 | Static configuration.| 413| DHCP | 1 | Dynamic configuration.| 414