@ohos.net.webSocket (WebSocket Connection)

Provides WebSocket clients and servers for third-party applications to implement bidirectional connections between the client and server.

On the WebSocket client: You can use WebSocket to establish a bidirectional connection between the server and client. Before doing this, you need to use the createWebSocket API to create a WebSocket object and then use the connect API to connect to the server. If the connection is successful, the client will receive a callback of the open event. Then, the client can communicate with the server using the send API. When the server sends a message to the client, the client will receive a callback of the message event. If the connection is no longer needed, the client can call the close API to close the connection. After successful disconnection, the client will receive a callback of the close event. If an error occurs in any of the preceding processes, the client will receive a callback of the error event.

On the WebSocket server: Use the createWebSocketServer method to create a WebSocketServer object, and then use the start method to start the server and listen to the link setup request message from the client. (The API version 23 and later versions support all devices. In earlier versions, only TV devices are supported.) If the connection is successful, the server receives the callback of the connect event. The server can then communicate with the client by using the send API or obtain information about all connected clients by using the listAllConnections API. When the client sends a message to the server, the server receives the callback of the messageReceive event. If the connection is no longer needed, the server can call the close API to close the connection. After successful disconnection, the server will receive a callback of the close event. To stop the service, the server can use the stop API. If an error occurs in any of the preceding processes, the server will receive a callback of the error event.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { webSocket } from '@kit.NetworkKit';

webSocket.createWebSocket

createWebSocket(): WebSocket

Creates a WebSocket object, which provides methods to create or close a WebSocket connection, send data over the connection, and enable or disable listening for the open, close, message, and error events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
WebSocket	A WebSocket object, which contains the connect, send, close, on, or off method.

Example

let ws: webSocket.WebSocket = webSocket.createWebSocket();

WebSocket

Defines a WebSocket object. Before invoking WebSocket APIs, you need to call webSocket.createWebSocket to create a WebSocket object.

connect

connect(url: string, callback: AsyncCallback<boolean>): void

Initiates a WebSocket request to establish a WebSocket connection to a given URL. This API uses an asynchronous callback to return the result.

NOTE

The boolean value returned in the callback indicates only whether the connection request is created successfully. To detect whether the WebSocket connection is successful, you need to subscribe to the open event via on('open') before calling this API.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

NOTE

The URL cannot contain more than 1024 characters. Otherwise, the connection fails. Since API version 15, the maximum length of URLs is changed from 1024 characters to 2048 characters. Since API version 26, the maximum length of URLs is changed from 2048 characters to 8196 characters.

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for establishing a WebSocket connection.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see webSocket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2302001	Websocket url error.
2302002	Websocket certificate file does not exist.
2302003	Websocket connection already exists.
2302998	It is not allowed to access this domain.
2302999	Internal error.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let url = "ws://";
ws.connect(url, (err: BusinessError, value: boolean) => {
  if (!err) {
    console.info("connect success")
  } else {
    console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
  }
});

connect

connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback<boolean>): void

Initiates a WebSocket request to establish a WebSocket connection to a given URL. This API uses an asynchronous callback to return the result.

NOTE

The boolean value returned in the callback indicates only whether the connection request is created successfully. To detect whether the WebSocket connection is successful, you need to subscribe to the open event via on('open') before calling this API.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

NOTE

The URL cannot contain more than 1024 characters. Otherwise, the connection fails. Since API version 15, the maximum length of URLs is changed from 1024 characters to 2048 characters. Since API version 26, the maximum length of URLs is changed from 2048 characters to 8196 characters.

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for establishing a WebSocket connection.
options	WebSocketRequestOptions	Yes	Request options. For details, see WebSocketRequestOptions.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see webSocket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2302001	Websocket url error.
2302002	Websocket certificate file does not exist.
2302003	Websocket connection already exists.
2302998	It is not allowed to access this domain.
2302999	Internal error.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

