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