• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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";
18import cert from "./@ohos.security.cert";
19
20/**
21 * Provides TCP and UDP Socket APIs.
22 *
23 * @since 7
24 * @syscap SystemCapability.Communication.NetStack
25 */
26declare namespace socket {
27  export import NetAddress = connection.NetAddress;
28  /**
29   * Deposit certificate
30   *
31   * @since 9
32   */
33  export type X509CertRawData = cert.EncodingBlob;
34
35  /**
36   * Creates a UDPSocket object.
37   */
38  function constructUDPSocketInstance(): UDPSocket;
39
40  /**
41   * Creates a TCPSocket object.
42   */
43  function constructTCPSocketInstance(): TCPSocket;
44
45  /**
46   * Creates a TLSSocket object.
47   *
48   * @since 9
49   */
50  function constructTLSSocketInstance(): TLSSocket;
51
52  export interface UDPSendOptions {
53    /**
54     * Data to send.
55     */
56    data: string | ArrayBuffer;
57
58    /**
59     * Destination address.
60     */
61    address: NetAddress;
62  }
63
64  export interface ExtraOptionsBase {
65    /**
66     * Size of the receive buffer, in MBS.
67     */
68    receiveBufferSize?: number;
69
70    /**
71     * Size of the send buffer, in MBS.
72     */
73    sendBufferSize?: number;
74
75    /**
76     * Whether to reuse addresses. The default value is false.
77     */
78    reuseAddress?: boolean;
79
80    /**
81     * Timeout duration of the UDPSocket connection, in milliseconds.
82     */
83    socketTimeout?: number;
84  }
85
86  export interface UDPExtraOptions extends ExtraOptionsBase {
87    /**
88     * Whether to send broadcast messages. The default value is false.
89     */
90    broadcast?: boolean;
91  }
92
93  export interface SocketStateBase {
94    /**
95     * Whether the connection is in the bound state.
96     */
97    isBound: boolean;
98
99    /**
100     * Whether the connection is in the closed state.
101     */
102    isClose: boolean;
103
104    /**
105     * Whether the connection is in the connected state.
106     */
107    isConnected: boolean;
108  }
109
110  export interface SocketRemoteInfo {
111    /**
112     * Bound IP address.
113     */
114    address: string;
115
116    /**
117     * Network protocol type. The options are as follows: IPv4, IPv6.
118     */
119    family: 'IPv4' | 'IPv6';
120
121    /**
122     * Port number. The value ranges from 0 to 65535.
123     */
124    port: number;
125
126    /**
127     * Length of the server response message, in bytes.
128     */
129    size: number;
130  }
131
132  export interface UDPSocket {
133    /**
134     * Binds the IP address and port number. The port number can be specified or randomly allocated by the system.
135     *
136     * @param address Destination address. {@link NetAddress}
137     * @permission ohos.permission.INTERNET
138     * @throws {BusinessError} 401 - Parameter error.
139     * @throws {BusinessError} 201 - Permission denied.
140     */
141    bind(address: NetAddress, callback: AsyncCallback<void>): void;
142    bind(address: NetAddress): Promise<void>;
143
144    /**
145     * Sends data over a UDPSocket connection.
146     *
147     * @param options Optional parameters {@link UDPSendOptions}.
148     * @permission ohos.permission.INTERNET
149     * @throws {BusinessError} 401 - Parameter error.
150     * @throws {BusinessError} 201 - Permission denied.
151     */
152    send(options: UDPSendOptions, callback: AsyncCallback<void>): void;
153    send(options: UDPSendOptions): Promise<void>;
154
155    /**
156     * Closes a UDPSocket connection.
157     * @permission ohos.permission.INTERNET
158     * @throws {BusinessError} 201 - Permission denied.
159     */
160    close(callback: AsyncCallback<void>): void;
161    close(): Promise<void>;
162
163    /**
164     * Obtains the status of the UDPSocket connection.
165     *
166     * @param callback Callback used to return the result. {@link SocketStateBase}.
167     * @permission ohos.permission.INTERNET
168     * @throws {BusinessError} 201 - Permission denied.
169     */
170    getState(callback: AsyncCallback<SocketStateBase>): void;
171    getState(): Promise<SocketStateBase>;
172
173    /**
174     * Sets other attributes of the UDPSocket connection.
175     *
176     * @param options Optional parameters {@link UDPExtraOptions}.
177     * @permission ohos.permission.INTERNET
178     * @throws {BusinessError} 401 - Parameter error.
179     * @throws {BusinessError} 201 - Permission denied.
180     */
181    setExtraOptions(options: UDPExtraOptions, callback: AsyncCallback<void>): void;
182    setExtraOptions(options: UDPExtraOptions): Promise<void>;
183
184    /**
185     * Listens for message receiving events of the UDPSocket connection.
186     */
187    on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void;
188
189    /**
190     * Cancels listening for message receiving events of the UDPSocket connection.
191     */
192    off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void;
193
194    /**
195     * Listens for data packet message events or close events of the UDPSocket connection.
196     */
197    on(type: 'listening' | 'close', callback: Callback<void>): void;
198
199    /**
200     * Cancels listening for data packet message events or close events of the UDPSocket connection.
201     */
202    off(type: 'listening' | 'close', callback?: Callback<void>): void;
203
204    /**
205     * Listens for error events of the UDPSocket connection.
206     */
207    on(type: 'error', callback: ErrorCallback): void;
208
209    /**
210     * Cancels listening for error events of the UDPSocket connection.
211     */
212    off(type: 'error', callback?: ErrorCallback): void;
213  }
214
215  export interface TCPConnectOptions {
216    /**
217     * Bound IP address and port number.
218     */
219    address: NetAddress;
220
221    /**
222     * Timeout duration of the TCPSocket connection, in milliseconds.
223     */
224    timeout?: number;
225  }
226
227  export interface TCPSendOptions {
228    /**
229     * Data to send.
230     */
231    data: string | ArrayBuffer;
232
233    /**
234     * Character encoding format.
235     */
236    encoding?: string;
237  }
238
239  export interface TCPExtraOptions extends ExtraOptionsBase {
240    /**
241     * Whether to keep the connection alive. The default value is false.
242     */
243    keepAlive?: boolean;
244
245    /**
246     * Whether to enable OOBInline. The default value is false.
247     */
248    OOBInline?: boolean;
249
250    /**
251     * Whether to enable no-delay on the TCPSocket connection. The default value is false.
252     */
253    TCPNoDelay?: boolean;
254
255    /**
256     * Socket linger.
257     */
258    socketLinger?: {on: boolean, linger: number};
259  }
260
261  export interface TCPSocket {
262    /**
263     * Binds the IP address and port number. The port number can be specified or randomly allocated by the system.
264     *
265     * @param address Destination address. {@link NetAddress}
266     * @permission ohos.permission.INTERNET
267     * @throws {BusinessError} 401 - Parameter error.
268     * @throws {BusinessError} 201 - Permission denied.
269     */
270    bind(address: NetAddress, callback: AsyncCallback<void>): void;
271    bind(address: NetAddress): Promise<void>;
272
273    /**
274     * Sets up a connection to the specified IP address and port number.
275     *
276     * @param options Optional parameters {@link TCPConnectOptions}.
277     * @permission ohos.permission.INTERNET
278     * @throws {BusinessError} 401 - Parameter error.
279     * @throws {BusinessError} 201 - Permission denied.
280     */
281    connect(options: TCPConnectOptions, callback: AsyncCallback<void>): void;
282    connect(options: TCPConnectOptions): Promise<void>;
283
284    /**
285     * Sends data over a TCPSocket connection.
286     *
287     * @param options Optional parameters {@link TCPSendOptions}.
288     * @permission ohos.permission.INTERNET
289     * @throws {BusinessError} 401 - Parameter error.
290     * @throws {BusinessError} 201 - Permission denied.
291     */
292    send(options: TCPSendOptions, callback: AsyncCallback<void>): void;
293    send(options: TCPSendOptions): Promise<void>;
294
295    /**
296     * Closes a TCPSocket connection.
297     * @permission ohos.permission.INTERNET
298     * @throws {BusinessError} 201 - Permission denied.
299     */
300    close(callback: AsyncCallback<void>): void;
301    close(): Promise<void>;
302
303    /**
304     * Obtains the peer address of a TCPSocket connection.
305     *
306     * @param callback Callback used to return the result. {@link NetAddress}
307     * @permission ohos.permission.INTERNET
308     * @throws {BusinessError} 201 - Permission denied.
309     */
310    getRemoteAddress(callback: AsyncCallback<NetAddress>): void;
311    getRemoteAddress(): Promise<NetAddress>;
312
313    /**
314     * Obtains the status of the TCPSocket connection.
315     *
316     * @param callback Callback used to return the result. {@link SocketStateBase}
317     * @permission ohos.permission.INTERNET
318     * @throws {BusinessError} 201 - Permission denied.
319     */
320    getState(callback: AsyncCallback<SocketStateBase>): void;
321    getState(): Promise<SocketStateBase>;
322
323    /**
324     * Sets other attributes of the TCPSocket connection.
325     *
326     * @param options Optional parameters {@link TCPExtraOptions}.
327     * @permission ohos.permission.INTERNET
328     * @throws {BusinessError} 401 - Parameter error.
329     * @throws {BusinessError} 201 - Permission denied.
330     */
331    setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void;
332    setExtraOptions(options: TCPExtraOptions): Promise<void>;
333
334    /**
335     * Listens for message receiving events of the TCPSocket connection.
336     */
337    on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void;
338
339    /**
340     * Cancels listening for message receiving events of the TCPSocket connection.
341     */
342    off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void;
343
344    /**
345     * Listens for connection or close events of the TCPSocket connection.
346     */
347    on(type: 'connect' | 'close', callback: Callback<void>): void;
348
349    /**
350     * Cancels listening for connection or close events of the TCPSocket connection.
351     */
352    off(type: 'connect' | 'close', callback?: Callback<void>): void;
353
354    /**
355     * Listens for error events of the TCPSocket connection.
356     */
357    on(type: 'error', callback: ErrorCallback): void;
358
359    /**
360     * Cancels listening for error events of the TCPSocket connection.
361     */
362    off(type: 'error', callback?: ErrorCallback): void;
363  }
364
365  /**
366   * @since 9
367   */
368  export interface TLSSocket {
369
370    /**
371     * Binds the IP address and port number. The port number can be specified or randomly allocated by the system.
372     *
373     * @param address Destination address. {@link NetAddress}
374     * @permission ohos.permission.INTERNET
375     * @throws {BusinessError} 401 - Parameter error.
376     * @throws {BusinessError} 201 - Permission denied.
377     * @throws {BusinessError} 2303198 - Address already in use.
378     * @throws {BusinessError} 2300002 - System internal error.
379     */
380    bind(address: NetAddress, callback: AsyncCallback<void>): void;
381    bind(address: NetAddress): Promise<void>;
382
383    /**
384     * Obtains the peer address of a TLSSocket connection.
385     *
386     * @param callback Callback used to return the result. {@link NetAddress}
387     * @throws {BusinessError} 2303188 - Socket operation on non-socket.
388     * @throws {BusinessError} 2300002 - System internal error.
389     */
390    getRemoteAddress(callback: AsyncCallback<NetAddress>): void;
391    getRemoteAddress(): Promise<NetAddress>;
392
393    /**
394     * Obtains the status of the TLSSocket connection.
395     *
396     * @param callback Callback used to return the result. {@link SocketStateBase}
397     * @throws {BusinessError} 2303188 - Socket operation on non-socket.
398     * @throws {BusinessError} 2300002 - System internal error.
399     */
400    getState(callback: AsyncCallback<SocketStateBase>): void;
401    getState(): Promise<SocketStateBase>;
402
403    /**
404     * Sets other attributes of the TLSSocket connection.
405     *
406     * @param options Optional parameters {@link TCPExtraOptions}.
407     * @throws {BusinessError} 401 - Parameter error.
408     * @throws {BusinessError} 2303188 - Socket operation on non-socket.
409     * @throws {BusinessError} 2300002 - System internal error.
410     */
411    setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void;
412    setExtraOptions(options: TCPExtraOptions): Promise<void>;
413
414    /**
415     * Listens for message receiving events of the TLSSocket connection.
416     *
417     * @throws {BusinessError} 401 - Parameter error.
418     */
419    on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void;
420
421    /**
422     * Cancels listening for message receiving events of the TLSSocket connection.
423     *
424     * @throws {BusinessError} 401 - Parameter error.
425     */
426    off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void;
427
428    /**
429     * Listens for connection or close events of the TLSSocket connection.
430     *
431     * @throws {BusinessError} 401 - Parameter error.
432     */
433    on(type: 'connect' | 'close', callback: Callback<void>): void;
434
435    /**
436     * Cancels listening for connection or close events of the TLSSocket connection.
437     *
438     * @throws {BusinessError} 401 - Parameter error.
439     */
440    off(type: 'connect' | 'close', callback?: Callback<void>): void;
441
442    /**
443     * Listens for error events of the TLSSocket connection.
444     *
445     * @throws {BusinessError} 401 - Parameter error.
446     */
447    on(type: 'error', callback: ErrorCallback): void;
448
449    /**
450     * Cancels listening for error events of the TLSSocket connection.
451     *
452     * @throws {BusinessError} 401 - Parameter error.
453     */
454    off(type: 'error', callback?: ErrorCallback): void;
455
456    /**
457     * Returns an object representing a local certificate.
458     *
459     * @throws {BusinessError} 2303501 - SSL is null.
460     * @throws {BusinessError} 2303504 - Error looking up x509
461     * @throws {BusinessError} 2300002 - System internal error.
462     */
463    getCertificate(callback: AsyncCallback<X509CertRawData>): void;
464    getCertificate(): Promise<X509CertRawData>;
465
466    /**
467     * Returns an object representing the peer certificate. If the peer does not provide a certificate,
468     * an empty object will be returned. If the socket is destroyed, null is returned.
469     * It only contains the peer's certificate.
470     *
471     * @throws {BusinessError} 2303501 - SSL is null.
472     * @throws {BusinessError} 2300002 - System internal error.
473     */
474    getRemoteCertificate(callback: AsyncCallback<X509CertRawData>): void;
475    getRemoteCertificate(): Promise<X509CertRawData>;
476
477    /**
478     * Returns a string containing the negotiated SSL/TLS protocol version of the current connection.
479     * For connected sockets that have not completed the handshake process, the value 'unknown' will be returned.
480     * Server sockets or disconnected client sockets will return a value of null.
481     *
482     * @throws {BusinessError} 2303501 - SSL is null.
483     * @throws {BusinessError} 2303505 - Error occurred in the tls system call.
484     * @throws {BusinessError} 2300002 - System internal error.
485     */
486    getProtocol(callback: AsyncCallback<string>): void;
487    getProtocol(): Promise<string>;
488
489    /**
490     * Returns a list containing the negotiated cipher suite information.
491     * For example:{"TLS_RSA_WITH_AES_128_CBC_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256"}
492     *
493     * @throws {BusinessError} 2303501 - SSL is null.
494     * @throws {BusinessError} 2303502 - Error in tls reading.
495     * @throws {BusinessError} 2303505 - Error occurred in the tls system call.
496     * @throws {BusinessError} 2300002 - System internal error.
497     */
498    getCipherSuite(callback: AsyncCallback<Array<string>>): void;
499    getCipherSuite(): Promise<Array<string>>;
500
501    /**
502     * The list of signature algorithms shared between the server and the client, in descending order of priority.
503     * @see https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html
504     *
505     * @throws {BusinessError} 2303501 - SSL is null.
506     * @throws {BusinessError} 2300002 - System internal error.
507     */
508    getSignatureAlgorithms(callback: AsyncCallback<Array<string>>): void;
509    getSignatureAlgorithms(): Promise<Array<string>>;
510
511    /**
512     * Sets up a connection to the specified IP address and port number.
513     * Only TCP is supported.
514     *
515     * @param options Optional parameters {@link TLSConnectOptions}.
516     * @throws {BusinessError} 401 - Parameter error.
517     * @throws {BusinessError} 2303104 - Interrupted system call.
518     * @throws {BusinessError} 2303109 - Bad file number.
519     * @throws {BusinessError} 2303111 - Resource temporarily unavailable try again.
520     * @throws {BusinessError} 2303188 - Socket operation on non-socket.
521     * @throws {BusinessError} 2303191 - Protocol wrong type for socket.
522     * @throws {BusinessError} 2303198 - Address already in use.
523     * @throws {BusinessError} 2303199 - Cannot assign requested address.
524     * @throws {BusinessError} 2303210 - Connection timed out.
525     * @throws {BusinessError} 2303501 - SSL is null.
526     * @throws {BusinessError} 2303502 - Error in tls reading.
527     * @throws {BusinessError} 2303503 - Error in tls writing
528     * @throws {BusinessError} 2303505 - Error occurred in the tls system call.
529     * @throws {BusinessError} 2303506 - Error clearing tls connection.
530     * @throws {BusinessError} 2300002 - System internal error.
531     */
532    connect(options: TLSConnectOptions, callback: AsyncCallback<void>): void;
533    connect(options: TLSConnectOptions): Promise<void>;
534
535    /**
536     * Sends data over a TLSSocket connection.
537     *
538     * @param data Optional parameters {@link string}.
539     * @throws {BusinessError} 401 - Parameter error.
540     * @throws {BusinessError} 2303501 - SSL is null.
541     * @throws {BusinessError} 2303503 - Error in tls writing.
542     * @throws {BusinessError} 2303505 - Error occurred in the tls system call.
543     * @throws {BusinessError} 2303506 - Error clearing tls connection.
544     * @throws {BusinessError} 2300002 - System internal error.
545     */
546    send(data: string, callback: AsyncCallback<void>): void;
547    send(data: string): Promise<void>;
548
549    /**
550     * Closes a TLSSocket connection
551     *
552     * @throws {BusinessError} 401 - Parameter error.
553     * @throws {BusinessError} 2303501 - SSL is null.
554     * @throws {BusinessError} 2303505 - Error occurred in the tls system call.
555     * @throws {BusinessError} 2303506 - Error clearing tls connection.
556     * @throws {BusinessError} 2300002 - System internal error.
557     */
558     close(callback: AsyncCallback<void>): void;
559     close(): Promise<void>;
560  }
561
562  /**
563   * @since 9
564   */
565  export interface TLSSecureOptions {
566    /**
567     * Certificate used to verify the identity of the server
568     */
569    ca: string | Array<string>;
570
571    /**
572     * Certificate proving the identity of the client
573     */
574    cert?: string;
575
576    /**
577     * Private key of client certificate
578     */
579    key?: string;
580
581    /**
582     * Password of the private key
583     */
584    password?: string;
585
586    /**
587     * TLS protocol version
588     */
589    protocols?: Protocol | Array<Protocol>;
590
591    /**
592     * default is false, use local cipher.
593     */
594    useRemoteCipherPrefer?: boolean;
595
596    /**
597     * Supported signature algorithms. This string can contain summary algorithms（SHA256、MD5、etc）、
598     * Public key algorithm（RSA-PSS、ECDSA、etc）、Combination of the two（For example 'RSA+SHA384'）
599     * or TLS v1.3 Scheme name（For example  rsa_pss_pss_sha512）
600     */
601    signatureAlgorithms?: string;
602
603    /**
604     * Crypto suite specification
605     */
606    cipherSuite?: string;
607  }
608
609  /**
610   * @since 9
611   */
612  export interface TLSConnectOptions {
613    address: NetAddress;
614    secureOptions: TLSSecureOptions;
615
616    /**
617     * Application layer protocol negotiation extension, such as "spdy/1", "http/1.1", "h2"
618     */
619    ALPNProtocols?: Array<string>;
620  }
621
622  /**
623   * @since 9
624   */
625  export enum Protocol {
626    TLSv12 = "TLSv1.2",
627    TLSv13 = "TLSv1.3",
628  }
629}
630
631export default socket;
632