1/* 2 * Copyright (C) 2022-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit NetworkKit 19 */ 20 21import type { AsyncCallback, Callback } from './@ohos.base'; 22import type connection from './@ohos.net.connection'; 23 24/** 25 * Provides interfaces to manage ethernet. 26 * @namespace ethernet 27 * @syscap SystemCapability.Communication.NetManager.Ethernet 28 * @since 9 29 */ 30declare namespace ethernet { 31 /** 32 * @typedef { connection.HttpProxy } 33 * @syscap SystemCapability.Communication.NetManager.Ethernet 34 * @since 10 35 */ 36 type HttpProxy = connection.HttpProxy; 37 38 /** 39 * Get the specified network interface information. 40 * @permission ohos.permission.GET_NETWORK_INFO 41 * @param { string } iface - Indicates the network interface name. 42 * @param { AsyncCallback<InterfaceConfiguration> } callback - the callback of getIfaceConfig. 43 * @throws { BusinessError } 201 - Permission denied. 44 * @throws { BusinessError } 202 - Non-system applications use system APIs. 45 * @throws { BusinessError } 401 - Parameter error. 46 * @throws { BusinessError } 2200001 - Invalid parameter value. 47 * @throws { BusinessError } 2200002 - Failed to connect to the service. 48 * @throws { BusinessError } 2200003 - System internal error. 49 * @throws { BusinessError } 2201005 - Device information does not exist. 50 * @syscap SystemCapability.Communication.NetManager.Ethernet 51 * @systemapi Hide this for inner system use. 52 * @since 9 53 */ 54 function getIfaceConfig(iface: string, callback: AsyncCallback<InterfaceConfiguration>): void; 55 56 /** 57 * Get the specified network interface information. 58 * @permission ohos.permission.GET_NETWORK_INFO 59 * @param { string } iface - Indicates the network interface name. 60 * @returns { Promise<InterfaceConfiguration> } the promise returned by the function. 61 * @throws { BusinessError } 201 - Permission denied. 62 * @throws { BusinessError } 202 - Non-system applications use system APIs. 63 * @throws { BusinessError } 401 - Parameter error. 64 * @throws { BusinessError } 2200001 - Invalid parameter value. 65 * @throws { BusinessError } 2200002 - Failed to connect to the service. 66 * @throws { BusinessError } 2200003 - System internal error. 67 * @throws { BusinessError } 2201005 - Device information does not exist. 68 * @syscap SystemCapability.Communication.NetManager.Ethernet 69 * @systemapi Hide this for inner system use. 70 * @since 9 71 */ 72 function getIfaceConfig(iface: string): Promise<InterfaceConfiguration>; 73 74 /** 75 * Set the specified network interface parameters. 76 * @permission ohos.permission.CONNECTIVITY_INTERNAL 77 * @param { string } iface - Indicates the network interface name of the network parameter. 78 * @param { InterfaceConfiguration } ic - Indicates the ic. See {@link InterfaceConfiguration}. 79 * @param { AsyncCallback<void> } callback - the callback of setIfaceConfig. 80 * @throws { BusinessError } 201 - Permission denied. 81 * @throws { BusinessError } 202 - Non-system applications use system APIs. 82 * @throws { BusinessError } 401 - Parameter error. 83 * @throws { BusinessError } 2100001 - Invalid parameter value. 84 * @throws { BusinessError } 2200002 - Failed to connect to the service. 85 * @throws { BusinessError } 2200003 - System internal error. 86 * @throws { BusinessError } 2201004 - Invalid Ethernet profile. 87 * @throws { BusinessError } 2201005 - Device information does not exist. 88 * @throws { BusinessError } 2201006 - Ethernet device not connected. 89 * @throws { BusinessError } 2201007 - Ethernet failed to write user configuration information. 90 * @syscap SystemCapability.Communication.NetManager.Ethernet 91 * @systemapi Hide this for inner system use. 92 * @since 9 93 */ 94 function setIfaceConfig(iface: string, ic: InterfaceConfiguration, callback: AsyncCallback<void>): void; 95 96 /** 97 * Set the specified network interface parameters. 98 * @permission ohos.permission.CONNECTIVITY_INTERNAL 99 * @param { string } iface - Indicates the network interface name of the network parameter. 100 * @param { InterfaceConfiguration } ic - Indicates the ic. See {@link InterfaceConfiguration}. 101 * @returns { Promise<void> } the promise returned by the function. 102 * @throws { BusinessError } 201 - Permission denied. 103 * @throws { BusinessError } 202 - Non-system applications use system APIs. 104 * @throws { BusinessError } 401 - Parameter error. 105 * @throws { BusinessError } 2100001 - Invalid parameter value. 106 * @throws { BusinessError } 2200002 - Failed to connect to the service. 107 * @throws { BusinessError } 2200003 - System internal error. 108 * @throws { BusinessError } 2201004 - Invalid Ethernet profile. 109 * @throws { BusinessError } 2201005 - Device information does not exist. 110 * @throws { BusinessError } 2201006 - Ethernet device not connected. 111 * @throws { BusinessError } 2201007 - Ethernet failed to write user configuration information. 112 * @syscap SystemCapability.Communication.NetManager.Ethernet 113 * @systemapi Hide this for inner system use. 114 * @since 9 115 */ 116 function setIfaceConfig(iface: string, ic: InterfaceConfiguration): Promise<void>; 117 118 /** 119 * Check whether the specified network is active. 120 * @permission ohos.permission.GET_NETWORK_INFO 121 * @param { string } iface - Indicates the network interface name. 122 * @param { AsyncCallback<number> } callback - the callback of isIfaceActive. 123 * @throws { BusinessError } 201 - Permission denied. 124 * @throws { BusinessError } 202 - Non-system applications use system APIs. 125 * @throws { BusinessError } 401 - Parameter error. 126 * @throws { BusinessError } 2200001 - Invalid parameter value. 127 * @throws { BusinessError } 2200002 - Failed to connect to the service. 128 * @throws { BusinessError } 2200003 - System internal error. 129 * @throws { BusinessError } 2201005 - Device information does not exist. 130 * @syscap SystemCapability.Communication.NetManager.Ethernet 131 * @systemapi Hide this for inner system use. 132 * @since 9 133 */ 134 function isIfaceActive(iface: string, callback: AsyncCallback<number>): void; 135 136 /** 137 * Check whether the specified network is active. 138 * @permission ohos.permission.GET_NETWORK_INFO 139 * @param { string } iface - Indicates the network interface name. 140 * @returns { Promise<number> } the promise returned by the function. 141 * @throws { BusinessError } 201 - Permission denied. 142 * @throws { BusinessError } 202 - Non-system applications use system APIs. 143 * @throws { BusinessError } 401 - Parameter error. 144 * @throws { BusinessError } 2200001 - Invalid parameter value. 145 * @throws { BusinessError } 2200002 - Failed to connect to the service. 146 * @throws { BusinessError } 2200003 - System internal error. 147 * @throws { BusinessError } 2201005 - Device information does not exist. 148 * @syscap SystemCapability.Communication.NetManager.Ethernet 149 * @systemapi Hide this for inner system use. 150 * @since 9 151 */ 152 function isIfaceActive(iface: string): Promise<number>; 153 154 /** 155 * Gets the names of all active network interfaces. 156 * @permission ohos.permission.GET_NETWORK_INFO 157 * @param { AsyncCallback<Array<string>> } callback - the callback of getAllActiveIfaces. 158 * @throws { BusinessError } 201 - Permission denied. 159 * @throws { BusinessError } 202 - Non-system applications use system APIs. 160 * @throws { BusinessError } 2200002 - Failed to connect to the service. 161 * @throws { BusinessError } 2200003 - System internal error. 162 * @syscap SystemCapability.Communication.NetManager.Ethernet 163 * @systemapi Hide this for inner system use. 164 * @since 9 165 */ 166 function getAllActiveIfaces(callback: AsyncCallback<Array<string>>): void; 167 168 /** 169 * Gets the names of all active network interfaces. 170 * @permission ohos.permission.GET_NETWORK_INFO 171 * @returns { Promise<Array<string>> } the promise returned by the function. 172 * @throws { BusinessError } 201 - Permission denied. 173 * @throws { BusinessError } 202 - Non-system applications use system APIs. 174 * @throws { BusinessError } 2200002 - Failed to connect to the service. 175 * @throws { BusinessError } 2200003 - System internal error. 176 * @syscap SystemCapability.Communication.NetManager.Ethernet 177 * @systemapi Hide this for inner system use. 178 * @since 9 179 */ 180 function getAllActiveIfaces(): Promise<Array<string>>; 181 182 /** 183 * Register a callback for the ethernet interface active state change. 184 * @permission ohos.permission.GET_NETWORK_INFO 185 * @param { 'interfaceStateChange' } type - Indicates Event name. 186 * @param { Callback<{ iface: string, active: boolean }> } callback - Including iface Indicates the ethernet interface, 187 * and active Indicates whether the interface is active. 188 * @throws { BusinessError } 201 - Permission denied. 189 * @throws { BusinessError } 202 - Non-system applications use system APIs. 190 * @throws { BusinessError } 401 - Parameter error. 191 * @syscap SystemCapability.Communication.NetManager.Ethernet 192 * @systemapi Hide this for inner system use. 193 * @since 10 194 */ 195 /** 196 * Register a callback for the ethernet interface active state change. 197 * @permission ohos.permission.GET_NETWORK_INFO 198 * @param { 'interfaceStateChange' } type - Indicates Event name. 199 * @param { Callback<InterfaceStateInfo> } callback - Including iface Indicates the ethernet interface, 200 * and active Indicates whether the interface is active. 201 * @throws { BusinessError } 201 - Permission denied. 202 * @throws { BusinessError } 202 - Non-system applications use system APIs. 203 * @throws { BusinessError } 401 - Parameter error. 204 * @syscap SystemCapability.Communication.NetManager.Ethernet 205 * @systemapi Hide this for inner system use. 206 * @since 11 207 */ 208 function on(type: 'interfaceStateChange', callback: Callback<InterfaceStateInfo>): void; 209 210 /** 211 * Unregister a callback from the ethernet interface active state change. 212 * @permission ohos.permission.GET_NETWORK_INFO 213 * @param { 'interfaceStateChange' } type - Indicates Event name. 214 * @param { Callback<{ iface: string, active: boolean }> } callback - Including iface Indicates the ethernet interface, 215 * and active Indicates whether the interface is active. 216 * @throws { BusinessError } 201 - Permission denied. 217 * @throws { BusinessError } 202 - Non-system applications use system APIs. 218 * @throws { BusinessError } 401 - Parameter error. 219 * @syscap SystemCapability.Communication.NetManager.Ethernet 220 * @systemapi Hide this for inner system use. 221 * @since 10 222 */ 223 /** 224 * Unregister a callback from the ethernet interface active state change. 225 * @permission ohos.permission.GET_NETWORK_INFO 226 * @param { 'interfaceStateChange' } type - Indicates Event name. 227 * @param { Callback<InterfaceStateInfo> } callback - Including iface Indicates the ethernet interface, 228 * and active Indicates whether the interface is active. 229 * @throws { BusinessError } 201 - Permission denied. 230 * @throws { BusinessError } 202 - Non-system applications use system APIs. 231 * @throws { BusinessError } 401 - Parameter error. 232 * @syscap SystemCapability.Communication.NetManager.Ethernet 233 * @systemapi Hide this for inner system use. 234 * @since 11 235 */ 236 function off(type: 'interfaceStateChange', callback?: Callback<InterfaceStateInfo>): void; 237 238 /** 239 * Get the ethernet mac address list. 240 * @permission ohos.permission.GET_ETHERNET_LOCAL_MAC 241 * @returns { Promise<Array<MacAddressInfo>> } the promise returned by the function. 242 * @throws { BusinessError } 201 - Permission denied. 243 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 244 * @throws { BusinessError } 2201005 - Device information does not exist. 245 * @syscap SystemCapability.Communication.NetManager.Ethernet 246 * @since 14 247 */ 248 function getMacAddress(): Promise<Array<MacAddressInfo>>; 249 250 /** 251 * Get the ethernet mac address list. 252 * @permission ohos.permission.GET_NETWORK_INFO 253 * @returns { Promise<Array<EthernetDeviceInfos>> } the promise returned by the function. 254 * @throws { BusinessError } 201 - Permission denied. 255 * @throws { BusinessError } 202 - Non-system applications use system APIs. 256 * @throws { BusinessError } 2201005 - Device information does not exist. 257 * @syscap SystemCapability.Communication.NetManager.Ethernet 258 * @systemapi Hide this for inner system use. 259 * @since 20 260 */ 261 function getEthernetDeviceInfos(): Promise<Array<EthernetDeviceInfos>>; 262 263 /** 264 * Defines the network configuration for the Ethernet connection. 265 * @interface InterfaceConfiguration 266 * @syscap SystemCapability.Communication.NetManager.Ethernet 267 * @systemapi Hide this for inner system use. 268 * @since 9 269 */ 270 export interface InterfaceConfiguration { 271 /** 272 * @type {IPSetMode} 273 * See {@link IPSetMode} 274 * @syscap SystemCapability.Communication.NetManager.Ethernet 275 * @systemapi Hide this for inner system use. 276 * @since 9 277 */ 278 mode: IPSetMode; 279 /** 280 * Ethernet connection static configuration IP information. 281 * The address value range is 0-255.0-255.0-255.0-255.0-255 282 * (DHCP mode does not need to be configured) 283 * @type {string} 284 * @syscap SystemCapability.Communication.NetManager.Ethernet 285 * @systemapi Hide this for inner system use. 286 * @since 9 287 */ 288 ipAddr: string; 289 290 /** 291 * Ethernet connection static configuration route information. 292 * The address value range is 0-255.0-255.0-255.0-255.0-255 293 * (DHCP mode does not need to be configured) 294 * @type {string} 295 * @syscap SystemCapability.Communication.NetManager.Ethernet 296 * @systemapi Hide this for inner system use. 297 * @since 9 298 */ 299 route: string; 300 301 /** 302 * Ethernet connection static configuration gateway information. 303 * The address value range is 0-255.0-255.0-255.0-255.0-255 304 * (DHCP mode does not need to be configured) 305 * @type {string} 306 * @syscap SystemCapability.Communication.NetManager.Ethernet 307 * @systemapi Hide this for inner system use. 308 * @since 9 309 */ 310 gateway: string; 311 312 /** 313 * Ethernet connection static configuration netMask information. 314 * The address value range is 0-255.0-255.0-255.0-255.0-255 315 * (DHCP mode does not need to be configured) 316 * @type {string} 317 * @syscap SystemCapability.Communication.NetManager.Ethernet 318 * @systemapi Hide this for inner system use. 319 * @since 9 320 */ 321 netMask: string; 322 323 /** 324 * The Ethernet connection is configured with the dns service address. 325 * The address value range is 0-255.0-255.0-255.0-255.0-255 326 * (DHCP mode does not need to be configured, Multiple addresses are separated by ",") 327 * @type {string} 328 * @syscap SystemCapability.Communication.NetManager.Ethernet 329 * @systemapi Hide this for inner system use. 330 * @since 9 331 */ 332 dnsServers: string; 333 334 /** 335 * Indicates the HttpProxy settings, no proxy is to be used as default. 336 * @type {?HttpProxy} 337 * @syscap SystemCapability.Communication.NetManager.Ethernet 338 * @systemapi Hide this for inner system use. 339 * @since 10 340 */ 341 httpProxy?: HttpProxy; 342 } 343 344 /** 345 * The interface is used to monitor network interface status changes. 346 * @interface InterfaceStateInfo 347 * @syscap SystemCapability.Communication.NetManager.Ethernet 348 * @systemapi Hide this for inner system use. 349 * @since 11 350 */ 351 export interface InterfaceStateInfo { 352 /** 353 * Define network card name. 354 * @type { string } 355 * @syscap SystemCapability.Communication.NetManager.Ethernet 356 * @systemapi Hide this for inner system use. 357 * @since 11 358 */ 359 iface: string; 360 /** 361 * Check if it is active. 362 * @type { boolean } 363 * @syscap SystemCapability.Communication.NetManager.Ethernet 364 * @systemapi Hide this for inner system use. 365 * @since 11 366 */ 367 active: boolean; 368 } 369 370 /** 371 * Defines the configuration mode of the Ethernet connection. 372 * @enum {number} 373 * @syscap SystemCapability.Communication.NetManager.Ethernet 374 * @systemapi Hide this for inner system use. 375 * @since 9 376 */ 377 export enum IPSetMode { 378 /** 379 * WAN Static configuration. 380 * @syscap SystemCapability.Communication.NetManager.Ethernet 381 * @systemapi Hide this for inner system use. 382 * @since 9 383 */ 384 STATIC = 0, 385 386 /** 387 * WAN Dynamic configuration. 388 * @syscap SystemCapability.Communication.NetManager.Ethernet 389 * @systemapi Hide this for inner system use. 390 * @since 9 391 */ 392 DHCP = 1, 393 394 /** 395 * LAN Static configuration. 396 * @syscap SystemCapability.Communication.NetManager.Ethernet 397 * @systemapi Hide this for inner system use. 398 * @since 11 399 */ 400 LAN_STATIC = 2, 401 402 /** 403 * LAN Dynamic configuration. 404 * @syscap SystemCapability.Communication.NetManager.Ethernet 405 * @systemapi Hide this for inner system use. 406 * @since 11 407 */ 408 LAN_DHCP = 3 409 } 410 411 /** 412 * Defines the mac address info of the Ethernet. 413 * @interface MacAddressInfo 414 * @syscap SystemCapability.Communication.NetManager.Ethernet 415 * @since 14 416 */ 417 export interface MacAddressInfo { 418 /** 419 * Ethernet interface name. 420 * @type { string } 421 * @syscap SystemCapability.Communication.NetManager.Ethernet 422 * @since 14 423 */ 424 iface: string; 425 426 /** 427 * Ethernet specific mac address. 428 * @type { string } 429 * @syscap SystemCapability.Communication.NetManager.Ethernet 430 * @since 14 431 */ 432 macAddress: string; 433 } 434 435 /** 436 * Defines the device information of the Ethernet. 437 * @interface EthernetDeviceInfos 438 * @syscap SystemCapability.Communication.NetManager.Ethernet 439 * @systemapi Hide this for inner system use. 440 * @since 20 441 */ 442 export interface EthernetDeviceInfos { 443 /** 444 * Ethernet interface name. 445 * @type { string } 446 * @syscap SystemCapability.Communication.NetManager.Ethernet 447 * @systemapi Hide this for inner system use. 448 * @since 20 449 */ 450 ifaceName: string; 451 452 /** 453 * Ethernet device name. 454 * @type { string } 455 * @syscap SystemCapability.Communication.NetManager.Ethernet 456 * @systemapi Hide this for inner system use. 457 * @since 20 458 */ 459 deviceName: string; 460 461 /** 462 * Device connection mode. 463 * @type { DeviceConnectionType } 464 * @syscap SystemCapability.Communication.NetManager.Ethernet 465 * @systemapi Hide this for inner system use. 466 * @since 20 467 */ 468 connectionMode: DeviceConnectionType; 469 470 /** 471 * Supplier name of device. 472 * @type { string } 473 * @syscap SystemCapability.Communication.NetManager.Ethernet 474 * @systemapi Hide this for inner system use. 475 * @since 20 476 */ 477 supplierName: string; 478 479 /** 480 * Supplier id of device. 481 * @type { string } 482 * @syscap SystemCapability.Communication.NetManager.Ethernet 483 * @systemapi Hide this for inner system use. 484 * @since 20 485 */ 486 supplierId: string; 487 488 /** 489 * Product name of device. 490 * @type { string } 491 * @syscap SystemCapability.Communication.NetManager.Ethernet 492 * @systemapi Hide this for inner system use. 493 * @since 20 494 */ 495 productName: string; 496 497 /** 498 * Maximum Rate of device. 499 * @type { string } 500 * @syscap SystemCapability.Communication.NetManager.Ethernet 501 * @systemapi Hide this for inner system use. 502 * @since 20 503 */ 504 maximumRate: string; 505 } 506 507 /** 508 * Defines the Device Connection Mode of the Ethernet. 509 * @enum {number} 510 * @syscap SystemCapability.Communication.NetManager.Ethernet 511 * @systemapi Hide this for inner system use. 512 * @since 20 513 */ 514 export enum DeviceConnectionType { 515 /** 516 * Ethernet in built-in mode. 517 * @syscap SystemCapability.Communication.NetManager.Ethernet 518 * @systemapi Hide this for inner system use. 519 * @since 20 520 */ 521 BUILT_IN = 0, 522 523 /** 524 * Ethernet in external mode. For example, an ethernet connection via USB. 525 * @syscap SystemCapability.Communication.NetManager.Ethernet 526 * @systemapi Hide this for inner system use. 527 * @since 20 528 */ 529 EXTERNAL = 1 530 } 531} 532 533export default ethernet;