// Example 1:
let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketRequestOptions | undefined;
if (options !=undefined) {
  options.header = {
     name1: "value1",
     name2: "value2",
     name3: "value3"
  };
  options.caPath = "";
}
let url = "ws://"
ws.connect(url, options, (err: BusinessError, value: Object) => {
  if (!err) {
    console.info("connect success")
  } else {
    console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
  }
});

// Example 2:
let url = "ws://"
let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketRequestOptions = {
  minSupportTlsProtocol: webSocket.TlsProtocol.TLS_V_1_1
};
ws.connect(url, options, (err: BusinessError, value: Object) => {
  if (!err) {
    console.info("connect success")
  } else {
    console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
  }
});

connect

connect(url: string, options?: WebSocketRequestOptions): Promise<boolean>

Establishes a WebSocket connection to a given URL. This API uses a promise to return the result.

NOTE

The boolean value returned in the callback indicates only whether the connection request is created successfully. To detect whether the WebSocket connection is successful, you need to subscribe to the open event via on('open') before calling this API.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

NOTE

The URL cannot contain more than 1024 characters. Otherwise, the connection fails. Since API version 15, the maximum length of URLs is changed from 1024 characters to 2048 characters. Since API version 26, the maximum length of URLs is changed from 2048 characters to 8196 characters.

Parameters

Name	Type	Mandatory	Description
url	string	Yes	URL for establishing a WebSocket connection.
options	WebSocketRequestOptions	No	Request options. For details, see WebSocketRequestOptions.

Return value

Type	Description
Promise<boolean>	Callback used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see webSocket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2302001	Websocket url error.
2302002	Websocket certificate file does not exist.
2302003	Websocket connection already exists.
2302998	It is not allowed to access this domain.
2302999	Internal error.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
let url = "ws://"
let promise = ws.connect(url);
promise.then((value: boolean) => {
  console.info("connect success")
}).catch((err:string) => {
  console.error("connect fail, error:" + JSON.stringify(err))
});

send

send(data: string | ArrayBuffer, callback: AsyncCallback<boolean>): void

Sends data through a WebSocket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Data to send. Only the string type is supported for API version 6 or earlier. Both the string and ArrayBuffer types are supported for API version 8 or later. A maximum of 5,242,864 bytes (that is, 5 x 1024 x 1024 - 16) can be sent. If the data size exceeds the upper limit, error code 401 will be returned.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let url = "ws://"
class OutValue {
  status: number = 0
  message: string = ""
}
ws.connect(url, (err: BusinessError, value: boolean) => {
    if (!err) {
      console.info("connect success")
    } else {
      console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
    }
});
ws.on('open', (err: BusinessError, value: Object) => {
  console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message)
    ws.send("Hello, server!", (err: BusinessError, value: boolean) => {
    if (!err) {
      console.info("send success")
    } else {
      console.error(`send fail. Code: ${err.code}, message: ${err.message}`)
    }
  });
});

NOTE

The send API can be called only after an open event is listened.

send

send(data: string | ArrayBuffer): Promise<boolean>

Sends data through the WebSocket connection. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Data to send. Only the string type is supported for API version 6 or earlier. Both the string and ArrayBuffer types are supported for API version 8 or later. A maximum of 5,242,864 bytes (that is, 5 x 1024 x 1024 - 16) can be sent. If the data size exceeds the upper limit, error code 401 will be returned.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let url = "ws://"
class OutValue {
  status: number = 0
  message: string = ""
}
ws.connect(url, (err: BusinessError, value: boolean) => {
    if (!err) {
      console.info("connect success")
    } else {
      console.error("connect fail. Code: ${err.code}, message: ${err.message}")
    }
});

ws.on('open', (err: BusinessError, value: Object) => {
  console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message)
  let promise = ws.send("Hello, server!");
  promise.then((value: boolean) => {
    console.info("send success")
  }).catch((err:string) => {
    console.error("send fail, error:" + JSON.stringify(err))
  });
});

NOTE

The send API can be called only after an open event is listened.

close

close(callback: AsyncCallback<boolean>): void

