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