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 data network that is activated by default. 54 * 55 * <p>To call this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 56 * 57 * @return Returns the {@link NetHandle} object; 58 * returns {@code null} if the default network is not activated. 59 * @permission ohos.permission.GET_NETWORK_INFO 60 * @since 9 61 */ 62 function getDefaultNetSync(): NetHandle; 63 64 /** 65 * Obtains the list of data networks that are activated. 66 * 67 * <p>To invoke this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 68 * 69 * @param callback Returns the {@link NetHandle} object; returns {@code null} if no network is activated. 70 * @permission ohos.permission.GET_NETWORK_INFO 71 */ 72 function getAllNets(callback: AsyncCallback<Array<NetHandle>>): void; 73 function getAllNets(): Promise<Array<NetHandle>>; 74 75 /** 76 * Queries the connection properties of a network. 77 * 78 * <p>This method requires the {@code ohos.permission.GET_NETWORK_INFO} permission. 79 * 80 * @param netHandle Indicates the network to be queried. 81 * @param callback Returns the {@link ConnectionProperties} object. 82 * @permission ohos.permission.GET_NETWORK_INFO 83 */ 84 function getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback<ConnectionProperties>): void; 85 function getConnectionProperties(netHandle: NetHandle): Promise<ConnectionProperties>; 86 87 /** 88 * Obtains {@link NetCapabilities} of a {@link NetHandle} object. 89 * 90 * <p>To invoke this method, you must have the {@code ohos.permission.GET_NETWORK_INFO} permission. 91 * 92 * @param netHandle Indicates the handle. See {@link NetHandle}. 93 * @param callback Returns {@link NetCapabilities}; returns {@code null} if {@code handle} is invalid. 94 * @permission ohos.permission.GET_NETWORK_INFO 95 */ 96 function getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback<NetCapabilities>): void; 97 function getNetCapabilities(netHandle: NetHandle): Promise<NetCapabilities>; 98 99 /** 100 * Checks whether data traffic usage on the current network is metered. 101 * 102 * @param callback Returns {@code true} if data traffic usage on the current network is metered; 103 * returns {@code false} otherwise. 104 * @permission ohos.permission.GET_NETWORK_INFO 105 * @since 9 106 */ 107 function isDefaultNetMetered(callback: AsyncCallback<boolean>): void; 108 function isDefaultNetMetered(): Promise<boolean>; 109 110 /** 111 * Checks whether the default data network is activated. 112 * 113 * @param callback Returns {@code true} if the default data network is activated; returns {@code false} otherwise. 114 */ 115 function hasDefaultNet(callback: AsyncCallback<boolean>): void; 116 function hasDefaultNet(): Promise<boolean>; 117 118 /** 119 * Enables the airplane mode for a device. 120 * 121 * @systemapi Hide this for inner system use. Only used for system app. 122 */ 123 function enableAirplaneMode(callback: AsyncCallback<void>): void; 124 function enableAirplaneMode(): Promise<void>; 125 126 /** 127 * Disables the airplane mode for a device. 128 * 129 * @systemapi Hide this for inner system use. Only used for system app. 130 */ 131 function disableAirplaneMode(callback: AsyncCallback<void>): void; 132 function disableAirplaneMode(): Promise<void>; 133 134 /** 135 * Reports the network state is connected. 136 * 137 * @param netHandle Indicates the network whose state is to be reported. 138 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 139 */ 140 function reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 141 function reportNetConnected(netHandle: NetHandle): Promise<void>; 142 143 /** 144 * Reports the network state is disconnected. 145 * 146 * @param netHandle Indicates the network whose state is to be reported. 147 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 148 */ 149 function reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 150 function reportNetDisconnected(netHandle: NetHandle): Promise<void>; 151 152 /** 153 * Resolves the host name to obtain all IP addresses based on the default data network. 154 * 155 * @param host Indicates the host name or the domain. 156 * @param callback Returns the NetAddress list. 157 * @permission ohos.permission.GET_NETWORK_INFO 158 */ 159 function getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 160 function getAddressesByName(host: string): Promise<Array<NetAddress>>; 161 162 /** 163 * Obtains http proxy configuration 164 * 165 * @param callback Returns the {@link HttpProxy} object. 166 */ 167 function getGlobalHttpProxy(callback:AsyncCallback<HttpProxy>):void; 168 function getGlobalHttpProxy():Promise<HttpProxy>; 169 170 /** 171 * Set http proxy information 172 * 173 * @param httpProxy Indicates the http proxy configuration. 174 * @permission ohos.permission.CONNECTIVITY_INTERNAL 175 */ 176 function setGlobalHttpProxy(httpProxy: HttpProxy, callback:AsyncCallback<void>):void; 177 function setGlobalHttpProxy(httpProxy: HttpProxy):Promise<void>; 178 179 export interface NetConnection { 180 on(type: 'netAvailable', callback: Callback<NetHandle>): void; 181 182 on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void; 183 184 on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void; 185 186 on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void; 187 188 on(type: 'netLost', callback: Callback<NetHandle>): void; 189 190 on(type: 'netUnavailable', callback: Callback<void>): void; 191 192 /** 193 * Receives status change notifications of a specified network. 194 * 195 * @permission ohos.permission.GET_NETWORK_INFO 196 */ 197 register(callback: AsyncCallback<void>): void; 198 199 /** 200 * Cancels listening for network status changes. 201 */ 202 unregister(callback: AsyncCallback<void>): void; 203 } 204 205 export interface NetSpecifier { 206 netCapabilities: NetCapabilities; 207 bearerPrivateIdentifier?: string; 208 } 209 210 export interface NetHandle { 211 netId: number; 212 213 /** 214 * Binds a TCPSocket or UDPSocket to the current network. All data flows from 215 * the socket will use this network, without being subject to {@link setAppNet}. 216 * Before using this method, ensure that the socket is disconnected. 217 * 218 * @param socketParam Indicates the TCPSocket or UDPSocket object. 219 */ 220 bindSocket(socketParam: TCPSocket | UDPSocket, callback: AsyncCallback<void>): void; 221 bindSocket(socketParam: TCPSocket | UDPSocket): Promise<void>; 222 223 /** 224 * Resolves a host name to obtain all IP addresses based on the specified NetHandle. 225 * 226 * @param host Indicates the host name or the domain. 227 * @param callback Returns the NetAddress list. 228 * @permission ohos.permission.GET_NETWORK_INFO 229 */ 230 getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 231 getAddressesByName(host: string): Promise<Array<NetAddress>>; 232 233 /** 234 * Resolves a host name to obtain the first IP address based on the specified NetHandle. 235 * 236 * @param host Indicates the host name or the domain. 237 * @return Returns the first NetAddress. 238 * @permission ohos.permission.GET_NETWORK_INFO 239 */ 240 getAddressByName(host: string, callback: AsyncCallback<NetAddress>): void; 241 getAddressByName(host: string): Promise<NetAddress>; 242 } 243 244 export interface NetCapabilities { 245 linkUpBandwidthKbps?: number; 246 linkDownBandwidthKbps?: number; 247 networkCap?: Array<NetCap>; 248 bearerTypes: Array<NetBearType>; 249 } 250 251 export enum NetCap { 252 /** 253 * Indicates that the network can access the carrier's MMSC to send and receive multimedia messages. 254 */ 255 NET_CAPABILITY_MMS = 0, 256 257 /** 258 * Indicates that the network traffic is not metered. 259 */ 260 NET_CAPABILITY_NOT_METERED = 11, 261 262 /** 263 * Indicates that the network can access the Internet. 264 */ 265 NET_CAPABILITY_INTERNET = 12, 266 267 /** 268 * Indicates that the network does not use a VPN. 269 */ 270 NET_CAPABILITY_NOT_VPN = 15, 271 272 /** 273 * Indicates that the network is available. 274 */ 275 NET_CAPABILITY_VALIDATED = 16, 276 } 277 278 export enum NetBearType { 279 /** 280 * Indicates that the network is based on a cellular network. 281 */ 282 BEARER_CELLULAR = 0, 283 284 /** 285 * Indicates that the network is based on a Wi-Fi network. 286 */ 287 BEARER_WIFI = 1, 288 289 /** 290 * Indicates that the network is an Ethernet network. 291 */ 292 BEARER_ETHERNET = 3, 293 } 294 295 export interface ConnectionProperties { 296 interfaceName: string; 297 domains: string; 298 linkAddresses: Array<LinkAddress>; 299 dnses: Array<NetAddress>; 300 routes: Array<RouteInfo>; 301 mtu: number; 302 } 303 304 export interface RouteInfo { 305 interface: string; 306 destination: LinkAddress; 307 gateway: NetAddress; 308 hasGateway: boolean; 309 isDefaultRoute: boolean; 310 } 311 312 export interface LinkAddress { 313 address: NetAddress; 314 prefixLength: number; 315 } 316 317 export interface NetAddress { 318 address: string; 319 family?: number; // IPv4 = 1; IPv6 = 2, default is IPv4 320 port?: number; // [0, 65535] 321 } 322 323 export interface HttpProxy { 324 host:string; 325 port:number; 326 parsedExclusionList:Array<string> 327 } 328} 329 330export default connection;