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 netSpecifier 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 * @param callback Returns the {@link NetHandle} object; 44 * returns {@code null} if the default network is not activated. 45 * @permission ohos.permission.GET_NETWORK_INFO 46 * @throws {BusinessError} 201 - Permission denied. 47 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 48 * @throws {BusinessError} 2100003 - System internal error. 49 */ 50 function getDefaultNet(callback: AsyncCallback<NetHandle>): void; 51 function getDefaultNet(): Promise<NetHandle>; 52 53 /** 54 * Obtains the data network that is activated by default. 55 * 56 * <p>To call this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 57 * 58 * @returns Returns the {@link NetHandle} object; 59 * returns {@code null} if the default network is not activated. 60 * @permission ohos.permission.GET_NETWORK_INFO 61 * @throws {BusinessError} 201 - Permission denied. 62 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 63 * @throws {BusinessError} 2100003 - System internal error. 64 * @since 9 65 */ 66 function getDefaultNetSync(): NetHandle; 67 68 /** 69 * Obtains the list of data networks that are activated. 70 * 71 * @param callback Returns the {@link NetHandle} object; returns {@code null} if no network is activated. 72 * @permission ohos.permission.GET_NETWORK_INFO 73 * @throws {BusinessError} 201 - Permission denied. 74 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 75 * @throws {BusinessError} 2100003 - System internal error. 76 */ 77 function getAllNets(callback: AsyncCallback<Array<NetHandle>>): void; 78 function getAllNets(): Promise<Array<NetHandle>>; 79 80 /** 81 * Queries the connection properties of a network. 82 * 83 * @param netHandle Indicates the network to be queried. 84 * @param callback Returns the {@link ConnectionProperties} object. 85 * @permission ohos.permission.GET_NETWORK_INFO 86 * @throws {BusinessError} 201 - Permission denied. 87 * @throws {BusinessError} 401 - Parameter error. 88 * @throws {BusinessError} 2100001 - Invalid parameter value. 89 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 90 * @throws {BusinessError} 2100003 - System internal error. 91 */ 92 function getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback<ConnectionProperties>): void; 93 function getConnectionProperties(netHandle: NetHandle): Promise<ConnectionProperties>; 94 95 /** 96 * Obtains {@link NetCapabilities} of a {@link NetHandle} object. 97 * 98 * @param netHandle Indicates the handle. See {@link NetHandle}. 99 * @param callback Returns {@link NetCapabilities}; returns {@code null} if {@code handle} is invalid. 100 * @permission ohos.permission.GET_NETWORK_INFO 101 * @throws {BusinessError} 201 - Permission denied. 102 * @throws {BusinessError} 401 - Parameter error. 103 * @throws {BusinessError} 2100001 - Invalid parameter value. 104 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 105 * @throws {BusinessError} 2100003 - System internal error. 106 */ 107 function getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback<NetCapabilities>): void; 108 function getNetCapabilities(netHandle: NetHandle): Promise<NetCapabilities>; 109 110 /** 111 * Checks whether data traffic usage on the current network is metered. 112 * 113 * @param callback Returns {@code true} if data traffic usage on the current network is metered; 114 * returns {@code false} otherwise. 115 * @permission ohos.permission.GET_NETWORK_INFO 116 * @throws {BusinessError} 201 - Permission denied. 117 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 118 * @throws {BusinessError} 2100003 - System internal error. 119 * @since 9 120 */ 121 function isDefaultNetMetered(callback: AsyncCallback<boolean>): void; 122 function isDefaultNetMetered(): Promise<boolean>; 123 124 /** 125 * Checks whether the default data network is activated. 126 * 127 * @param callback Returns {@code true} if the default data network is activated; returns {@code false} otherwise. 128 * @permission ohos.permission.GET_NETWORK_INFO 129 * @throws {BusinessError} 201 - Permission denied. 130 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 131 * @throws {BusinessError} 2100003 - System internal error. 132 */ 133 function hasDefaultNet(callback: AsyncCallback<boolean>): void; 134 function hasDefaultNet(): Promise<boolean>; 135 136 /** 137 * Enables the airplane mode for a device. 138 * 139 * <p>To invoke this method, you must have the {@code ohos.permission.CONNECTIVITY_INTERNAL} permission. 140 * 141 * @permission ohos.permission.CONNECTIVITY_INTERNAL 142 * @systemapi Hide this for inner system use. Only used for system app. 143 * @throws {BusinessError} 201 - Permission denied. 144 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 145 * @throws {BusinessError} 2100003 - System internal error. 146 */ 147 function enableAirplaneMode(callback: AsyncCallback<void>): void; 148 function enableAirplaneMode(): Promise<void>; 149 150 /** 151 * Disables the airplane mode for a device. 152 * 153 * <p>To invoke this method, you must have the {@code ohos.permission.CONNECTIVITY_INTERNAL} permission. 154 * 155 * @permission ohos.permission.CONNECTIVITY_INTERNAL 156 * @systemapi Hide this for inner system use. Only used for system app. 157 * @throws {BusinessError} 201 - Permission denied. 158 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 159 * @throws {BusinessError} 2100003 - System internal error. 160 */ 161 function disableAirplaneMode(callback: AsyncCallback<void>): void; 162 function disableAirplaneMode(): Promise<void>; 163 164 /** 165 * Reports the network state is connected. 166 * 167 * @param netHandle Indicates the network whose state is to be reported. 168 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 169 * @throws {BusinessError} 201 - Permission denied. 170 * @throws {BusinessError} 401 - Parameter error. 171 * @throws {BusinessError} 2100001 - Invalid parameter value. 172 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 173 * @throws {BusinessError} 2100003 - System internal error. 174 */ 175 function reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 176 function reportNetConnected(netHandle: NetHandle): Promise<void>; 177 178 /** 179 * Reports the network state is disconnected. 180 * 181 * @param netHandle Indicates the network whose state is to be reported. 182 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 183 * @throws {BusinessError} 201 - Permission denied. 184 * @throws {BusinessError} 401 - Parameter error. 185 * @throws {BusinessError} 2100001 - Invalid parameter value. 186 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 187 * @throws {BusinessError} 2100003 - System internal error. 188 */ 189 function reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 190 function reportNetDisconnected(netHandle: NetHandle): Promise<void>; 191 192 /** 193 * Resolves the host name to obtain all IP addresses based on the default data network. 194 * 195 * @param host Indicates the host name or the domain. 196 * @param callback Returns the NetAddress list. 197 * @permission ohos.permission.INTERNET 198 * @throws {BusinessError} 201 - Permission denied. 199 * @throws {BusinessError} 401 - Parameter error. 200 * @throws {BusinessError} 2100001 - Invalid parameter value. 201 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 202 * @throws {BusinessError} 2100003 - System internal error. 203 */ 204 function getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 205 function getAddressesByName(host: string): Promise<Array<NetAddress>>; 206 207 /** 208 * Obtains the {@link NetHandle} bound to a process using {@link setAppNet}. 209 * 210 * @param callback Returns the {@link NetHandle} bound to the process; 211 * returns {@code null} if no {@link NetHandle} is bound to the process. 212 * For details, see {@link NetHandle}. 213 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 214 * @throws {BusinessError} 2100003 - System internal error. 215 * @since 9 216 */ 217 function getAppNet(callback: AsyncCallback<NetHandle>): void; 218 219 /** 220 * Obtains the {@link NetHandle} bound to a process using {@link setAppNet}. 221 * 222 * @returns { Promise<NetHandle> } the promise returned by the function. 223 * returns {@code null} if no {@link NetHandle} is bound to the process. 224 * For details, see {@link NetHandle}. 225 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 226 * @throws {BusinessError} 2100003 - System internal error. 227 * @since 9 228 */ 229 function getAppNet(): Promise<NetHandle>; 230 231 /** 232 * Binds a process to {@code NetHandle}. 233 * 234 * <p>All the sockets created from the process will be bound to the {@code NetHandle}, 235 * and the resolution of all host names will be managed by the {@code NetHandle}. 236 * 237 * @param netHandle Indicates the handle. For details, see {@link NetHandle}. 238 * @param callback Returns the callback of setAppNet. 239 * @permission ohos.permission.INTERNET 240 * @throws {BusinessError} 201 - Permission denied. 241 * @throws {BusinessError} 401 - Parameter error. 242 * @throws {BusinessError} 2100001 - Invalid parameter value. 243 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 244 * @throws {BusinessError} 2100003 - System internal error. 245 * @since 9 246 */ 247 function setAppNet(netHandle: NetHandle, callback: AsyncCallback<void>): void; 248 249 /** 250 * Binds a process to {@code NetHandle}. 251 * 252 * <p>All the sockets created from the process will be bound to the {@code NetHandle}, 253 * and the resolution of all host names will be managed by the {@code NetHandle}. 254 * 255 * @param netHandle Indicates the handle. For details, see {@link NetHandle}. 256 * @returns { Promise<void> } the promise returned by the function. 257 * @permission ohos.permission.INTERNET 258 * @throws {BusinessError} 201 - Permission denied. 259 * @throws {BusinessError} 401 - Parameter error. 260 * @throws {BusinessError} 2100001 - Invalid parameter value. 261 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 262 * @throws {BusinessError} 2100003 - System internal error. 263 * @since 9 264 */ 265 function setAppNet(netHandle: NetHandle): Promise<void>; 266 267 export interface NetConnection { 268 on(type: 'netAvailable', callback: Callback<NetHandle>): void; 269 270 on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void; 271 272 on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void; 273 274 on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void; 275 276 on(type: 'netLost', callback: Callback<NetHandle>): void; 277 278 on(type: 'netUnavailable', callback: Callback<void>): void; 279 280 /** 281 * Receives status change notifications of a specified network. 282 * 283 * @permission ohos.permission.GET_NETWORK_INFO 284 * @throws {BusinessError} 201 - Permission denied. 285 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 286 * @throws {BusinessError} 2100003 - System internal error. 287 * @throws {BusinessError} 2101008 - The callback is not found. 288 * @throws {BusinessError} 2101022 - The number of requests exceeded the maximum. 289 */ 290 register(callback: AsyncCallback<void>): void; 291 292 /** 293 * Cancels listening for network status changes. 294 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 295 * @throws {BusinessError} 2100003 - System internal error. 296 * @throws {BusinessError} 2101007 - The same callback exists. 297 */ 298 unregister(callback: AsyncCallback<void>): void; 299 } 300 301 export interface NetSpecifier { 302 netCapabilities: NetCapabilities; 303 bearerPrivateIdentifier?: string; 304 } 305 306 export interface NetHandle { 307 netId: number; 308 309 /** 310 * Binds a TCPSocket or UDPSocket to the current network. All data flows from 311 * the socket will use this network, without being subject to {@link setAppNet}. 312 * Before using this method, ensure that the socket is disconnected. 313 * 314 * @param socketParam Indicates the TCPSocket or UDPSocket object. 315 * @throws {BusinessError} 401 - Parameter error. 316 * @throws {BusinessError} 2100001 - Invalid parameter value. 317 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 318 * @throws {BusinessError} 2100003 - System internal error. 319 * @since 9 320 */ 321 bindSocket(socketParam: TCPSocket | UDPSocket, callback: AsyncCallback<void>): void; 322 bindSocket(socketParam: TCPSocket | UDPSocket): Promise<void>; 323 324 /** 325 * Resolves a host name to obtain all IP addresses based on the specified NetHandle. 326 * 327 * @param host Indicates the host name or the domain. 328 * @param callback Returns the NetAddress list. 329 * @permission ohos.permission.INTERNET 330 * @throws {BusinessError} 201 - Permission denied. 331 * @throws {BusinessError} 401 - Parameter error. 332 * @throws {BusinessError} 2100001 - Invalid parameter value. 333 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 334 * @throws {BusinessError} 2100003 - System internal error. 335 */ 336 getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 337 getAddressesByName(host: string): Promise<Array<NetAddress>>; 338 339 /** 340 * Resolves a host name to obtain the first IP address based on the specified NetHandle. 341 * 342 * @param host Indicates the host name or the domain. 343 * @param callback Returns the first NetAddress. 344 * @permission ohos.permission.INTERNET 345 * @throws {BusinessError} 201 - Permission denied. 346 * @throws {BusinessError} 401 - Parameter error. 347 * @throws {BusinessError} 2100001 - Invalid parameter value. 348 * @throws {BusinessError} 2100002 - Operation failed. Cannot connect to service. 349 * @throws {BusinessError} 2100003 - System internal error. 350 */ 351 getAddressByName(host: string, callback: AsyncCallback<NetAddress>): void; 352 getAddressByName(host: string): Promise<NetAddress>; 353 } 354 355 export interface NetCapabilities { 356 linkUpBandwidthKbps?: number; 357 linkDownBandwidthKbps?: number; 358 networkCap?: Array<NetCap>; 359 bearerTypes: Array<NetBearType>; 360 } 361 362 export enum NetCap { 363 /** 364 * Indicates that the network can access the carrier's MMSC to send and receive multimedia messages. 365 */ 366 NET_CAPABILITY_MMS = 0, 367 368 /** 369 * Indicates that the network traffic is not metered. 370 */ 371 NET_CAPABILITY_NOT_METERED = 11, 372 373 /** 374 * Indicates that the network can access the Internet. 375 */ 376 NET_CAPABILITY_INTERNET = 12, 377 378 /** 379 * Indicates that the network does not use a VPN. 380 */ 381 NET_CAPABILITY_NOT_VPN = 15, 382 383 /** 384 * Indicates that the network is available. 385 */ 386 NET_CAPABILITY_VALIDATED = 16, 387 } 388 389 export enum NetBearType { 390 /** 391 * Indicates that the network is based on a cellular network. 392 */ 393 BEARER_CELLULAR = 0, 394 395 /** 396 * Indicates that the network is based on a Wi-Fi network. 397 */ 398 BEARER_WIFI = 1, 399 400 /** 401 * Indicates that the network is an Ethernet network. 402 */ 403 BEARER_ETHERNET = 3, 404 } 405 406 export interface ConnectionProperties { 407 interfaceName: string; 408 domains: string; 409 linkAddresses: Array<LinkAddress>; 410 dnses: Array<NetAddress>; 411 routes: Array<RouteInfo>; 412 mtu: number; 413 } 414 415 export interface RouteInfo { 416 interface: string; 417 destination: LinkAddress; 418 gateway: NetAddress; 419 hasGateway: boolean; 420 isDefaultRoute: boolean; 421 } 422 423 export interface LinkAddress { 424 address: NetAddress; 425 prefixLength: number; 426 } 427 428 export interface NetAddress { 429 address: string; 430 family?: number; // IPv4 = 1; IPv6 = 2, default is IPv4 431 port?: number; // [0, 65535] 432 } 433} 434 435export default connection; 436