Closes the WebSocket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.close((err: BusinessError) => {
  if (!err) {
    console.info("close success")
  } else {
    console.error(`close fail. Code: ${err.code}, message: ${err.message}`)
  }
});

close

close(options: WebSocketCloseOptions, callback: AsyncCallback<boolean>): void

Closes the WebSocket connection based on the options parameter. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	WebSocketCloseOptions	Yes	Request options. For details, see WebSocketCloseOptions.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();

let options: webSocket.WebSocketCloseOptions | undefined;
if (options != undefined) {
    options.code = 1000
    options.reason = "your reason"
}
ws.close(options, (err: BusinessError) => {
    if (!err) {
        console.info("close success")
    } else {
        console.error(`close fail. Code: ${err.code}, message: ${err.message}`)
    }
});

close

close(options?: WebSocketCloseOptions): Promise<boolean>

Closes a WebSocket connection based on the specified options. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	WebSocketCloseOptions	No	Request options. For details, see WebSocketCloseOptions.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketCloseOptions | undefined;
if (options != undefined) {
    options.code = 1000
    options.reason = "your reason"
}
let promise = ws.close();
promise.then((value: boolean) => {
    console.info("close success")
}).catch((err:string) => {
    console.error("close fail, error:" + JSON.stringify(err))
});

on('open')

on(type: 'open', callback: AsyncCallback<Object>): void

Subscribes to WebSocket open events. This API uses an asynchronous callback to return the result. This event indicates whether the WebSocket connection is successful. This API must be called before connect is called to initiate a connection request.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. open: event indicating that a WebSocket connection has been opened.
callback	AsyncCallback<Object>	Yes	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let ws= webSocket.createWebSocket();
class OutValue {
  status: number = 0
  message: string = ""
}
ws.on('open', (err: BusinessError, value: Object) => {
  console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message)
});

off('open')

off(type: 'open', callback?: AsyncCallback<Object>): void

Unsubscribes from WebSocket open events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. open: event indicating that a WebSocket connection has been opened.
callback	AsyncCallback<Object>	No	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
class OutValue {
  status: number = 0
  message: string = ""
}
let callback1 = (err: BusinessError, value: Object) => {
 console.info("on open, status:" + ((value as OutValue).status + ", message:" + (value as OutValue).message))
}
ws.on('open', callback1);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
ws.off('open', callback1);

on('message')

on(type: 'message', callback: AsyncCallback<string | ArrayBuffer>): void

Subscribes to WebSocket server message receiving events. This API uses an asynchronous callback to return the result.

NOTE

The data in AsyncCallback can be in the format of string (API version 6) or ArrayBuffer (API version 8).

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: event indicating that a message has been received from the server.
callback	AsyncCallback<string | ArrayBuffer 8+>	Yes	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.on('message', (err: BusinessError<void>, value: string | ArrayBuffer) => {
  console.info("on message, message:" + value)
});

off('message')

off(type: 'message', callback?: AsyncCallback<string | ArrayBuffer>): void

Unsubscribes from WebSocket server message receiving events. This API uses an asynchronous callback to return the result.

NOTE

The data in AsyncCallback can be in the format of string (API version 6) or ArrayBuffer (API version 8). You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: event indicating that a message has been received from the server.
callback	AsyncCallback<string |ArrayBuffer 8+>	No	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.off('message');

on('close')

on(type: 'close', callback: AsyncCallback<CloseResult>): void

Subscribes to WebSocket close events. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: event indicating that a WebSocket connection has been closed.
callback	AsyncCallback<CloseResult>	Yes	Callback used to return the result. close and reason indicate the error code and error cause for closing the connection, respectively.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => {
  console.info("on close, code is " + value.code + ", reason is " + value.reason)
});

off('close')

off(type: 'close', callback?: AsyncCallback<CloseResult>): void

Unsubscribes from WebSocket close events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: event indicating that a WebSocket connection has been closed.
callback	AsyncCallback<CloseResult>	No	Callback used to return the result. close and reason indicate the error code and error cause for closing the connection, respectively.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.off('close');

on('error')

on(type: 'error', callback: ErrorCallback): void

