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