1/* 2 * Copyright (C) 2022 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 16import {AsyncCallback, Callback} from "./basic"; 17import http from "./@ohos.net.http"; 18import socket from "./@ohos.net.socket"; 19 20/** 21 * Provides interfaces to manage and use data networks. 22 * 23 * @since 8 24 * @sysCap SystemCapability.Communication.NetManager.Core 25 */ 26declare namespace connection { 27 type HttpRequest = http.HttpRequest; 28 type TCPSocket = socket.TCPSocket; 29 type UDPSocket = socket.UDPSocket; 30 31 /** 32 * Create a network connection with optional netSpefifier and timeout. 33 * 34 * @param netSpecifier Indicates the network specifier. See {@link NetSpecifier}. 35 * @param timeout The time in milliseconds to attempt looking for a suitable network before 36 * {@link NetConnection#netUnavailable} is called. 37 */ 38 function createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection; 39 40 /** 41 * Obtains the data network that is activated by default. 42 * 43 * <p>To call this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 44 * 45 * @param callback Returns the {@link NetHandle} object; 46 * returns {@code null} if the default network is not activated. 47 * @permission ohos.permission.GET_NETWORK_INFO 48 */ 49 function getDefaultNet(callback: AsyncCallback<NetHandle>): void; 50 function getDefaultNet(): Promise<NetHandle>; 51 52 /** 53 * Obtains the list of data networks that are activated. 54 * 55 * <p>To invoke this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 56 * 57 * @param callback Returns the {@link NetHandle} object; returns {@code null} if no network is activated. 58 * @permission ohos.permission.GET_NETWORK_INFO 59 */ 60 function getAllNets(callback: AsyncCallback<Array<NetHandle>>): void; 61 function getAllNets(): Promise<Array<NetHandle>>; 62 63 /** 64 * Queries the connection properties of a network. 65 * 66 * <p>This method requires the {@code ohos.permission.GET_NETWORK_INFO} permission. 67 * 68 * @param netHandle Indicates the network to be queried. 69 * @param callback Returns the {@link ConnectionProperties} object. 70 * @permission ohos.permission.GET_NETWORK_INFO 71 */ 72 function getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback<ConnectionProperties>): void; 73 function getConnectionProperties(netHandle: NetHandle): Promise<ConnectionProperties>; 74 75 /** 76 * Obtains {@link NetCapabilities} of a {@link NetHandle} object. 77 * 78 * <p>To invoke this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 79 * 80 * @param netHandle Indicates the handle. See {@link NetHandle}. 81 * @param callback Returns {@link NetCapabilities}; returns {@code null} if {@code handle} is invalid. 82 * @permission ohos.permission.GET_NETWORK_INFO 83 */ 84 function getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback<NetCapabilities>): void; 85 function getNetCapabilities(netHandle: NetHandle): Promise<NetCapabilities>; 86 87 /** 88 * Checks whether the default data network is activated. 89 * 90 * @param callback Returns {@code true} if the default data network is activated; returns {@code false} otherwise. 91 */ 92 function hasDefaultNet(callback: AsyncCallback<boolean>): void; 93 function hasDefaultNet(): Promise<boolean>; 94 95 /** 96 * Enables the airplane mode for a device. 97 * 98 * @systemapi Hide this for inner system use. Only used for system app. 99 */ 100 function enableAirplaneMode(callback: AsyncCallback<void>): void; 101 function enableAirplaneMode(): Promise<void>; 102 103 /** 104 * Disables the airplane mode for a device. 105 * 106 * @systemapi Hide this for inner system use. Only used for system app. 107 */ 108 function disableAirplaneMode(callback: AsyncCallback<void>): void; 109 function disableAirplaneMode(): Promise<void>; 110 111 /** 112 * Reports the network state is connected. 113 * 114 * @param netHandle Indicates the network whose state is to be reported. 115 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 116 */ 117 function reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 118 function reportNetConnected(netHandle: NetHandle): Promise<void>; 119 120 /** 121 * Reports the network state is disconnected. 122 * 123 * @param netHandle Indicates the network whose state is to be reported. 124 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 125 */ 126 function reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 127 function reportNetDisconnected(netHandle: NetHandle): Promise<void>; 128 129 /** 130 * Resolves the host name to obtain all IP addresses based on the default data network. 131 * 132 * @param host Indicates the host name or the domain. 133 * @param callback Returns the NetAddress list. 134 * @permission ohos.permission.GET_NETWORK_INFO 135 */ 136 function getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 137 function getAddressesByName(host: string): Promise<Array<NetAddress>>; 138 139 export interface NetConnection { 140 on(type: 'netAvailable', callback: Callback<NetHandle>): void; 141 142 on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void; 143 144 on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void; 145 146 on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void; 147 148 on(type: 'netLost', callback: Callback<NetHandle>): void; 149 150 on(type: 'netUnavailable', callback: Callback<void>): void; 151 152 /** 153 * Receives status change notifications of a specified network. 154 * 155 * @permission ohos.permission.GET_NETWORK_INFO 156 */ 157 register(callback: AsyncCallback<void>): void; 158 159 /** 160 * Cancels listening for network status changes. 161 */ 162 unregister(callback: AsyncCallback<void>): void; 163 } 164 165 export interface NetSpecifier { 166 netCapabilities: NetCapabilities; 167 bearerPrivateIdentifier?: string; 168 } 169 170 export interface NetHandle { 171 netId: number; 172 173 /** 174 * Binds a TCPSocket or UDPSocket to the current network. All data flows from 175 * the socket will use this network, without being subject to {@link setAppNet}. 176 * Before using this method, ensure that the socket is disconnected. 177 * 178 * @param socketParam Indicates the TCPSocket or UDPSocket object. 179 */ 180 bindSocket(socketParam: TCPSocket | UDPSocket, callback: AsyncCallback<void>): void; 181 bindSocket(socketParam: TCPSocket | UDPSocket): Promise<void>; 182 183 /** 184 * Accesses a specified URL. 185 * 186 * @param url Indicates a URL connection. 187 * @param callback Returns a {@code URLConnection} object matching the given {@code url}. 188 */ 189 openConnection(url: string, callback: AsyncCallback<HttpRequest>): void; 190 openConnection(url: string, proxy: NetProxy, callback: AsyncCallback<HttpRequest>): void; 191 openConnection(url: string, proxy?: NetProxy): Promise<HttpRequest>; 192 193 /** 194 * Resolves a host name to obtain all IP addresses based on the specified NetHandle. 195 * 196 * @param host Indicates the host name or the domain. 197 * @param callback Returns the NetAddress list. 198 */ 199 getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 200 getAddressesByName(host: string): Promise<Array<NetAddress>>; 201 202 /** 203 * Resolves a host name to obtain the first IP address based on the specified NetHandle. 204 * 205 * @param host Indicates the host name or the domain. 206 * @return Returns the first NetAddress. 207 */ 208 getAddressByName(host: string, callback: AsyncCallback<NetAddress>): void; 209 getAddressByName(host: string): Promise<NetAddress>; 210 } 211 212 export interface NetCapabilities { 213 linkUpBandwidthKbps?: number; 214 linkDownBandwidthKbps?: number; 215 networkCap?: Array<NetCap>; 216 bearerTypes: Array<NetBearType>; 217 } 218 219 export enum NetCap { 220 /** 221 * Indicates that the network can access the carrier's MMSC to send and receive multimedia messages. 222 */ 223 NET_CAPABILITY_MMS = 0, 224 225 /** 226 * Indicates that the network can access the carrier's SUPL server. 227 */ 228 NET_CAPABILITY_SUPL = 1, 229 230 /** 231 * Indicates that the network can access the carrier's DUN or Tethering gateway. 232 */ 233 NET_CAPABILITY_DUN = 2, 234 235 /** 236 * Indicates that the network can access the FOTA server for remote device upgrade. 237 */ 238 NET_CAPABILITY_FOTA = 3, 239 240 /** 241 * Indicates that the network can access the IMS server. 242 */ 243 NET_CAPABILITY_IMS = 4, 244 245 /** 246 * Indicates that the network can access the carrier's CBS server. 247 */ 248 NET_CAPABILITY_CBS = 5, 249 250 /** 251 * Indicates that the network can be used for Wi-Fi Direct. 252 */ 253 NET_CAPABILITY_WIFI_P2P = 6, 254 255 /** 256 * Indicates that the network can access the carrier's Initial Attach server. 257 */ 258 NET_CAPABILITY_IA = 7, 259 260 /** 261 * Indicates that the network can access the carrier's RCS server. 262 */ 263 NET_CAPABILITY_RCS = 8, 264 265 /** 266 * Indicates that the network can access the carrier's XCAP server. 267 */ 268 NET_CAPABILITY_XCAP = 9, 269 270 /** 271 * Indicates that the network can access the carrier's IMS emergency call server. 272 */ 273 NET_CAPABILITY_EIMS = 10, 274 275 /** 276 * Indicates that the network traffic is not metered. 277 */ 278 NET_CAPABILITY_NOT_METERED = 11, 279 280 /** 281 * Indicates that the network can access the Internet. 282 */ 283 NET_CAPABILITY_INTERNET = 12, 284 285 /** 286 * Indicates that the network is not restricted. 287 */ 288 NET_CAPABILITY_NOT_RESTRICTED = 13, 289 290 /** 291 * Indicates that the network is trusted. 292 */ 293 NET_CAPABILITY_TRUSTED = 14, 294 295 /** 296 * Indicates that the network does not use a VPN. 297 */ 298 NET_CAPABILITY_NOT_VPN = 15, 299 300 /** 301 * Indicates that the network is available. 302 */ 303 NET_CAPABILITY_VALIDATED = 16, 304 305 /** 306 * Indicates that this network was found to have a captive portal in place last time it was 307 * probed. 308 */ 309 NET_CAPABILITY_CAPTIVE_PORTAL = 17, 310 311 /** 312 * Indicates that the network is unavailable during roaming. 313 */ 314 NET_CAPABILITY_NOT_ROAMING = 18, 315 316 /** 317 * Indicates that the network is available only for foreground applications. 318 */ 319 NET_CAPABILITY_FOREGROUND = 19, 320 321 /** 322 * Indicates that the network is not congested. 323 */ 324 NET_CAPABILITY_NOT_CONGESTED = 20, 325 326 /** 327 * Indicates that the network is not suspended. 328 */ 329 NET_CAPABILITY_NOT_SUSPENDED = 21, 330 331 /** 332 * Indicates that traffic that goes through this network is paid by oem. For example, 333 * this network can be used by system apps to upload telemetry data. 334 * 335 * @systemapi Hide this for inner system use. 336 */ 337 NET_CAPABILITY_OEM_PAID = 22, 338 339 /** 340 * Indicates that the network can access the Mission Critical server of the carrier. 341 */ 342 NET_CAPABILITY_MCX = 23, 343 344 /** 345 * Indicates that the network was tested to only provide partial connectivity. 346 * 347 * @systemapi Hide this for inner system use. 348 */ 349 NET_CAPABILITY_PARTIAL_CONNECTIVITY = 24, 350 351 /** 352 * Indicates that the network extends cap 353 * 354 * @systemapi Hide this for inner system use. 355 */ 356 NET_CAPABILITY_HW_BASE = NET_CAPABILITY_PARTIAL_CONNECTIVITY, 357 358 /** 359 * Indicates that the network can access the BIP0 server. 360 * 361 * @systemapi Hide this for inner system use. 362 */ 363 NET_CAPABILITY_BIP0 = NET_CAPABILITY_HW_BASE + 1, 364 365 /** 366 * Indicates that the network can access the BIP1 server. 367 * 368 * @systemapi Hide this for inner system use. 369 */ 370 NET_CAPABILITY_BIP1 = NET_CAPABILITY_HW_BASE + 2, 371 372 /** 373 * Indicates that the network can access the BIP2 server. 374 * 375 * @systemapi Hide this for inner system use. 376 */ 377 NET_CAPABILITY_BIP2 = NET_CAPABILITY_HW_BASE + 3, 378 379 /** 380 * Indicates that the network can access the BIP3 server. 381 * 382 * @systemapi Hide this for inner system use. 383 */ 384 NET_CAPABILITY_BIP3 = NET_CAPABILITY_HW_BASE + 4, 385 386 /** 387 * Indicates that the network can access the BIP4 server. 388 * 389 * @systemapi Hide this for inner system use. 390 */ 391 NET_CAPABILITY_BIP4 = NET_CAPABILITY_HW_BASE + 5, 392 393 /** 394 * Indicates that the network can access the BIP5 server. 395 * 396 * @systemapi Hide this for inner system use. 397 */ 398 NET_CAPABILITY_BIP5 = NET_CAPABILITY_HW_BASE + 6, 399 400 /** 401 * Indicates that the network can access the BIP6 server. 402 * 403 * @systemapi Hide this for inner system use. 404 */ 405 NET_CAPABILITY_BIP6 = NET_CAPABILITY_HW_BASE + 7, 406 407 /** 408 * Indicates that the network can access internal default servers. 409 * 410 * @systemapi Hide this for inner system use. 411 */ 412 NET_CAPABILITY_INTERNAL_DEFAULT 413 } 414 415 export enum NetBearType { 416 /** 417 * Indicates that the network is based on a cellular network. 418 */ 419 BEARER_CELLULAR = 0, 420 421 /** 422 * Indicates that the network is based on a Wi-Fi network. 423 */ 424 BEARER_WIFI = 1, 425 426 /** 427 * Indicates that the network is based on a Bluetooth network. 428 */ 429 BEARER_BLUETOOTH = 2, 430 431 /** 432 * Indicates that the network is an Ethernet network. 433 */ 434 BEARER_ETHERNET = 3, 435 436 /** 437 * Indicates that the network is a VPN. 438 */ 439 BEARER_VPN = 4, 440 441 /** 442 * Indicates that the network is a Wi-Fi Aware network. 443 */ 444 BEARER_WIFI_AWARE = 5, 445 446 /** 447 * Indicates that the network is a LoWPAN network. 448 */ 449 BEARER_LOWPAN = 6 450 } 451 452 export interface ConnectionProperties { 453 interfaceName: string; 454 isUsePrivateDns: boolean; 455 privateDnsServerName: string; 456 domains: string; 457 httpProxy: HttpProxy; 458 linkAddresses: Array<LinkAddress>; 459 dnses: Array<NetAddress>; 460 routes: Array<RouteInfo>; 461 mtu: number; 462 } 463 464 export interface HttpProxy { 465 host: string; 466 port: number; 467 parsedExclusionList: Array<string>; 468 } 469 470 export interface RouteInfo { 471 interface: string; 472 destination: LinkAddress; 473 gateway: NetAddress; 474 hasGateway: boolean; 475 isDefaultRoute: boolean; 476 } 477 478 export interface LinkAddress { 479 address: NetAddress; 480 prefixLength: number; 481 } 482 483 /** 484 * @since 7 485 */ 486 export interface NetAddress { 487 address: string; 488 family?: number; // IPv4 = 1; IPv6 = 2, default is IPv4 489 port?: number; // [0, 65535] 490 } 491 492 export interface NetProxy { 493 type: ProxyType; 494 address: NetAddress; 495 } 496 497 export enum ProxyType { 498 /** 499 * Represents proxy for high level protocols such as HTTP or FTP. 500 */ 501 HTTP, 502 /** 503 * Represents a SOCKS (V4 or V5) proxy. 504 */ 505 SOCKS 506 } 507} 508 509export default connection;