1# @ohos.net.ethernet (以太网连接管理)（系统接口） 2 3以太网连接管理主要提供有线网络能力，提供设置有线网络的IP地址，子网掩码，网关，DNS，代理等信息 4 5> **说明：** 6> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7> 本模块为系统接口。 8 9## 导入模块 10 11```ts 12import ethernet from '@ohos.net.ethernet' 13``` 14 15## ethernet.setIfaceConfig<sup>9+</sup> 16 17setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallback\<void>): void 18 19设置网络接口配置信息，使用callback方式作为异步方法。 20 21**系统接口**：此接口为系统接口。 22 23**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL 24 25**系统能力**：SystemCapability.Communication.NetManager.Ethernet 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| -------- | ------------------------------------------------- | ---- | ------------------------------------------ | 31| iface | string | 是 | 网络接口名 | 32| ic | [InterfaceConfiguration](#interfaceconfiguration9) | 是 | 要设置的网络接口配置信息 | 33| callback | AsyncCallback\<void> | 是 | 回调函数，成功无返回，失败返回对应错误码。 | 34 35**错误码：** 36 37| 错误码ID | 错误信息 | 38| ------- | ----------------------------------------| 39| 201 | Permission denied. | 40| 202 | Non-system applications use system APIs. | 41| 401 | Parameter error. | 42| 2200001 | Invalid parameter value. | 43| 2200002 | Operation failed. Cannot connect to 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**示例：** 51 52```ts 53import ethernet from '@ohos.net.ethernet' 54import { BusinessError } from '@ohos.base' 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 78设置网络接口配置信息，使用Promise方式作为异步方法。 79 80**系统接口**：此接口为系统接口。 81 82**需要权限**：ohos.permission.CONNECTIVITY_INTERNAL 83 84**系统能力**：SystemCapability.Communication.NetManager.Ethernet 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ------ | ------------------------------------------------- | ---- | ------------------------ | 90| iface | string | 是 | 接口名 | 91| ic | [InterfaceConfiguration](#interfaceconfiguration9) | 是 | 要设置的网络接口配置信息 | 92 93**返回值：** 94 95| 类型 | 说明 | 96| ------------------- | ----------------------------------------------------------- | 97| Promise\<void> | 以Promise形式返回执行结果。成功无返回，失败返回对应错误码。 | 98 99**错误码：** 100 101| 错误码ID | 错误信息 | 102| ------- | ----------------------------------------| 103| 201 | Permission denied. | 104| 202 | Non-system applications use system APIs. | 105| 401 | Parameter error. | 106| 2200001 | Invalid parameter value. | 107| 2200002 | Operation failed. Cannot connect to 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**示例：** 115 116```ts 117import ethernet from '@ohos.net.ethernet' 118import { BusinessError } from '@ohos.base' 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 142获取指定网络接口信息，使用callback方式作为异步方法。 143 144**系统接口**：此接口为系统接口。 145 146**需要权限**：ohos.permission.GET_NETWORK_INFO 147 148**系统能力**：SystemCapability.Communication.NetManager.Ethernet 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| -------- | ----------------------------------------------- | ----- | ------------ | 154| iface | string | 是 | 指定网络接口 | 155| callback | AsyncCallback\<[InterfaceConfiguration](#interfaceconfiguration9)> | 是 | 回调函数，返回指定网络接口信息 | 156 157**错误码：** 158 159| 错误码ID | 错误信息 | 160| ------- | ----------------------------------------| 161| 201 | Permission denied. | 162| 202 | Non-system applications use system APIs. | 163| 401 | Parameter error. | 164| 2200001 | Invalid parameter value. | 165| 2200002 | Operation failed. Cannot connect to service.| 166| 2200003 | System internal error. | 167| 2201005 | Device information does not exist. | 168 169**示例：** 170 171```ts 172import ethernet from '@ohos.net.ethernet' 173import { BusinessError } from '@ohos.base' 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 193获取指定网络接口信息，使用Promise方式作为异步方法。 194 195**系统接口**：此接口为系统接口。 196 197**需要权限**：ohos.permission.GET_NETWORK_INFO 198 199**系统能力**：SystemCapability.Communication.NetManager.Ethernet 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| -------- | --------------------------------------- | ---- | ------------ | 205| iface | string | 是 | 指定网络接口 | 206 207**返回值：** 208 209| 类型 | 说明 | 210| --------------------------------- | ---------------------------------- | 211| Promise\<[InterfaceConfiguration](#interfaceconfiguration9)> | 以Promise形式返回接口信息。 | 212 213**错误码：** 214 215| 错误码ID | 错误信息 | 216| ------- | ----------------------------------------| 217| 201 | Permission denied. | 218| 202 | Non-system applications use system APIs. | 219| 401 | Parameter error. | 220| 2200001 | Invalid parameter value. | 221| 2200002 | Operation failed. Cannot connect to service.| 222| 2200003 | System internal error. | 223| 2201005 | Device information does not exist. | 224 225**示例：** 226 227```ts 228import ethernet from '@ohos.net.ethernet' 229import { BusinessError } from '@ohos.base' 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 247判断接口是否已激活，使用callback方式作为异步方法。 248 249**系统接口**：此接口为系统接口。 250 251**需要权限**：ohos.permission.GET_NETWORK_INFO 252 253**系统能力**：SystemCapability.Communication.NetManager.Ethernet 254 255**参数：** 256 257| 参数名 | 类型 | 必填 | 说明 | 258| -------- | --------------------------- | ---- | -------------------------------------------------- | 259| iface | string | 是 | 接口名。为空时代表查询是否存在激活接口 | 260| callback | AsyncCallback\<number> | 是 | 回调函数，已激活:1,未激活:0,其他为获取失败错误码。 | 261 262**错误码：** 263 264| 错误码ID | 错误信息 | 265| ------- | ----------------------------------------| 266| 201 | Permission denied. | 267| 202 | Non-system applications use system APIs. | 268| 401 | Parameter error. | 269| 2200001 | Invalid parameter value. | 270| 2200002 | Operation failed. Cannot connect to service.| 271| 2200003 | System internal error. | 272| 2201005 | Device information does not exist. | 273 274**示例：** 275 276```ts 277import ethernet from '@ohos.net.ethernet' 278import { BusinessError } from '@ohos.base' 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 293判断接口是否已激活，使用Promise方式作为异步方法。 294 295**系统接口**：此接口为系统接口。 296 297**需要权限**：ohos.permission.GET_NETWORK_INFO 298 299**系统能力**：SystemCapability.Communication.NetManager.Ethernet 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| ------ | ------ | ---- | -------------------------------------- | 305| iface | string | 是 | 接口名。为空时代表查询是否存在激活接口 | 306 307**返回值：** 308 309| 类型 | 说明 | 310| ----------------| ------------------------------------------------------------------ | 311| Promise\<number> | 以Promise形式返回获取结果。已激活:1,未激活:0,其他为获取失败错误码。| 312 313**错误码：** 314 315| 错误码ID | 错误信息 | 316| ------- | ----------------------------------------| 317| 201 | Permission denied. | 318| 202 | Non-system applications use system APIs. | 319| 401 | Parameter error. | 320| 2200001 | Invalid parameter value. | 321| 2200002 | Operation failed. Cannot connect to service.| 322| 2200003 | System internal error. | 323| 2201005 | Device information does not exist. | 324 325**示例：** 326 327```ts 328import ethernet from '@ohos.net.ethernet' 329import { BusinessError } from '@ohos.base' 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 342获取活动的网络接口，使用callback方式作为异步方法。 343 344**系统接口**：此接口为系统接口。 345 346**需要权限**：ohos.permission.GET_NETWORK_INFO 347 348**系统能力**：SystemCapability.Communication.NetManager.Ethernet 349 350**参数：** 351 352| 参数名 | 类型 | 必填 | 说明 | 353| -------- | ------------------------------------ | ---- | ------------------------------ | 354| callback | AsyncCallback\<Array\<string>> | 是 | 回调函数，返回值为对应接口名。 | 355 356**错误码：** 357 358| 错误码ID | 错误信息 | 359| ------- | ----------------------------------------| 360| 201 | Permission denied. | 361| 202 | Non-system applications use system APIs. | 362| 2200002 | Operation failed. Cannot connect to service.| 363| 2200003 | System internal error. | 364 365**示例：** 366 367```ts 368import ethernet from '@ohos.net.ethernet' 369import { BusinessError } from '@ohos.base' 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 387获取活动的网络接口，使用Promise方式作为异步方法。 388 389**系统接口**：此接口为系统接口。 390 391**需要权限**：ohos.permission.GET_NETWORK_INFO 392 393**系统能力**：SystemCapability.Communication.NetManager.Ethernet 394 395**返回值：** 396 397| 类型 | 说明 | 398| ------------------------------ | ----------------------------------------------- | 399| Promise\<Array\<string>> | 以Promise形式返回获取结果。返回值为对应接口名。 | 400 401**错误码：** 402 403| 错误码ID | 错误信息 | 404| ------- | ----------------------------------------| 405| 201 | Permission denied. | 406| 202 | Non-system applications use system APIs. | 407| 2200002 | Operation failed. Cannot connect to service.| 408| 2200003 | System internal error. | 409 410**示例：** 411 412```ts 413import ethernet from '@ohos.net.ethernet' 414import { BusinessError } from '@ohos.base' 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 430注册网卡热插拔事件，使用callback方式作为异步方法。 431 432**系统接口**：此接口为系统接口。 433 434**需要权限**：ohos.permission.GET_NETWORK_INFO 435 436**系统能力**：SystemCapability.Communication.NetManager.Ethernet 437 438**参数：** 439 440| 参数名 | 类型 | 必填 | 说明 | 441| -------- | --------------------------------------- | ---- | ---------- | 442| type | string | 是 | 订阅的事件类型，'interfaceStateChange'。 | 443| callback | AsyncCallback\<[InterfaceStateInfo](#interfacestateinfo11)> | 是 | 回调函数。返回以太网卡状态信息。 | 444 445**错误码：** 446 447| 错误码ID | 错误信息 | 448| ------- | -------------------------------------------- | 449| 201 | Permission denied. | 450| 202 | Non-system applications use system APIs. | 451| 401 | Parameter error. | 452 453**示例：** 454 455```ts 456import ethernet from '@ohos.net.ethernet' 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 467注销网卡热插拔事件，使用callback方式作为异步方法。 468 469**系统接口**：此接口为系统接口。 470 471**需要权限**：ohos.permission.GET_NETWORK_INFO 472 473**系统能力**：SystemCapability.Communication.NetManager.Ethernet 474 475**参数：** 476 477| 参数名 | 类型 | 必填 | 说明 | 478| -------- | --------------------------------------- | ---- | ---------- | 479| type | string | 是 | 订阅的事件类型，'interfaceStateChange'。 | 480| callback | AsyncCallback\<[InterfaceStateInfo](#interfacestateinfo11)> | 否 | 回调函数。返回以太网卡状态信息。 | 481 482**错误码：** 483 484| 错误码ID | 错误信息 | 485| ------- | -------------------------------------------- | 486| 201 | Permission denied. | 487| 202 | Non-system applications use system APIs. | 488| 401 | Parameter error. | 489 490**示例：** 491 492```ts 493import ethernet from '@ohos.net.ethernet' 494 495ethernet.off('interfaceStateChange'); 496``` 497 498## InterfaceConfiguration<sup>9+</sup> 499 500以太网连接配置网络信息。 501 502**系统接口**：此接口为系统接口。 503 504**系统能力**：SystemCapability.Communication.NetManager.Ethernet 505 506| 名称 | 类型 | 必填 | 说明 | 507| ------------ | ----------------------- | ---|------------------------------------------------------------ | 508| mode | [IPSetMode](#ipsetmode9) | 是 | 以太网连接配置模式。 | 509| ipAddr | string | 是 | 以太网连接静态配置ip信息，地址值范围0-255.0-255.0-255.0-255（DHCP模式无需配置）。 | 510| route | string | 是 | 以太网连接静态配置路由信息，地址值范围0-255.0-255.0-255.0-255（DHCP模式无需配置）。 | 511| gateway | string | 是 | 以太网连接配置网关信息，地址值范围0-255.0-255.0-255.0-255（DHCP模式无需配置）。 | 512| netMask | string | 是 | 以太网连接配置子网掩码，地址值范围0-255.0-255.0-255.0-255（DHCP模式无需配置）。 | 513| dnsServers | string | 是 | 以太网连接配置dns服务地址，地址值范围0-255.0-255.0-255.0-255（DHCP模式无需配置）多地址间用“,”隔开。 | 514| httpProxy<sup>10+</sup> | [HttpProxy](js-apis-net-connection.md#httpproxy10) | 否 | 以太网连接代理配置信息，默认情况下不配置任何代理信息。 | 515 516## InterfaceStateInfo<sup>11+</sup> 517 518监听以太网卡状态变化 519 520**系统接口**：此接口为系统接口。 521 522**系统能力**：SystemCapability.Communication.NetManager.Ethernet 523 524| 名称 | 类型 | 必填 | 说明 | 525| ------------ | ----------------------- | --- | ---------------------------------------------------- | 526| iface | string | 是 | 以太网卡名称。 | 527| active | boolean | 是 | 以太网卡是否处于激活状态（true：激活；false：未激活）。 | 528 529## IPSetMode<sup>9+</sup> 530 531以太网连接模式。 532 533**系统接口**：此接口为系统接口。 534 535**系统能力**：SystemCapability.Communication.NetManager.Ethernet 536 537| 名称 | 值 | 说明 | 538| --------------------- | ---- | -------------------------- | 539| STATIC | 0 | 以太网连接静态配置网络信息。 | 540| DHCP | 1 | 以太网连接动态配置网络信息。 | 541| LAN_STATIC<sup>11+</sup>| 2 | LAN连接静态配置网络信息。 | 542| LAN_DHCP<sup>11+</sup> | 3 | LAN连接动态配置网络信息。 | 543