1/* 2 * Copyright (c) 2021-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, ErrorCallback} from "./basic"; 17import connection from "./@ohos.net.connection"; 18 19/** 20 * Provides TCP and UDP Socket APIs. 21 * 22 * @since 7 23 * @syscap SystemCapability.Communication.NetStack 24 */ 25declare namespace socket { 26 export import NetAddress = connection.NetAddress; 27 28 /** 29 * Creates a UDPSocket object. 30 */ 31 function constructUDPSocketInstance(): UDPSocket; 32 33 /** 34 * Creates a TCPSocket object. 35 */ 36 function constructTCPSocketInstance(): TCPSocket; 37 38 export interface UDPSendOptions { 39 /** 40 * Data to send. 41 */ 42 data: string | ArrayBuffer; 43 /** 44 * Destination address. 45 */ 46 address: NetAddress; 47 } 48 49 export interface ExtraOptionsBase { 50 /** 51 * Size of the receive buffer, in MBS. 52 */ 53 receiveBufferSize?: number; 54 /** 55 * Size of the send buffer, in MBS. 56 */ 57 sendBufferSize?: number; 58 /** 59 * Whether to reuse addresses. The default value is false. 60 */ 61 reuseAddress?: boolean; 62 /** 63 * Timeout duration of the UDPSocket connection, in milliseconds. 64 */ 65 socketTimeout?: number; 66 } 67 68 export interface UDPExtraOptions extends ExtraOptionsBase { 69 /** 70 * Whether to send broadcast messages. The default value is false. 71 */ 72 broadcast?: boolean; 73 } 74 75 export interface SocketStateBase { 76 /** 77 * Whether the connection is in the bound state. 78 */ 79 isBound: boolean; 80 /** 81 * Whether the connection is in the closed state. 82 */ 83 isClose: boolean; 84 /** 85 * Whether the connection is in the connected state. 86 */ 87 isConnected: boolean; 88 } 89 90 export interface SocketRemoteInfo { 91 /** 92 * Bound IP address. 93 */ 94 address: string; 95 /** 96 * Network protocol type. The options are as follows: IPv4, IPv6. 97 */ 98 family: 'IPv4' | 'IPv6'; 99 /** 100 * Port number. The value ranges from 0 to 65535. 101 */ 102 port: number; 103 /** 104 * Length of the server response message, in bytes. 105 */ 106 size: number; 107 } 108 109 export interface UDPSocket { 110 /** 111 * Binds the IP address and port number. The port number can be specified or randomly allocated by the system. 112 * 113 * @param address Destination address. {@link NetAddress} 114 * @permission ohos.permission.INTERNET 115 */ 116 bind(address: NetAddress, callback: AsyncCallback<void>): void; 117 bind(address: NetAddress): Promise<void>; 118 119 /** 120 * Sends data over a UDPSocket connection. 121 * 122 * @param options Optional parameters {@link UDPSendOptions}. 123 * @permission ohos.permission.INTERNET 124 */ 125 send(options: UDPSendOptions, callback: AsyncCallback<void>): void; 126 send(options: UDPSendOptions): Promise<void>; 127 128 /** 129 * Closes a UDPSocket connection. 130 * @permission ohos.permission.INTERNET 131 */ 132 close(callback: AsyncCallback<void>): void; 133 close(): Promise<void>; 134 135 /** 136 * Obtains the status of the UDPSocket connection. 137 * 138 * @param callback Callback used to return the result. {@link SocketStateBase}. 139 * @permission ohos.permission.INTERNET 140 */ 141 getState(callback: AsyncCallback<SocketStateBase>): void; 142 getState(): Promise<SocketStateBase>; 143 144 /** 145 * Sets other attributes of the UDPSocket connection. 146 * 147 * @param options Optional parameters {@link UDPExtraOptions}. 148 * @permission ohos.permission.INTERNET 149 */ 150 setExtraOptions(options: UDPExtraOptions, callback: AsyncCallback<void>): void; 151 setExtraOptions(options: UDPExtraOptions): Promise<void>; 152 153 /** 154 * Listens for message receiving events of the UDPSocket connection. 155 */ 156 on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void; 157 158 /** 159 * Cancels listening for message receiving events of the UDPSocket connection. 160 */ 161 off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void; 162 163 /** 164 * Listens for data packet message events or close events of the UDPSocket connection. 165 */ 166 on(type: 'listening' | 'close', callback: Callback<void>): void; 167 168 /** 169 * Cancels listening for data packet message events or close events of the UDPSocket connection. 170 */ 171 off(type: 'listening' | 'close', callback?: Callback<void>): void; 172 173 /** 174 * Listens for error events of the UDPSocket connection. 175 */ 176 on(type: 'error', callback: ErrorCallback): void; 177 178 /** 179 * Cancels listening for error events of the UDPSocket connection. 180 */ 181 off(type: 'error', callback?: ErrorCallback): void; 182 } 183 184 export interface TCPConnectOptions { 185 /** 186 * Bound IP address and port number. 187 */ 188 address: NetAddress; 189 /** 190 * Timeout duration of the TCPSocket connection, in milliseconds. 191 */ 192 timeout?: number; 193 } 194 195 export interface TCPSendOptions { 196 /** 197 * Data to send. 198 */ 199 data: string | ArrayBuffer; 200 /** 201 * Character encoding format. 202 */ 203 encoding?: string; 204 } 205 206 export interface TCPExtraOptions extends ExtraOptionsBase { 207 /** 208 * Whether to keep the connection alive. The default value is false. 209 */ 210 keepAlive?: boolean; 211 /** 212 * Whether to enable OOBInline. The default value is false. 213 */ 214 OOBInline?: boolean; 215 /** 216 * Whether to enable no-delay on the TCPSocket connection. The default value is false. 217 */ 218 TCPNoDelay?: boolean; 219 /** 220 * Socket linger. 221 */ 222 socketLinger: {on: boolean, linger: number}; 223 } 224 225 export interface TCPSocket { 226 /** 227 * Binds the IP address and port number. The port number can be specified or randomly allocated by the system. 228 * 229 * @param address Destination address. {@link NetAddress} 230 * @permission ohos.permission.INTERNET 231 */ 232 bind(address: NetAddress, callback: AsyncCallback<void>): void; 233 bind(address: NetAddress): Promise<void>; 234 235 /** 236 * Sets up a connection to the specified IP address and port number. 237 * 238 * @param options Optional parameters {@link TCPConnectOptions}. 239 * @permission ohos.permission.INTERNET 240 */ 241 connect(options: TCPConnectOptions, callback: AsyncCallback<void>): void; 242 connect(options: TCPConnectOptions): Promise<void>; 243 244 /** 245 * Sends data over a TCPSocket connection. 246 * 247 * @param options Optional parameters {@link TCPSendOptions}. 248 * @permission ohos.permission.INTERNET 249 */ 250 send(options: TCPSendOptions, callback: AsyncCallback<void>): void; 251 send(options: TCPSendOptions): Promise<void>; 252 253 /** 254 * Closes a TCPSocket connection. 255 * @permission ohos.permission.INTERNET 256 */ 257 close(callback: AsyncCallback<void>): void; 258 close(): Promise<void>; 259 260 /** 261 * Obtains the peer address of a TCPSocket connection. 262 * 263 * @param callback Callback used to return the result. {@link NetAddress} 264 * @permission ohos.permission.INTERNET 265 */ 266 getRemoteAddress(callback: AsyncCallback<NetAddress>): void; 267 getRemoteAddress(): Promise<NetAddress>; 268 269 /** 270 * Obtains the status of the TCPSocket connection. 271 * 272 * @param callback Callback used to return the result. {@link SocketStateBase} 273 * @permission ohos.permission.INTERNET 274 */ 275 getState(callback: AsyncCallback<SocketStateBase>): void; 276 getState(): Promise<SocketStateBase>; 277 278 /** 279 * Sets other attributes of the TCPSocket connection. 280 * 281 * @param options Optional parameters {@link TCPExtraOptions}. 282 * @permission ohos.permission.INTERNET 283 */ 284 setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void; 285 setExtraOptions(options: TCPExtraOptions): Promise<void>; 286 287 /** 288 * Listens for message receiving events of the TCPSocket connection. 289 */ 290 on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void; 291 292 /** 293 * Cancels listening for message receiving events of the TCPSocket connection. 294 */ 295 off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void; 296 297 /** 298 * Listens for connection or close events of the TCPSocket connection. 299 */ 300 on(type: 'connect' | 'close', callback: Callback<void>): void; 301 302 /** 303 * Cancels listening for connection or close events of the TCPSocket connection. 304 */ 305 off(type: 'connect' | 'close', callback?: Callback<void>): void; 306 307 /** 308 * Listens for error events of the TCPSocket connection. 309 */ 310 on(type: 'error', callback: ErrorCallback): void; 311 312 /** 313 * Cancels listening for error events of the TCPSocket connection. 314 */ 315 off(type: 'error', callback?: ErrorCallback): void; 316 } 317} 318 319export default socket;