• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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, ErrorCallback} from "./basic";
17
18/**
19 * Provides WebSocket APIs.
20 *
21 * @since 6
22 * @syscap SystemCapability.Communication.NetStack
23 */
24declare namespace webSocket {
25  /**
26   * Creates a web socket connection.
27   */
28  function createWebSocket(): WebSocket;
29
30  export interface WebSocketRequestOptions {
31    /**
32     * HTTP request header.
33     */
34    header?: Object;
35  }
36
37  export interface WebSocketCloseOptions {
38    /**
39     * Error code.
40     */
41    code?: number;
42    /**
43     * Error cause.
44     */
45    reason?: string;
46  }
47
48  export interface WebSocket {
49    /**
50     * Initiates a WebSocket request to establish a WebSocket connection to a given URL.
51     *
52     * @param url URL for establishing a WebSocket connection.
53     * @param options Optional parameters {@link WebSocketRequestOptions}.
54     * @param callback Returns callback used to return the execution result.
55     * @permission ohos.permission.INTERNET
56     * @throws {BusinessError} 401 - Parameter error.
57     * @throws {BusinessError} 201 - Permission denied.
58     */
59    connect(url: string, callback: AsyncCallback<boolean>): void;
60    connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback<boolean>): void;
61    connect(url: string, options?: WebSocketRequestOptions): Promise<boolean>;
62
63    /**
64     * Sends data through a WebSocket connection.
65     *
66     * @param data Data to send. It can be a string(API 6) or an ArrayBuffer(API 8).
67     * @param callback Returns callback used to return the execution result.
68     * @permission ohos.permission.INTERNET
69     * @throws {BusinessError} 401 - Parameter error.
70     * @throws {BusinessError} 201 - Permission denied.
71     */
72    send(data: string | ArrayBuffer, callback: AsyncCallback<boolean>): void;
73    send(data: string | ArrayBuffer): Promise<boolean>;
74
75    /**
76     * Closes a WebSocket connection.
77     *
78     * @param options Optional parameters {@link WebSocketCloseOptions}.
79     * @param callback Returns callback used to return the execution result.
80     * @permission ohos.permission.INTERNET
81     * @throws {BusinessError} 401 - Parameter error.
82     * @throws {BusinessError} 201 - Permission denied.
83     */
84    close(callback: AsyncCallback<boolean>): void;
85    close(options: WebSocketCloseOptions, callback: AsyncCallback<boolean>): void;
86    close(options?: WebSocketCloseOptions): Promise<boolean>;
87
88    /**
89     * Enables listening for the open events of a WebSocket connection.
90     */
91    on(type: 'open', callback: AsyncCallback<Object>): void;
92
93    /**
94     * Cancels listening for the open events of a WebSocket connection.
95     */
96    off(type: 'open', callback?: AsyncCallback<Object>): void;
97
98    /**
99     * Enables listening for the message events of a WebSocket connection.
100     * data in AsyncCallback can be a string(API 6) or an ArrayBuffer(API 8).
101     */
102    on(type: 'message', callback: AsyncCallback<string | ArrayBuffer>): void;
103
104    /**
105     * Cancels listening for the message events of a WebSocket connection.
106     * data in AsyncCallback can be a string(API 6) or an ArrayBuffer(API 8).
107     */
108    off(type: 'message', callback?: AsyncCallback<string | ArrayBuffer>): void;
109
110    /**
111     * Enables listening for the close events of a WebSocket connection.
112     */
113    on(type: 'close', callback: AsyncCallback<{ code: number, reason: string }>): void;
114
115    /**
116     * Cancels listening for the close events of a WebSocket connection.
117     */
118    off(type: 'close', callback?: AsyncCallback<{ code: number, reason: string }>): void;
119
120    /**
121     * Enables listening for the error events of a WebSocket connection.
122     */
123    on(type: 'error', callback: ErrorCallback): void;
124
125    /**
126     * Cancels listening for the error events of a WebSocket connection.
127     */
128    off(type: 'error', callback?: ErrorCallback): void;
129  }
130}
131
132export default webSocket;