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