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 } 2200001 - 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 } 2200001 - 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<string>> } the promise returned by the function. 242 * @throws { BusinessError } 201 - Permission denied. 243 * @throws { BusinessError } 202 - Non-system applications use system APIs. 244 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 245 * @throws { BusinessError } 2201005 - Device information does not exist. 246 * @syscap SystemCapability.Communication.NetManager.Ethernet 247 * @systemapi Hide this for inner system use. 248 * @since 13 249 */ 250 function getMacAddress(): Promise<Array<MacAddressInfo>>; 251 252 /** 253 * Defines the network configuration for the Ethernet connection. 254 * @interface InterfaceConfiguration 255 * @syscap SystemCapability.Communication.NetManager.Ethernet 256 * @systemapi Hide this for inner system use. 257 * @since 9 258 */ 259 export interface InterfaceConfiguration { 260 /** 261 * @type {IPSetMode} 262 * See {@link IPSetMode} 263 * @syscap SystemCapability.Communication.NetManager.Ethernet 264 * @systemapi Hide this for inner system use. 265 * @since 9 266 */ 267 mode: IPSetMode; 268 /** 269 * Ethernet connection static configuration IP information. 270 * The address value range is 0-255.0-255.0-255.0-255.0-255 271 * (DHCP mode does not need to be configured) 272 * @type {string} 273 * @syscap SystemCapability.Communication.NetManager.Ethernet 274 * @systemapi Hide this for inner system use. 275 * @since 9 276 */ 277 ipAddr: string; 278 279 /** 280 * Ethernet connection static configuration route 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 route: string; 289 290 /** 291 * Ethernet connection static configuration gateway 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 gateway: string; 300 301 /** 302 * Ethernet connection static configuration netMask 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 netMask: string; 311 312 /** 313 * The Ethernet connection is configured with the dns service address. 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, Multiple addresses are separated by ",") 316 * @type {string} 317 * @syscap SystemCapability.Communication.NetManager.Ethernet 318 * @systemapi Hide this for inner system use. 319 * @since 9 320 */ 321 dnsServers: string; 322 323 /** 324 * Indicates the HttpProxy settings, no proxy is to be used as default. 325 * @type {?HttpProxy} 326 * @syscap SystemCapability.Communication.NetManager.Ethernet 327 * @systemapi Hide this for inner system use. 328 * @since 10 329 */ 330 httpProxy?: HttpProxy; 331 } 332 333 /** 334 * The interface is used to monitor network interface status changes. 335 * @interface InterfaceStateInfo 336 * @syscap SystemCapability.Communication.NetManager.Ethernet 337 * @systemapi Hide this for inner system use. 338 * @since 11 339 */ 340 export interface InterfaceStateInfo { 341 /** 342 * Define network card name. 343 * @type { string } 344 * @syscap SystemCapability.Communication.NetManager.Ethernet 345 * @systemapi Hide this for inner system use. 346 * @since 11 347 */ 348 iface: string; 349 /** 350 * Check if it is active. 351 * @type { boolean } 352 * @syscap SystemCapability.Communication.NetManager.Ethernet 353 * @systemapi Hide this for inner system use. 354 * @since 11 355 */ 356 active: boolean; 357 } 358 359 /** 360 * Defines the configuration mode of the Ethernet connection. 361 * @enum {number} 362 * @syscap SystemCapability.Communication.NetManager.Ethernet 363 * @systemapi Hide this for inner system use. 364 * @since 9 365 */ 366 export enum IPSetMode { 367 /** 368 * WAN Static configuration. 369 * @syscap SystemCapability.Communication.NetManager.Ethernet 370 * @systemapi Hide this for inner system use. 371 * @since 9 372 */ 373 STATIC = 0, 374 375 /** 376 * WAN Dynamic configuration. 377 * @syscap SystemCapability.Communication.NetManager.Ethernet 378 * @systemapi Hide this for inner system use. 379 * @since 9 380 */ 381 DHCP = 1, 382 383 /** 384 * LAN Static configuration. 385 * @syscap SystemCapability.Communication.NetManager.Ethernet 386 * @systemapi Hide this for inner system use. 387 * @since 11 388 */ 389 LAN_STATIC = 2, 390 391 /** 392 * LAN Dynamic configuration. 393 * @syscap SystemCapability.Communication.NetManager.Ethernet 394 * @systemapi Hide this for inner system use. 395 * @since 11 396 */ 397 LAN_DHCP = 3 398 } 399 400 /** 401 * Defines the mac address info of the Ethernet. 402 * @interface MacAddressInfo 403 * @syscap SystemCapability.Communication.NetManager.Ethernet 404 * @systemapi Hide this for inner system use. 405 * @since 13 406 */ 407 export interface MacAddressInfo { 408 /** 409 * Ethernet interface name. 410 * @type { string } 411 * @syscap SystemCapability.Communication.NetManager.Ethernet 412 * @systemapi Hide this for inner system use. 413 * @since 13 414 */ 415 iface: string; 416 417 /** 418 * Ethernet specific mac address. 419 * @type { string } 420 * @syscap SystemCapability.Communication.NetManager.Ethernet 421 * @systemapi Hide this for inner system use. 422 * @since 13 423 */ 424 macAddress: string; 425 } 426} 427 428export default ethernet;