Subscribes to WebSocket error events. This API uses an asynchronous callback to return the result.

The error code of the error event callback is described as follows: WebSocket is essentially an HTTP protocol upgrade. If the server agrees to the upgrade, the server returns 101. The status code indicates that the protocol is switched from HTTP to WebSocket (the open callback is triggered). If the server rejects the upgrade or other exceptions occur, the server returns 200, indicating that the server only processes the request as a common HTTP request.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: event indicating the WebSocket connection has encountered an error.
callback	ErrorCallback	Yes	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.on('error', (err: BusinessError) => {
  console.error(`on error. Code: ${err.code}, message: ${err.message}`)
});

off('error')

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from WebSocket error events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: event indicating the WebSocket connection has encountered an error.
callback	ErrorCallback	No	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.off('error');

on('dataEnd')¹¹⁺

on(type: 'dataEnd', callback: Callback<void>): void

Subscribes to the WebSocket data receiving end event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. dataEnd: event indicating the data receiving over the WebSocket connection has ended.
callback	Callback<void>	Yes	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.on('dataEnd', () => {
  console.info("on dataEnd")
});

off('dataEnd')¹¹⁺

off(type: 'dataEnd', callback?: Callback<void>): void

Unsubscribes from WebSocket data receiving end events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. dataEnd: event indicating the data receiving over the WebSocket connection has ended.
callback	Callback<void>	No	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.off('dataEnd');

on('headerReceive')¹²⁺

on(type: 'headerReceive', callback: Callback<ResponseHeaders>): void

Subscribes to HTTP response header events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. Event type. The value is headerReceive.
callback	Callback<ResponseHeaders>	Yes	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.on('headerReceive', (data) => {
  console.info("on headerReceive " + JSON.stringify(data))
});

off('headerReceive')¹²⁺

off(type: 'headerReceive', callback?: Callback<ResponseHeaders>): void

Unsubscribes from HTTP response header events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. Event type. The value is headerReceive.
callback	Callback<ResponseHeaders>	No	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.off('headerReceive');

webSocket.createWebSocketServer¹⁹⁺

createWebSocketServer(): WebSocketServer

Creates a WebSocketServer object, which provides methods to start or stop the WebSocketServer service, send data over the connection, close the connection, list all connections, and enable or disable listening for the open, close, message, and error events.

NOTE

Supported on all devices since API version 23. In earlier versions, this method is supported only on TV devices.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
WebSocketServer	WebSocketServer object, which provides the start, listAllConnections, send, close, stop, on, and off methods.

Example

let ws: webSocket.WebSocketServer = webSocket.createWebSocketServer();

WebSocketServer¹⁹⁺

Defines a WebSocketServer object. You need to use webSocket.createWebSocketServer to create a WebSocketServer object before using its methods.

start¹⁹⁺

start(config: WebSocketServerConfig): Promise<boolean>

Starts the WebSocketServer service based on the specified config. This API uses a promise to return the result.

NOTE

You are advised not to listen for the same port when calling this API multiple times.

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
config	WebSocketServerConfig	Yes	Starts the WebSocket server.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes and WebSocket Error Codes.

ID	Error Message
201	Permission denied.
2302002	Websocket certificate file does not exist.
2302004	Can't listen on the given NIC.
2302005	Can't listen on the given Port.
2302007	Websocket port already occupied.
2302999	Websocket other unknown error.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // Listening port
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

send¹⁹⁺

send(data: string | ArrayBuffer, connection: WebSocketConnection): Promise<boolean>

Sends data through the WebSocket connection. This API uses a promise to return the result.

NOTE

The send API can be called only after a connect event is listened.

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Data to send, which can be of the string or ArrayBuffer type. A maximum of 5,242,864 bytes (that is, 5 x 1024 x 1024 - 16) can be sent. If the data size exceeds the upper limit, error code 401 will be returned.
connection	WebSocketConnection	Yes	Client information.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes and WebSocket Error Codes.

