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 * @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 */ 47 function getDefaultNet(callback: AsyncCallback<NetHandle>): void; 48 function getDefaultNet(): Promise<NetHandle>; 49 50 /** 51 * Obtains the list of data networks that are activated. 52 * 53 * @param callback Returns the {@link NetHandle} object; returns {@code null} if no network is activated. 54 * @permission ohos.permission.GET_NETWORK_INFO 55 */ 56 function getAllNets(callback: AsyncCallback<Array<NetHandle>>): void; 57 function getAllNets(): Promise<Array<NetHandle>>; 58 59 /** 60 * Queries the connection properties of a network. 61 * 62 * @param netHandle Indicates the network to be queried. 63 * @param callback Returns the {@link ConnectionProperties} object. 64 * @permission ohos.permission.GET_NETWORK_INFO 65 */ 66 function getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback<ConnectionProperties>): void; 67 function getConnectionProperties(netHandle: NetHandle): Promise<ConnectionProperties>; 68 69 /** 70 * Obtains {@link NetCapabilities} of a {@link NetHandle} object. 71 * 72 * @param netHandle Indicates the handle. See {@link NetHandle}. 73 * @param callback Returns {@link NetCapabilities}; returns {@code null} if {@code handle} is invalid. 74 * @permission ohos.permission.GET_NETWORK_INFO 75 */ 76 function getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback<NetCapabilities>): void; 77 function getNetCapabilities(netHandle: NetHandle): Promise<NetCapabilities>; 78 79 /** 80 * Checks whether the default data network is activated. 81 * 82 * @param callback Returns {@code true} if the default data network is activated; returns {@code false} otherwise. 83 */ 84 function hasDefaultNet(callback: AsyncCallback<boolean>): void; 85 function hasDefaultNet(): Promise<boolean>; 86 87 /** 88 * Enables the airplane mode for a device. 89 * 90 * @systemapi Hide this for inner system use. Only used for system app. 91 */ 92 function enableAirplaneMode(callback: AsyncCallback<void>): void; 93 function enableAirplaneMode(): Promise<void>; 94 95 /** 96 * Disables the airplane mode for a device. 97 * 98 * @systemapi Hide this for inner system use. Only used for system app. 99 */ 100 function disableAirplaneMode(callback: AsyncCallback<void>): void; 101 function disableAirplaneMode(): Promise<void>; 102 103 /** 104 * Reports the network state is connected. 105 * 106 * @param netHandle Indicates the network whose state is to be reported. 107 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 108 */ 109 function reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 110 function reportNetConnected(netHandle: NetHandle): Promise<void>; 111 112 /** 113 * Reports the network state is disconnected. 114 * 115 * @param netHandle Indicates the network whose state is to be reported. 116 * @permission ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET 117 */ 118 function reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>): void; 119 function reportNetDisconnected(netHandle: NetHandle): Promise<void>; 120 121 /** 122 * Resolves the host name to obtain all IP addresses based on the default data network. 123 * 124 * @param host Indicates the host name or the domain. 125 * @param callback Returns the NetAddress list. 126 * @permission ohos.permission.GET_NETWORK_INFO 127 */ 128 function getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 129 function getAddressesByName(host: string): Promise<Array<NetAddress>>; 130 131 export interface NetConnection { 132 on(type: 'netAvailable', callback: Callback<NetHandle>): void; 133 134 on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void; 135 136 on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void; 137 138 on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void; 139 140 on(type: 'netLost', callback: Callback<NetHandle>): void; 141 142 on(type: 'netUnavailable', callback: Callback<void>): void; 143 144 /** 145 * Receives status change notifications of a specified network. 146 * 147 * @permission ohos.permission.GET_NETWORK_INFO 148 */ 149 register(callback: AsyncCallback<void>): void; 150 151 /** 152 * Cancels listening for network status changes. 153 */ 154 unregister(callback: AsyncCallback<void>): void; 155 } 156 157 export interface NetSpecifier { 158 netCapabilities: NetCapabilities; 159 bearerPrivateIdentifier?: string; 160 } 161 162 export interface NetHandle { 163 netId: number; 164 165 /** 166 * Resolves a host name to obtain all IP addresses based on the specified NetHandle. 167 * 168 * @param host Indicates the host name or the domain. 169 * @param callback Returns the NetAddress list. 170 * @permission ohos.permission.GET_NETWORK_INFO 171 */ 172 getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void; 173 getAddressesByName(host: string): Promise<Array<NetAddress>>; 174 175 /** 176 * Resolves a host name to obtain the first IP address based on the specified NetHandle. 177 * 178 * @param host Indicates the host name or the domain. 179 * @return Returns the first NetAddress. 180 * @permission ohos.permission.GET_NETWORK_INFO 181 */ 182 getAddressByName(host: string, callback: AsyncCallback<NetAddress>): void; 183 getAddressByName(host: string): Promise<NetAddress>; 184 } 185 186 export interface NetCapabilities { 187 linkUpBandwidthKbps?: number; 188 linkDownBandwidthKbps?: number; 189 networkCap?: Array<NetCap>; 190 bearerTypes: Array<NetBearType>; 191 } 192 193 export enum NetCap { 194 /** 195 * Indicates that the network can access the carrier's MMSC to send and receive multimedia messages. 196 */ 197 NET_CAPABILITY_MMS = 0, 198 199 /** 200 * Indicates that the network traffic is not metered. 201 */ 202 NET_CAPABILITY_NOT_METERED = 11, 203 204 /** 205 * Indicates that the network can access the Internet. 206 */ 207 NET_CAPABILITY_INTERNET = 12, 208 209 /** 210 * Indicates that the network does not use a VPN. 211 */ 212 NET_CAPABILITY_NOT_VPN = 15, 213 214 /** 215 * Indicates that the network is available. 216 */ 217 NET_CAPABILITY_VALIDATED = 16, 218 } 219 220 export enum NetBearType { 221 /** 222 * Indicates that the network is based on a cellular network. 223 */ 224 BEARER_CELLULAR = 0, 225 226 /** 227 * Indicates that the network is based on a Wi-Fi network. 228 */ 229 BEARER_WIFI = 1, 230 231 /** 232 * Indicates that the network is an Ethernet network. 233 */ 234 BEARER_ETHERNET = 3, 235 } 236 237 export interface ConnectionProperties { 238 interfaceName: string; 239 domains: string; 240 linkAddresses: Array<LinkAddress>; 241 dnses: Array<NetAddress>; 242 routes: Array<RouteInfo>; 243 mtu: number; 244 } 245 246 export interface RouteInfo { 247 interface: string; 248 destination: LinkAddress; 249 gateway: NetAddress; 250 hasGateway: boolean; 251 isDefaultRoute: boolean; 252 } 253 254 export interface LinkAddress { 255 address: NetAddress; 256 prefixLength: number; 257 } 258 259 export interface NetAddress { 260 address: string; 261 family?: number; // IPv4 = 1; IPv6 = 2, default is IPv4 262 port?: number; // [0, 65535] 263 } 264} 265 266export default connection;