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](#interfaceconfiguration)> | 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](#interfaceconfiguration)> | 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\<{ iface: string, active: boolean }\>): 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\<{ iface: string, active: boolean }\> | Yes | Callback used to return the result.<br>**iface**: NIC name.<br>**active**: whether the NIC is active. The value **true** indicates that the NIC is active, and the value **false** indicates the opposite.| 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\<{ iface: string, active: boolean }\>): 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\<{ iface: string, active: boolean }> | No | Callback used to return the result.<br>**iface**: NIC name.<br>**active**: whether the NIC is active. The value **true** indicates that the NIC is active, and the value **false** indicates the opposite.| 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](#ipsetmode) | 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. 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## IPSetMode<sup>9+</sup> 516 517Defines the configuration mode of the Ethernet connection. 518 519**System API**: This is a system API. 520 521**System capability**: SystemCapability.Communication.NetManager.Ethernet 522 523| Name | Value | Description | 524| ------------------------ | ---- | ---------------------- | 525| STATIC | 0 | Static configuration.| 526| DHCP | 1 | Dynamic configuration.| 527