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, and HTTP proxy 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```ts 11import ethernet from '@ohos.net.ethernet' 12``` 13 14## ethernet.setIfaceConfig<sup>9+</sup> 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](#interfaceconfiguration9) | 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| 202 | Non-system applications use system APIs. | 40| 401 | Parameter error. | 41| 2200001 | Invalid parameter value. | 42| 2200002 | Operation failed. Cannot connect to service.| 43| 2200003 | System internal error. | 44| 2201004 | Invalid Ethernet profile. | 45| 2201005 | Device information does not exist. | 46| 2201006 | Ethernet device not connected. | 47| 2201007 | Ethernet failed to write user configuration information. | 48 49**Example** 50 51```ts 52import ethernet from '@ohos.net.ethernet' 53import { BusinessError } from '@ohos.base' 54 55let config: ethernet.InterfaceConfiguration = { 56 mode: 0, 57 ipAddr: "192.168.xx.xxx", 58 route: "192.168.xx.xxx", 59 gateway: "192.168.xx.xxx", 60 netMask: "255.255.255.0", 61 dnsServers: "1.1.1.1" 62}; 63 64ethernet.setIfaceConfig("eth0", config, (error: BusinessError) => { 65 if (error) { 66 console.log("setIfaceConfig callback error = " + JSON.stringify(error)); 67 } else { 68 console.log("setIfaceConfig callback ok"); 69 } 70}); 71``` 72 73## ethernet.setIfaceConfig<sup>9+</sup> 74 75setIfaceConfig(iface: string, ic: InterfaceConfiguration): Promise\<void> 76 77Sets the network interface configuration. This API uses a promise to return the result. 78 79**System API**: This is a system API. 80 81**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL 82 83**System capability**: SystemCapability.Communication.NetManager.Ethernet 84 85**Parameters** 86 87| Name| Type | Mandatory| Description | 88| ------ | ------------------------------------------------- | ---- | ------------------------ | 89| iface | string | Yes | Interface name. | 90| ic | [InterfaceConfiguration](#interfaceconfiguration9) | Yes | Network interface configuration to set.| 91 92**Return value** 93 94| Type | Description | 95| ------------------- | ----------------------------------------------------------- | 96| 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.| 97 98**Error codes** 99 100| ID| Error Message | 101| ------- | ----------------------------------------| 102| 201 | Permission denied. | 103| 202 | Non-system applications use system APIs. | 104| 401 | Parameter error. | 105| 2200001 | Invalid parameter value. | 106| 2200002 | Operation failed. Cannot connect to service.| 107| 2200003 | System internal error. | 108| 2201004 | Invalid Ethernet profile. | 109| 2201005 | Device information does not exist. | 110| 2201006 | Ethernet device not connected. | 111| 2201007 | Ethernet failed to write user configuration information. | 112 113**Example** 114 115```ts 116import ethernet from '@ohos.net.ethernet' 117import { BusinessError } from '@ohos.base' 118 119let config: ethernet.InterfaceConfiguration = { 120 mode: 0, 121 ipAddr: "192.168.xx.xxx", 122 route: "192.168.xx.xxx", 123 gateway: "192.168.xx.xxx", 124 netMask: "255.255.255.0", 125 dnsServers: "1.1.1.1" 126}; 127 128const setConfigPromise = ethernet.setIfaceConfig("eth0", config); 129 130setConfigPromise.then(() => { 131 console.log("setIfaceConfig promise ok"); 132}).catch((error: BusinessError) => { 133 console.log("setIfaceConfig promise error = " + JSON.stringify(error)); 134}); 135``` 136 137## ethernet.getIfaceConfig<sup>9+</sup> 138 139getIfaceConfig(iface: string, callback: AsyncCallback\<InterfaceConfiguration>): void 140 141Obtains the configuration of a network interface. This API uses an asynchronous callback to return the result. 142 143**System API**: This is a system API. 144 145**Required permission**: ohos.permission.GET_NETWORK_INFO 146 147**System capability**: SystemCapability.Communication.NetManager.Ethernet 148 149**Parameters** 150 151| Name | Type | Mandatory | Description | 152| -------- | ----------------------------------------------- | ----- | ------------ | 153| iface | string | Yes | Interface name.| 154| callback | AsyncCallback\<[InterfaceConfiguration](#interfaceconfiguration9)> | Yes | Callback used to return the result. | 155 156**Error codes** 157 158| ID| Error Message | 159| ------- | ----------------------------------------| 160| 201 | Permission denied. | 161| 202 | Non-system applications use system APIs. | 162| 401 | Parameter error. | 163| 2200001 | Invalid parameter value. | 164| 2200002 | Operation failed. Cannot connect to service.| 165| 2200003 | System internal error. | 166| 2201005 | Device information does not exist. | 167 168**Example** 169 170```ts 171import ethernet from '@ohos.net.ethernet' 172import { BusinessError } from '@ohos.base' 173 174ethernet.getIfaceConfig("eth0", (error: BusinessError, value: ethernet.InterfaceConfiguration) => { 175 if (error) { 176 console.log("getIfaceConfig callback error = " + JSON.stringify(error)); 177 } else { 178 console.log("getIfaceConfig callback mode = " + JSON.stringify(value.mode)); 179 console.log("getIfaceConfig callback ipAddr = " + JSON.stringify(value.ipAddr)); 180 console.log("getIfaceConfig callback route = " + JSON.stringify(value.route)); 181 console.log("getIfaceConfig callback gateway = " + JSON.stringify(value.gateway)); 182 console.log("getIfaceConfig callback netMask = " + JSON.stringify(value.netMask)); 183 console.log("getIfaceConfig callback dnsServers = " + JSON.stringify(value.dnsServers)); 184 } 185}); 186``` 187 188## ethernet.getIfaceConfig<sup>9+</sup> 189 190getIfaceConfig(iface: string): Promise\<InterfaceConfiguration> 191 192Obtains the configuration of a network interface. This API uses a promise to return the result. 193 194**System API**: This is a system API. 195 196**Required permission**: ohos.permission.GET_NETWORK_INFO 197 198**System capability**: SystemCapability.Communication.NetManager.Ethernet 199 200**Parameters** 201 202| Name | Type | Mandatory| Description | 203| -------- | --------------------------------------- | ---- | ------------ | 204| iface | string | Yes | Interface name.| 205 206**Return value** 207 208| Type | Description | 209| --------------------------------- | ---------------------------------- | 210| Promise\<[InterfaceConfiguration](#interfaceconfiguration9)> | Promise used to return the result. | 211 212**Error codes** 213 214| ID| Error Message | 215| ------- | ----------------------------------------| 216| 201 | Permission denied. | 217| 202 | Non-system applications use system APIs. | 218| 401 | Parameter error. | 219| 2200001 | Invalid parameter value. | 220| 2200002 | Operation failed. Cannot connect to service.| 221| 2200003 | System internal error. | 222| 2201005 | Device information does not exist. | 223 224**Example** 225 226```ts 227import ethernet from '@ohos.net.ethernet' 228import { BusinessError } from '@ohos.base' 229 230ethernet.getIfaceConfig("eth0").then((data: ethernet.InterfaceConfiguration) => { 231 console.log("getIfaceConfig promise mode = " + JSON.stringify(data.mode)); 232 console.log("getIfaceConfig promise ipAddr = " + JSON.stringify(data.ipAddr)); 233 console.log("getIfaceConfig promise route = " + JSON.stringify(data.route)); 234 console.log("getIfaceConfig promise gateway = " + JSON.stringify(data.gateway)); 235 console.log("getIfaceConfig promise netMask = " + JSON.stringify(data.netMask)); 236 console.log("getIfaceConfig promise dnsServers = " + JSON.stringify(data.dnsServers)); 237}).catch((error: BusinessError) => { 238 console.log("getIfaceConfig promise error = " + JSON.stringify(error)); 239}); 240``` 241 242## ethernet.isIfaceActive<sup>9+</sup> 243 244isIfaceActive(iface: string, callback: AsyncCallback\<number>): void 245 246Checks whether a network interface is active. This API uses an asynchronous callback to return the result. 247 248**System API**: This is a system API. 249 250**Required permission**: ohos.permission.GET_NETWORK_INFO 251 252**System capability**: SystemCapability.Communication.NetManager.Ethernet 253 254**Parameters** 255 256| Name | Type | Mandatory| Description | 257| -------- | --------------------------- | ---- | -------------------------------------------------- | 258| iface | string | Yes | Interface name. If this parameter is left empty, the API checks for any active network interface. | 259| 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.| 260 261**Error codes** 262 263| ID| Error Message | 264| ------- | ----------------------------------------| 265| 201 | Permission denied. | 266| 202 | Non-system applications use system APIs. | 267| 401 | Parameter error. | 268| 2200001 | Invalid parameter value. | 269| 2200002 | Operation failed. Cannot connect to service.| 270| 2200003 | System internal error. | 271| 2201005 | Device information does not exist. | 272 273**Example** 274 275```ts 276import ethernet from '@ohos.net.ethernet' 277import { BusinessError } from '@ohos.base' 278 279ethernet.isIfaceActive("eth0", (error: BusinessError, value: number) => { 280 if (error) { 281 console.log("whether2Activate callback error = " + JSON.stringify(error)); 282 } else { 283 console.log("whether2Activate callback = " + JSON.stringify(value)); 284 } 285}); 286``` 287 288## ethernet.isIfaceActive<sup>9+</sup> 289 290isIfaceActive(iface: string): Promise\<number> 291 292Checks whether a network interface is active. This API uses a promise to return the result. 293 294**System API**: This is a system API. 295 296**Required permission**: ohos.permission.GET_NETWORK_INFO 297 298**System capability**: SystemCapability.Communication.NetManager.Ethernet 299 300**Parameters** 301 302| Name| Type | Mandatory| Description | 303| ------ | ------ | ---- | -------------------------------------- | 304| iface | string | Yes | Interface name. If this parameter is left empty, the API checks for any active network interface.| 305 306**Return value** 307 308| Type | Description | 309| ----------------| ------------------------------------------------------------------ | 310| 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.| 311 312**Error codes** 313 314| ID| Error Message | 315| ------- | ----------------------------------------| 316| 201 | Permission denied. | 317| 202 | Non-system applications use system APIs. | 318| 401 | Parameter error. | 319| 2200001 | Invalid parameter value. | 320| 2200002 | Operation failed. Cannot connect to service.| 321| 2200003 | System internal error. | 322| 2201005 | Device information does not exist. | 323 324**Example** 325 326```ts 327import ethernet from '@ohos.net.ethernet' 328import { BusinessError } from '@ohos.base' 329 330ethernet.isIfaceActive("eth0").then((data: number) => { 331 console.log("isIfaceActive promise = " + JSON.stringify(data)); 332}).catch((error: BusinessError) => { 333 console.log("isIfaceActive promise error = " + JSON.stringify(error)); 334}); 335``` 336 337## ethernet.getAllActiveIfaces<sup>9+</sup> 338 339getAllActiveIfaces(callback: AsyncCallback\<Array\<string>>): void 340 341Obtains the list of all active network interfaces. This API uses an asynchronous callback to return the result. 342 343**System API**: This is a system API. 344 345**Required permission**: ohos.permission.GET_NETWORK_INFO 346 347**System capability**: SystemCapability.Communication.NetManager.Ethernet 348 349**Parameters** 350 351| Name | Type | Mandatory| Description | 352| -------- | ------------------------------------ | ---- | ------------------------------ | 353| callback | AsyncCallback\<Array\<string>> | Yes | Callback used to return the result.| 354 355**Error codes** 356 357| ID| Error Message | 358| ------- | ----------------------------------------| 359| 201 | Permission denied. | 360| 202 | Non-system applications use system APIs. | 361| 2200002 | Operation failed. Cannot connect to service.| 362| 2200003 | System internal error. | 363 364**Example** 365 366```ts 367import ethernet from '@ohos.net.ethernet' 368import { BusinessError } from '@ohos.base' 369 370ethernet.getAllActiveIfaces((error: BusinessError, value: string[]) => { 371 if (error) { 372 console.log("getAllActiveIfaces callback error = " + JSON.stringify(error)); 373 } else { 374 console.log("getAllActiveIfaces callback value.length = " + JSON.stringify(value.length)); 375 for (let i = 0; i < value.length; i++) { 376 console.log("getAllActiveIfaces callback = " + JSON.stringify(value[i])); 377 } 378 } 379}); 380``` 381 382## ethernet.getAllActiveIfaces<sup>9+</sup> 383 384getAllActiveIfaces(): Promise\<Array\<string>> 385 386Obtains the list of all active network interfaces. This API uses a promise to return the result. 387 388**System API**: This is a system API. 389 390**Required permission**: ohos.permission.GET_NETWORK_INFO 391 392**System capability**: SystemCapability.Communication.NetManager.Ethernet 393 394**Return value** 395 396| Type | Description | 397| ------------------------------ | ----------------------------------------------- | 398| Promise\<Array\<string>> | Promise used to return the result. | 399 400**Error codes** 401 402| ID| Error Message | 403| ------- | ----------------------------------------| 404| 201 | Permission denied. | 405| 202 | Non-system applications use system APIs. | 406| 2200002 | Operation failed. Cannot connect to service.| 407| 2200003 | System internal error. | 408 409**Example** 410 411```ts 412import ethernet from '@ohos.net.ethernet' 413import { BusinessError } from '@ohos.base' 414 415ethernet.getAllActiveIfaces().then((data: string[]) => { 416 console.log("getAllActiveIfaces promise data.length = " + JSON.stringify(data.length)); 417 for (let i = 0; i < data.length; i++) { 418 console.log("getAllActiveIfaces promise = " + JSON.stringify(data[i])); 419 } 420}).catch((error:BusinessError) => { 421 console.log("getAllActiveIfaces promise error = " + JSON.stringify(error)); 422}); 423``` 424 425## ethernet.on('interfaceStateChange')<sup>10+</sup> 426 427on(type: 'interfaceStateChange', callback: Callback\<InterfaceStateInfo>): void 428 429Registers an observer for NIC hot swap events. This API uses an asynchronous callback to return the result. 430 431**System API**: This is a system API. 432 433**Required permission**: ohos.permission.GET_NETWORK_INFO 434 435**System capability**: SystemCapability.Communication.NetManager.Ethernet 436 437**Parameters** 438 439| Name | Type | Mandatory| Description | 440| -------- | --------------------------------------- | ---- | ---------- | 441| type | string | Yes | Event type. The value is **interfaceStateChange**.| 442| callback | AsyncCallback\<[InterfaceStateInfo](#interfacestateinfo11)> | Yes | Callback used to return the result. | 443 444**Error codes** 445 446| ID| Error Message | 447| ------- | -------------------------------------------- | 448| 201 | Permission denied. | 449| 202 | Non-system applications use system APIs. | 450| 401 | Parameter error. | 451 452**Example** 453 454```ts 455import ethernet from '@ohos.net.ethernet' 456 457ethernet.on('interfaceStateChange', (data: object) => { 458 console.log('on interfaceSharingStateChange: ' + JSON.stringify(data)); 459}); 460``` 461 462## ethernet.off('interfaceStateChange')<sup>10+</sup> 463 464off(type: 'interfaceStateChange', callback?: Callback\<InterfaceStateInfo\>): void 465 466Unregisters the observer for NIC hot swap events. This API uses an asynchronous callback to return the result. 467 468**System API**: This is a system API. 469 470**Required permission**: ohos.permission.GET_NETWORK_INFO 471 472**System capability**: SystemCapability.Communication.NetManager.Ethernet 473 474**Parameters** 475 476| Name | Type | Mandatory| Description | 477| -------- | --------------------------------------- | ---- | ---------- | 478| type | string | Yes | Event type. The value is **interfaceStateChange**.| 479| callback | AsyncCallback\<[InterfaceStateInfo](#interfacestateinfo11)> | No | Callback used to return the result. | 480 481**Error codes** 482 483| ID| Error Message | 484| ------- | -------------------------------------------- | 485| 201 | Permission denied. | 486| 202 | Non-system applications use system APIs. | 487| 401 | Parameter error. | 488 489**Example** 490 491```ts 492import ethernet from '@ohos.net.ethernet' 493 494ethernet.off('interfaceStateChange'); 495``` 496 497## InterfaceConfiguration<sup>9+</sup> 498 499Defines the network configuration for the Ethernet connection. 500 501**System API**: This is a system API. 502 503**System capability**: SystemCapability.Communication.NetManager.Ethernet 504 505| Name | Type | Mandatory| Description | 506| ------------ | ----------------------- | ---|------------------------------------------------------------ | 507| mode | [IPSetMode](#ipsetmode9)| Yes| Configuration mode of the Ethernet connection.| 508| 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.| 509| 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.| 510| 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.| 511| 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.| 512| dnsServers | string | Yes| DNS server addresses 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. Multiple addresses are separated by commas (,).| 513| httpProxy<sup>10+</sup> | [HttpProxy](js-apis-net-connection.md#httpproxy10) | No| HTTP proxy of the Ethernet connection. By default, no proxy is configured.| 514 515## InterfaceStateInfo<sup>11+</sup> 516 517Listens for status changes of an Ethernet NIC. 518 519**System API**: This is a system API. 520 521**System capability**: SystemCapability.Communication.NetManager.Ethernet 522 523| Name | Type | Mandatory| Description | 524| ------------ | ----------------------- | --- | ---------------------------------------------------- | 525| iface | string | Yes| Name of the Ethernet NIC. | 526| active | boolean | Yes| Whether the Ethernet NIC is activated. The value **true** indicates the NIC is activated, and the value **false** indicates the opposite.| 527 528## IPSetMode<sup>9+</sup> 529 530Defines the configuration mode of the Ethernet connection. 531 532**System API**: This is a system API. 533 534**System capability**: SystemCapability.Communication.NetManager.Ethernet 535 536| Name | Value | Description | 537| --------------------- | ---- | -------------------------- | 538| STATIC | 0 | Static network configuration for an Ethernet connection.| 539| DHCP | 1 | Dynamic network configuration for an Ethernet connection.| 540| LAN_STATIC<sup>11+</sup>| 2 | Static network configuration for a LAN connection. | 541| LAN_DHCP<sup>11+</sup> | 3 | Dynamic network configuration for a LAN connection. | 542