ID	Error Message
201	Permission denied.
2302006	websocket connection does not exist.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // Listening port
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.on('connect', async (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
  // Use send() to send data to the client when the on('connect') event is received.
  localServer.send("Hello, I'm server!", connection).then((success: boolean) => {
    if (success) {
      console.info('message send successfully');
    } else {
      console.error('message send failed');
    }
  }).catch((error: BusinessError) => {
    console.error(`message send failed, Code: ${error.code}, message: ${error.message}`);
  });
});

listAllConnections¹⁹⁺

listAllConnections(): WebSocketConnection[]

Obtains information about all clients connected to the server.

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

NOTE

This API is called asynchronously. The await keyword needs to be used to wait until the asynchronous operation is complete, ensuring that information about all clients connected to the server can be correctly obtained.

Return value

Type	Description
WebSocketConnection[]	Information about all clients connected to the server, which is of the string array type.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let connections: webSocket.WebSocketConnection[] = [];
let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // Listening port
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.on('connect', async (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
  try {
    connections = await localServer.listAllConnections();
    if (connections.length === 0) {
      console.info('client list is empty');
    } else {
      console.info(`client list cnt: ${connections.length}, client connections list is: ${connections}`);
    }
  } catch (error) {
    console.error(`Failed to listAllConnections. Code: ${error.code}, message: ${error.message}`);
  }
});

close¹⁹⁺

close(connection: WebSocketConnection, options?: webSocket.WebSocketCloseOptions): Promise<boolean>

Closes a WebSocket connection. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
connection	WebSocketConnection	Yes	Client information, including the IP address and port number.
options	webSocket.WebSocketCloseOptions	No	Optional parameters carried in the request for closing a WebSocket connection. By default, the error code is 200, and the cause is Websocket connect failed.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes and WebSocket Error Codes.

ID	Error Message
201	Permission denied.
2302006	websocket connection does not exist.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // Listening port
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.on('connect', (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
  localServer.close(connection).then((success: boolean) => {
    if (success) {
      console.info('close client successfully');
    } else {
      console.error('close client failed');
    }
  });
});

stop¹⁹⁺

stop(): Promise<boolean>

Stops the WebSocketServer service. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // Listening port
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.stop().then((success: boolean) => {
  if (success) {
    console.info('server stop service successfully');
  } else {
    console.error('server stop service failed');
  }
});

on('connect')¹⁹⁺

on(type: 'connect', callback: Callback<WebSocketConnection>): void

Subscribes to the WebSocketServer connection event (the connection between the client and server is successfully established). This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of connect. Successful calling of onconnect() indicates that a connection is established between the client and server.
callback	Callback<WebSocketConnection>	Yes	Callback used to return the information about connected clients.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.on('connect', (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
});

off('connect')¹⁹⁺

off(type: 'connect', callback?: Callback<WebSocketConnection>): void

Unsubscribes from WebSocketServer connection events (the connection between the client and server is successfully established). This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of connect. Successful calling of offconnect() indicates that listening for connection events is canceled successful.
callback	Callback<WebSocketConnection>	No	Callback used to return the information about connected clients.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('connect');

on('messageReceive')¹⁹⁺

on(type: 'messageReceive', callback: Callback<WebSocketMessage>): void

Subscribes to the WebSocketServer event of receiving client messages. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of messageReceive. Successful calling of onmessageReceive() indicates that a message is received from the client.
callback	Callback<WebSocketMessage>	Yes	Callback used to return the result. clientconnection indicates the client information and data indicates the data message sent by the client.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.on('messageReceive', (message: webSocket.WebSocketMessage) => {
  console.info(`on message received, client: ${message.clientConnection}, data: ${message.data}`);
});

off('messageReceive')¹⁹⁺

off(type: 'messageReceive', callback?: Callback<WebSocketMessage>): void

Unsubscribes from the WebSocketServer event of receiving client messages. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of messageReceive. Successful calling of offmessageReceive() indicates that listening for messageReceive events is canceled successfully.
callback	Callback<WebSocketMessage>	No	Callback used to return the result, which contains: - clientconnection: client information. - data: data sent by the client.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('messageReceive');

