1/* 2 * Copyright (c) 2022-2023 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 type { AsyncCallback, ErrorCallback } from './@ohos.base'; 17 18/** 19 * Provides WebSocket APIs. 20 * @namespace webSocket 21 * @syscap SystemCapability.Communication.NetStack 22 * @since 6 23 */ 24/** 25 * Provides WebSocket APIs. 26 * @namespace webSocket 27 * @syscap SystemCapability.Communication.NetStack 28 * @crossplatform 29 * @since 10 30 */ 31declare namespace webSocket { 32 /** 33 * Creates a web socket connection. 34 * @returns { WebSocket } the WebSocket of the createWebSocket. 35 * @syscap SystemCapability.Communication.NetStack 36 * @since 6 37 */ 38 /** 39 * Creates a web socket connection. 40 * @returns { WebSocket } the WebSocket of the createWebSocket. 41 * @syscap SystemCapability.Communication.NetStack 42 * @crossplatform 43 * @since 10 44 */ 45 function createWebSocket(): WebSocket; 46 47 /** 48 * Defines the optional parameters carried in the request for establishing a WebSocket connection. 49 * @interface WebSocketRequestOptions 50 * @syscap SystemCapability.Communication.NetStack 51 * @since 6 52 */ 53 /** 54 * Defines the optional parameters carried in the request for establishing a WebSocket connection. 55 * @interface WebSocketRequestOptions 56 * @syscap SystemCapability.Communication.NetStack 57 * @crossplatform 58 * @since 10 59 */ 60 export interface WebSocketRequestOptions { 61 /** 62 * HTTP request header. 63 * @type {?Object} 64 * @syscap SystemCapability.Communication.NetStack 65 * @since 6 66 */ 67 /** 68 * HTTP request header. 69 * @type {?Object} 70 * @syscap SystemCapability.Communication.NetStack 71 * @crossplatform 72 * @since 10 73 */ 74 header?: Object; 75 } 76 77 /** 78 * Defines the optional parameters carried in the request for closing a WebSocket connection. 79 * @interface WebSocketCloseOptions 80 * @syscap SystemCapability.Communication.NetStack 81 * @since 6 82 */ 83 /** 84 * Defines the optional parameters carried in the request for closing a WebSocket connection. 85 * @interface WebSocketCloseOptions 86 * @syscap SystemCapability.Communication.NetStack 87 * @crossplatform 88 * @since 10 89 */ 90 export interface WebSocketCloseOptions { 91 /** 92 * Error code. 93 * @type {?number} 94 * @syscap SystemCapability.Communication.NetStack 95 * @since 6 96 */ 97 /** 98 * Error code. 99 * @type {?number} 100 * @syscap SystemCapability.Communication.NetStack 101 * @crossplatform 102 * @since 10 103 */ 104 code?: number; 105 /** 106 * Error cause. 107 * @type {?string} 108 * @syscap SystemCapability.Communication.NetStack 109 * @since 6 110 */ 111 /** 112 * Error cause. 113 * @type {?string} 114 * @syscap SystemCapability.Communication.NetStack 115 * @crossplatform 116 * @since 10 117 */ 118 reason?: string; 119 } 120 121 /** 122 * The result for closing a WebSocket connection. 123 * @interface CloseResult 124 * @syscap SystemCapability.Communication.NetStack 125 * @crossplatform 126 * @since 10 127 */ 128 export interface CloseResult { 129 /** 130 * Error code. 131 * @type {number} 132 * @syscap SystemCapability.Communication.NetStack 133 * @crossplatform 134 * @since 10 135 */ 136 code: number; 137 /** 138 * Error cause. 139 * @type {string} 140 * @syscap SystemCapability.Communication.NetStack 141 * @crossplatform 142 * @since 10 143 */ 144 reason: string; 145 } 146 147 /** 148 * <p>Defines a WebSocket object. Before invoking WebSocket APIs, 149 * you need to call webSocket.createWebSocket to create a WebSocket object.</p> 150 * @interface WebSocket 151 * @syscap SystemCapability.Communication.NetStack 152 * @since 6 153 */ 154 /** 155 * <p>Defines a WebSocket object. Before invoking WebSocket APIs, 156 * you need to call webSocket.createWebSocket to create a WebSocket object.</p> 157 * @interface WebSocket 158 * @syscap SystemCapability.Communication.NetStack 159 * @crossplatform 160 * @since 10 161 */ 162 export interface WebSocket { 163 /** 164 * Initiates a WebSocket request to establish a WebSocket connection to a given URL. 165 * @permission ohos.permission.INTERNET 166 * @param { string } url - URL for establishing a WebSocket connection. 167 * @param { AsyncCallback<boolean> } callback - the callback of connect. 168 * @throws { BusinessError } 401 - Parameter error. 169 * @throws { BusinessError } 201 - Permission denied. 170 * @syscap SystemCapability.Communication.NetStack 171 * @since 6 172 */ 173 /** 174 * Initiates a WebSocket request to establish a WebSocket connection to a given URL. 175 * @permission ohos.permission.INTERNET 176 * @param { string } url URL for establishing a WebSocket connection. 177 * @param { AsyncCallback<boolean> } callback - the callback of connect. 178 * @throws { BusinessError } 401 - Parameter error. 179 * @throws { BusinessError } 201 - Permission denied. 180 * @syscap SystemCapability.Communication.NetStack 181 * @crossplatform 182 * @since 10 183 */ 184 connect(url: string, callback: AsyncCallback<boolean>): void; 185 186 /** 187 * Initiates a WebSocket request to establish a WebSocket connection to a given URL. 188 * @permission ohos.permission.INTERNET 189 * @param { string } url URL for establishing a WebSocket connection. 190 * @param { WebSocketRequestOptions } options - Optional parameters {@link WebSocketRequestOptions}. 191 * @param { AsyncCallback<boolean> } callback - the callback of connect. 192 * @throws { BusinessError } 401 - Parameter error. 193 * @throws { BusinessError } 201 - Permission denied. 194 * @syscap SystemCapability.Communication.NetStack 195 * @since 6 196 */ 197 /** 198 * Initiates a WebSocket request to establish a WebSocket connection to a given URL. 199 * @permission ohos.permission.INTERNET 200 * @param { string } url URL for establishing a WebSocket connection. 201 * @param { WebSocketRequestOptions } options - Optional parameters {@link WebSocketRequestOptions}. 202 * @param { AsyncCallback<boolean> } callback - the callback of connect. 203 * @throws { BusinessError } 401 - Parameter error. 204 * @throws { BusinessError } 201 - Permission denied. 205 * @syscap SystemCapability.Communication.NetStack 206 * @crossplatform 207 * @since 10 208 */ 209 connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback<boolean>): void; 210 211 /** 212 * Initiates a WebSocket request to establish a WebSocket connection to a given URL. 213 * @permission ohos.permission.INTERNET 214 * @param { string } url URL for establishing a WebSocket connection. 215 * @param { WebSocketRequestOptions } options - Optional parameters {@link WebSocketRequestOptions}. 216 * @returns { Promise<boolean> } The promise returned by the function. 217 * @throws { BusinessError } 401 - Parameter error. 218 * @throws { BusinessError } 201 - Permission denied. 219 * @syscap SystemCapability.Communication.NetStack 220 * @since 6 221 */ 222 /** 223 * Initiates a WebSocket request to establish a WebSocket connection to a given URL. 224 * @permission ohos.permission.INTERNET 225 * @param { string } url URL for establishing a WebSocket connection. 226 * @param { WebSocketRequestOptions } options - Optional parameters {@link WebSocketRequestOptions}. 227 * @returns { Promise<boolean> } The promise returned by the function. 228 * @throws { BusinessError } 401 - Parameter error. 229 * @throws { BusinessError } 201 - Permission denied. 230 * @syscap SystemCapability.Communication.NetStack 231 * @crossplatform 232 * @since 10 233 */ 234 connect(url: string, options?: WebSocketRequestOptions): Promise<boolean>; 235 236 /** 237 * Sends data through a WebSocket connection. 238 * @permission ohos.permission.INTERNET 239 * @param { string | ArrayBuffer } data - Data to send. It can be a string(API 6) or an ArrayBuffer(API 8). 240 * @param { AsyncCallback<boolean> } callback - the callback of send. 241 * @throws { BusinessError } 401 - Parameter error. 242 * @throws { BusinessError } 201 - Permission denied. 243 * @syscap SystemCapability.Communication.NetStack 244 * @since 6 245 */ 246 /** 247 * Sends data through a WebSocket connection. 248 * @permission ohos.permission.INTERNET 249 * @param { string | ArrayBuffer } data - Data to send. It can be a string(API 6) or an ArrayBuffer(API 8). 250 * @param { AsyncCallback<boolean> } callback - the callback of send. 251 * @throws { BusinessError } 401 - Parameter error. 252 * @throws { BusinessError } 201 - Permission denied. 253 * @syscap SystemCapability.Communication.NetStack 254 * @crossplatform 255 * @since 10 256 */ 257 send(data: string | ArrayBuffer, callback: AsyncCallback<boolean>): void; 258 259 /** 260 * Sends data through a WebSocket connection. 261 * @permission ohos.permission.INTERNET 262 * @param { string | ArrayBuffer } data - Data to send. It can be a string(API 6) or an ArrayBuffer(API 8). 263 * @returns { Promise<boolean> } The promise returned by the function. 264 * @throws { BusinessError } 401 - Parameter error. 265 * @throws { BusinessError } 201 - Permission denied. 266 * @syscap SystemCapability.Communication.NetStack 267 * @since 6 268 */ 269 /** 270 * Sends data through a WebSocket connection. 271 * @permission ohos.permission.INTERNET 272 * @param { string | ArrayBuffer } data - Data to send. It can be a string(API 6) or an ArrayBuffer(API 8). 273 * @returns { Promise<boolean> } The promise returned by the function. 274 * @throws { BusinessError } 401 - Parameter error. 275 * @throws { BusinessError } 201 - Permission denied. 276 * @syscap SystemCapability.Communication.NetStack 277 * @crossplatform 278 * @since 10 279 */ 280 send(data: string | ArrayBuffer): Promise<boolean>; 281 282 /** 283 * Closes a WebSocket connection. 284 * @permission ohos.permission.INTERNET 285 * @param { AsyncCallback<boolean> } callback - the callback of close. 286 * @throws { BusinessError } 401 - Parameter error. 287 * @throws { BusinessError } 201 - Permission denied. 288 * @syscap SystemCapability.Communication.NetStack 289 * @since 6 290 */ 291 /** 292 * Closes a WebSocket connection. 293 * @permission ohos.permission.INTERNET 294 * @param { AsyncCallback<boolean> } callback - the callback of close. 295 * @throws { BusinessError } 401 - Parameter error. 296 * @throws { BusinessError } 201 - Permission denied. 297 * @syscap SystemCapability.Communication.NetStack 298 * @crossplatform 299 * @since 10 300 */ 301 close(callback: AsyncCallback<boolean>): void; 302 303 /** 304 * Closes a WebSocket connection. 305 * @permission ohos.permission.INTERNET 306 * @param { WebSocketCloseOptions } options - Optional parameters {@link WebSocketCloseOptions}. 307 * @param { AsyncCallback<boolean> } callback - the callback of close. 308 * @throws { BusinessError } 401 - Parameter error. 309 * @throws { BusinessError } 201 - Permission denied. 310 * @syscap SystemCapability.Communication.NetStack 311 * @since 6 312 */ 313 /** 314 * Closes a WebSocket connection. 315 * @permission ohos.permission.INTERNET 316 * @param { WebSocketCloseOptions } options - Optional parameters {@link WebSocketCloseOptions}. 317 * @param { AsyncCallback<boolean> } callback - the callback of close. 318 * @throws { BusinessError } 401 - Parameter error. 319 * @throws { BusinessError } 201 - Permission denied. 320 * @syscap SystemCapability.Communication.NetStack 321 * @crossplatform 322 * @since 10 323 */ 324 close(options: WebSocketCloseOptions, callback: AsyncCallback<boolean>): void; 325 326 /** 327 * Closes a WebSocket connection. 328 * @permission ohos.permission.INTERNET 329 * @param { WebSocketCloseOptions } options - Optional parameters {@link WebSocketCloseOptions}. 330 * @returns { Promise<boolean> } The promise returned by the function. 331 * @throws { BusinessError } 401 - Parameter error. 332 * @throws { BusinessError } 201 - Permission denied. 333 * @syscap SystemCapability.Communication.NetStack 334 * @since 6 335 */ 336 /** 337 * Closes a WebSocket connection. 338 * @permission ohos.permission.INTERNET 339 * @param { WebSocketCloseOptions } options - Optional parameters {@link WebSocketCloseOptions}. 340 * @returns { Promise<boolean> } The promise returned by the function. 341 * @throws { BusinessError } 401 - Parameter error. 342 * @throws { BusinessError } 201 - Permission denied. 343 * @syscap SystemCapability.Communication.NetStack 344 * @crossplatform 345 * @since 10 346 */ 347 close(options?: WebSocketCloseOptions): Promise<boolean>; 348 349 /** 350 * Enables listening for the open events of a WebSocket connection. 351 * @param { 'open' } type - event indicating that a WebSocket connection has been opened. 352 * @param { AsyncCallback<Object> } callback - the callback used to return the result. 353 * @syscap SystemCapability.Communication.NetStack 354 * @since 6 355 */ 356 /** 357 * Enables listening for the open events of a WebSocket connection. 358 * @param { 'open' } type - event indicating that a WebSocket connection has been opened. 359 * @param { AsyncCallback<Object> } callback - the callback used to return the result. 360 * @syscap SystemCapability.Communication.NetStack 361 * @crossplatform 362 * @since 10 363 */ 364 on(type: 'open', callback: AsyncCallback<Object>): void; 365 366 /** 367 * Cancels listening for the open events of a WebSocket connection. 368 * @param { 'open' } type - event indicating that a WebSocket connection has been opened. 369 * @param { AsyncCallback<Object> } callback - the callback used to return the result. 370 * @syscap SystemCapability.Communication.NetStack 371 * @since 6 372 */ 373 /** 374 * Cancels listening for the open events of a WebSocket connection. 375 * @param { 'open' } type - event indicating that a WebSocket connection has been opened. 376 * @param { AsyncCallback<Object> } callback the callback used to return the result. 377 * @syscap SystemCapability.Communication.NetStack 378 * @crossplatform 379 * @since 10 380 */ 381 off(type: 'open', callback?: AsyncCallback<Object>): void; 382 383 /** 384 * Enables listening for the message events of a WebSocket connection. 385 * data in AsyncCallback can be a string(API 6) or an ArrayBuffer(API 8). 386 * @param { 'message' } type - event indicating that a message has been received from the server. 387 * @param { AsyncCallback<string | ArrayBuffer> } callback - the callback used to return the result. 388 * @syscap SystemCapability.Communication.NetStack 389 * @since 6 390 */ 391 /** 392 * Enables listening for the message events of a WebSocket connection. 393 * data in AsyncCallback can be a string(API 6) or an ArrayBuffer(API 8). 394 * @param { 'message' } type - event indicating that a message has been received from the server. 395 * @param { AsyncCallback<string | ArrayBuffer> } callback - the callback used to return the result. 396 * @syscap SystemCapability.Communication.NetStack 397 * @crossplatform 398 * @since 10 399 */ 400 on(type: 'message', callback: AsyncCallback<string | ArrayBuffer>): void; 401 402 /** 403 * Cancels listening for the message events of a WebSocket connection. 404 * data in AsyncCallback can be a string(API 6) or an ArrayBuffer(API 8). 405 * @param { 'message' } type - event indicating that a message has been received from the server. 406 * @param { AsyncCallback<string | ArrayBuffer> } callback - the callback used to return the result. 407 * @syscap SystemCapability.Communication.NetStack 408 * @since 6 409 */ 410 /** 411 * Cancels listening for the message events of a WebSocket connection. 412 * data in AsyncCallback can be a string(API 6) or an ArrayBuffer(API 8). 413 * @param { 'message' } type - event indicating that a message has been received from the server. 414 * @param { AsyncCallback<string | ArrayBuffer> } callback - the callback used to return the result. 415 * @syscap SystemCapability.Communication.NetStack 416 * @crossplatform 417 * @since 10 418 */ 419 off(type: 'message', callback?: AsyncCallback<string | ArrayBuffer>): void; 420 421 /** 422 * Enables listening for the close events of a WebSocket connection. 423 * @param { 'close' } type - event indicating that a WebSocket connection has been closed. 424 * @param { AsyncCallback<CloseResult> } callback - the callback used to return the result. 425 * <br>close indicates the close error code and reason indicates the error code description. 426 * @syscap SystemCapability.Communication.NetStack 427 * @since 6 428 */ 429 /** 430 * Enables listening for the close events of a WebSocket connection. 431 * @param { 'close' } type - event indicating that a WebSocket connection has been closed. 432 * @param { AsyncCallback<CloseResult> } callback - the callback used to return the result. 433 * <br>close indicates the close error code and reason indicates the error code description. 434 * @syscap SystemCapability.Communication.NetStack 435 * @crossplatform 436 * @since 10 437 */ 438 on(type: 'close', callback: AsyncCallback<CloseResult>): void; 439 440 /** 441 * Cancels listening for the close events of a WebSocket connection. 442 * @param { 'close' } type - event indicating that a WebSocket connection has been closed. 443 * @param { AsyncCallback<CloseResult> } callback - the callback used to return the result. 444 * <br>close indicates the close error code and reason indicates the error code description. 445 * @syscap SystemCapability.Communication.NetStack 446 * @since 6 447 */ 448 /** 449 * Cancels listening for the close events of a WebSocket connection. 450 * @param { 'close' } type - event indicating that a WebSocket connection has been closed. 451 * @param { AsyncCallback<CloseResult> } callback - the callback used to return the result. 452 * <br>close indicates the close error code and reason indicates the error code description. 453 * @syscap SystemCapability.Communication.NetStack 454 * @crossplatform 455 * @since 10 456 */ 457 off(type: 'close', callback?: AsyncCallback<CloseResult>): void; 458 459 /** 460 * Enables listening for the error events of a WebSocket connection. 461 * @param { 'error' } type - event indicating the WebSocket connection has encountered an error. 462 * @param { ErrorCallback } callback - the callback used to return the result. 463 * @syscap SystemCapability.Communication.NetStack 464 * @since 6 465 */ 466 /** 467 * Enables listening for the error events of a WebSocket connection. 468 * @param { 'error' } type - event indicating the WebSocket connection has encountered an error. 469 * @param { ErrorCallback } callback - the callback used to return the result. 470 * @syscap SystemCapability.Communication.NetStack 471 * @crossplatform 472 * @since 10 473 */ 474 on(type: 'error', callback: ErrorCallback): void; 475 476 /** 477 * Cancels listening for the error events of a WebSocket connection. 478 * @param { 'error' } type - event indicating the WebSocket connection has encountered an error. 479 * @param { ErrorCallback } callback - the callback used to return the result. 480 * @syscap SystemCapability.Communication.NetStack 481 * @since 6 482 */ 483 /** 484 * Cancels listening for the error events of a WebSocket connection. 485 * @param { 'error' } type - event indicating the WebSocket connection has encountered an error. 486 * @param { ErrorCallback } callback - the callback used to return the result. 487 * @syscap SystemCapability.Communication.NetStack 488 * @crossplatform 489 * @since 10 490 */ 491 off(type: 'error', callback?: ErrorCallback): void; 492 } 493} 494 495export default webSocket;