on('close')¹⁹⁺

on(type: 'close', callback: ClientConnectionCloseCallback): void

Subscribes to WebSocketServer close events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of close. Successful calling of onclose() indicates that the connection is closed successfully.
callback	ClientConnectionCloseCallback	Yes	Callback used to return the result. close and reason indicate the error code and error cause for closing the connection, respectively.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.on('close', (clientConnection: webSocket.WebSocketConnection, closeReason: webSocket.CloseResult) => {
  console.info(`client close, client: ${clientConnection}, closeReason: Code: ${closeReason.code}, reason: ${closeReason.reason}`);
});

off('close')¹⁹⁺

off(type: 'close', callback?: ClientConnectionCloseCallback): void

Unsubscribes from WebSocketServer close events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of close. Successful calling of offclose() indicates that listening for the close events is canceled successfully.
callback	ClientConnectionCloseCallback	No	Callback used to return the result. close and reason indicate the error code and error cause for closing the connection, respectively.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('close');

on('error')¹⁹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to WebSocketServer error events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of error. Successful calling of onerror() indicates that an error has occurred.
callback	ErrorCallback	Yes	Callback used to return the result.

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let wsServer: webSocket.WebSocketServer = webSocket.createWebSocketServer();
wsServer.on('error', (err: BusinessError) => {
  console.error(`error. Code: ${err.code}, message: ${err.message}`);
});

off('error')¹⁹⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from WebSocketServer error events. This API uses an asynchronous callback to return the result.

NOTE

You can pass the callback of the on function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which has a fixed value of error. Successful calling of offerror() indicates that listening for the error events is canceled successfully.
callback	ErrorCallback	No	Callback used to return the error code (default value: 200).

Example

import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('error');

WebSocketRequestOptions

Defines the optional parameters carried in the request for establishing a WebSocket connection.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
header	Object	No	Yes	Header carrying optional parameters in the request for establishing a WebSocket connection. You can customize the parameter or leave it unspecified. Atomic service API: This API can be used in atomic services since API version 11.
caPath11+	string	No	Yes	Path of CA certificates. If a path is set, the system uses the CA certificates in this path. If a path is not set, the system uses the preset CA certificate, namely, /etc/ssl/certs/cacert.pem. This path is the sandbox mapping path, which can be obtained by using UIAbilityContext APIs. Currently, only text certificates in PEM format are supported.
clientCert11+	ClientCert	No	Yes	Client certificate.
proxy12+	ProxyConfiguration	No	Yes	Proxy configuration. By default, the system network proxy is used.
protocol12+	string	No	Yes	Custom Sec-WebSocket-Protocol field. The default value is "".
skipServerCertVerification20+	boolean	No	Yes	Whether to skip server certificate verification. The value true means to skip server certificate verification, and the value false means the opposite. Default value: false.
pingInterval21+	number	No	Yes	Custom heartbeat detection interval. The default value is 30s. Heartbeat detection is initiated at the specified interval. If the value is set to 0, heartbeat detection is disabled. The maximum value is 30000s, and the minimum value is 0s.
pongTimeout21+	number	No	Yes	Timeout interval for disconnecting a connection after heartbeat detection is initiated. The default value is 30s. If no response is received during the specified interval, the connection is disconnected. The maximum value is 30000s, and the minimum value is 0s. pongTimeout must be less than or equal to pingInterval.
minSupportTlsProtocol26+	TlsProtocol	No	Yes	Custom minimum TLS version supported. For example, if this parameter is set to TLS_V_1_1, the client supports TLS 1.1, TLS 1.2, and TLS 1.3.

ClientCert¹¹⁺

Defines the client certificate type.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
certPath	string	No	No	Path of the certificate file.
keyPath	string	No	No	Path of the certificate key file.
keyPassword	string	No	Yes	Password of the certificate key file. The default value is an empty string.

ProxyConfiguration¹²⁺

type ProxyConfiguration = 'system' | 'no-proxy' | HttpProxy

Represents the HTTP proxy configuration.

System capability: SystemCapability.Communication.NetStack

Type	Description
'system'	The default network proxy is used.
'no-proxy'	No network proxy is used.
HttpProxy	The specified network proxy is used.

WebSocketCloseOptions

Defines the optional parameters carried in the request for closing a WebSocket connection.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
code	number	No	Yes	Error code. Set this parameter based on the actual situation. The value must be a positive integer ranging from 1000 to 1015. If no error code is specified or the input value is not within the preceding range, the code will be set to the default value 1000.
reason	string	No	Yes	Error cause. Set this parameter based on the actual situation. If no reason value is specified, the reason value is set to the default value CLOSE_NORMAL.

CloseResult¹⁰⁺

Represents the result obtained from the close event reported when the WebSocket connection is closed.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
code	number	No	No	Error code for closing the connection.
reason	string	No	No	Error cause for closing the connection.

ResponseHeaders¹²⁺

type ResponseHeaders = { [k: string]: string | string[] | undefined; }

Enumerates the response headers sent by the server.

System capability: SystemCapability.Communication.NetStack

Name	Type	Mandatory	Description
[k:string]	string | string[] | undefined	No	Key-value pairs. The key can be any character string and the value can be any character string, character array, or undefined.

Result Codes for Connection Closing

The error code sent to the server must be a positive integer ranging from 1000 to 1015. You can define the error code as required. If no error code is specified or the input value is not within the preceding range, the error code is set to the default value 1000. The following list is for reference.

System capability: SystemCapability.Communication.NetStack

Value	Description
1000	Normally closed.
1001	Connection closed by the server.
1002	Incorrect protocol.
1003	Data unable to be processed.
1004~1015	Reserved.

HttpProxy¹²⁺

type HttpProxy = connection.HttpProxy

Defines the global HTTP proxy configuration of the network.

System capability: SystemCapability.Communication.NetManager.Core

Type	Description
connection.HttpProxy	The specified network proxy is used.

WebSocketServerConfig¹⁹⁺

Defines the WebSocketServer configuration.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
serverIP	string	No	Yes	IP address of the WebSocketServer. The default value is 0.0.0.0.
serverPort	number	No	No	Port of the WebSocketServer.
serverCert	ServerCert	No	Yes	Certificate information, which includes the paths of the WebSocketServer certificate file and private key file.
protocol	string	No	Yes	Custom protocol.
maxConcurrentClientsNumber	number	No	No	Maximum number of concurrent clients. When the number of concurrent clients reaches the maximum, the server rejects new connections. The default value is 10.
maxConnectionsForOneClient	number	No	No	Maximum number of connections for each client. The default value is 10.

ServerCert¹⁹⁺

Certificate information, which includes the paths of the WebSocketServer certificate file and private key file.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
certPath	string	No	No	Path of the server certificate file.
keyPath	string	No	No	Path of the private key file of the server certificate.

WebSocketMessage¹⁹⁺

Callback used to return the result, which contains:

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
data	string |ArrayBuffer	No	No	Message data sent by the client.
clientConnection	WebSocketConnection	No	No	Client information, including the IP address and port number.

WebSocketConnection¹⁹⁺

Client information, including the IP address and port number.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read Only	Optional	Description
clientIP	string	No	No	IP address of the client.
clientPort	number	No	No	Port number of the client.

ClientConnectionCloseCallback¹⁹⁺

type ClientConnectionCloseCallback = (clientConnection: WebSocketConnection, closeReason: CloseResult) => void

Callback invoked when the WebSocketServer connection is closed.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
clientConnection	WebSocketConnection	Yes	Client information, including the IP address and port number.
closeReason	CloseResult	Yes	Represents the result obtained from the close event reported when the WebSocket connection is closed.

TlsProtocol²⁶⁺

Enumerates the TLS protocol types.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
TLS_V_1_0	0	TLS version 1.0.
TLS_V_1_1	1	TLS version 1.1.
TLS_V_1_2	2	TLS version 1.2.
TLS_V_1_3	3	TLS version 1.3.