# @ohos.net.webSocket (WebSocket Connection)

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.

You can use WebSocket to establish a bidirectional connection between a server and a 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 client no longer needs this connection, it can call the close API to disconnect from the server. Then, 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.

Modules to Import

import webSocket from '@ohos.net.webSocket';

Examples

import webSocket from '@ohos.net.webSocket';

let defaultIpAddress = "ws://";
let ws = webSocket.createWebSocket();
ws.on('open', (err, value) => {
  if (err != undefined) {
    console.log(JSON.stringify(err))
    return
  }
  console.log("on open, status:" + value['status'] + ", message:" + value['message']);
  // When receiving the on('open') event, the client can use the send() API to communicate with the server.
  ws.send("Hello, server!", (err, value) => {
    if (!err) {
      console.log("send success");
    } else {
      console.log("send fail, err:" + JSON.stringify(err));
    }
  });
});
ws.on('message', (err, value) => {
  console.log("on message, message:" + value);
  // When receiving the `bye` message (the actual message name may differ) from the server, the client proactively disconnects from the server.
  if (value === 'bye') {
    ws.close((err, value) => {
      if (!err) {
        console.log("close success");
      } else {
        console.log("close fail, err is " + JSON.stringify(err));
      }
    });
  }
});
ws.on('close', (err, value) => {
  console.log("on close, code is " + value.code + ", reason is " + value.reason);
});
ws.on('error', (err) => {
  console.log("on error, error:" + JSON.stringify(err));
});
ws.connect(defaultIpAddress, (err, value) => {
  if (!err) {
    console.log("connect success");
  } else {
    console.log("connect fail, err:" + JSON.stringify(err));
  }
});

webSocket.createWebSocket

createWebSocket(): WebSocket

Creates a WebSocket connection. You can use this API to create or close a WebSocket connection, send data over it, or enable or disable listening for the open, close, message, and error events.

System capability: SystemCapability.Communication.NetStack

Return value

Example

let ws = 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 You can listen to error events to obtain the operation result. If an error occurs, the error code 200 will be returned.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

Example

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err, value) => {
  if (!err) {
    console.log("connect success");
  } else {
    console.log("connect fail, err:" + JSON.stringify(err))
  }
});

connect

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

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

NOTE You can listen to error events to obtain the operation result. If an error occurs, the error code 200 will be returned.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

Example

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, {
  header: {
    "key": "value",
    "key2": "value2"
  }
}, (err, value) => {
  if (!err) {
    console.log("connect success");
  } else {
    console.log("connect fail, err:" + JSON.stringify(err))
  }
});

connect

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

Initiates a WebSocket request carrying specified options to establish a WebSocket connection to a given URL. This API uses a promise to return the result.

NOTE You can listen to error events to obtain the operation result. If an error occurs, the error code 200 will be returned.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

Example

let ws = webSocket.createWebSocket();
let url = "ws://"
let promise = ws.connect(url);
promise.then((value) => {
  console.log("connect success")
}).catch((err) => {
  console.log("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

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

Example

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err, value) => {
  ws.send("Hello, server!", (err, value) => {
    if (!err) {
      console.log("send success");
    } else {
      console.log("send fail, err:" + JSON.stringify(err))
    }
  });
});

send

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

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

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

Example

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err, value) => {
  let promise = ws.send("Hello, server!");
  promise.then((value) => {
    console.log("send success")
  }).catch((err) => {
    console.log("send fail, error:" + JSON.stringify(err))
  });
});

close

close(callback: AsyncCallback<boolean>): void

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

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

Example

let ws = webSocket.createWebSocket();
ws.close((err, value) => {
  if (!err) {
    console.log("close success")
  } else {
    console.log("close fail, err is " + JSON.stringify(err))
  }
});

close

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

Closes a WebSocket connection carrying specified options such as code and reason. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Error codes

Example

let ws = webSocket.createWebSocket();
ws.close({
  code: 1000,
  reason: "your reason"
}, (err, value) => {
  if (!err) {
    console.log("close success")
  } else {
    console.log("close fail, err is " + JSON.stringify(err))
  }
});

close

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

Closes a WebSocket connection carrying specified options such as code and reason. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Return value

Error codes

Example

let ws = webSocket.createWebSocket();
let promise = ws.close({
  code: 1000,
  reason: "your reason"
});
promise.then((value) => {
  console.log("close success")
}).catch((err) => {
  console.log("close fail, err is " + JSON.stringify(err))
});

on('open')

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

Enables listening for the open events of a WebSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

let ws = webSocket.createWebSocket();
ws.on('open', (err, value) => {
  console.log("on open, status:" + value['status'] + ", message:" + value['message']);
});

off('open')

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

Disables listening for the open events of a WebSocket connection. 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

Example

let ws = webSocket.createWebSocket();
let callback1 = (err, value) => {
  console.log("on open, status:" + value['status'] + ", message:" + value['message']);
}
ws.on('open', callback1);
// You can pass the callback of the on function to cancel listening for a certain type of callback. If you do not pass the callback, you will cancel listening for all callbacks.
ws.off('open', callback1);

on('message')

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

Enables listening for the message events of a WebSocket connection. This API uses an asynchronous callback to return the result. The maximum length of each message is 4 KB. If the length exceeds 4 KB, the message is automatically fragmented.

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

System capability: SystemCapability.Communication.NetStack

Parameters

Example

let ws = webSocket.createWebSocket();
ws.on('message', (err, value) => {
  console.log("on message, message:" + value);
});

off('message')

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

Disables listening for the message events of a WebSocket connection. This API uses an asynchronous callback to return the result. The maximum length of each message is 4 KB. If the length exceeds 4 KB, the message is automatically fragmented.

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.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

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

on('close')

on(type: 'close', callback: AsyncCallback<{ code: number, reason: string }>): void

Enables listening for the close events of a WebSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

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

off('close')

off(type: 'close', callback?: AsyncCallback<{ code: number, reason: string }>): void

Disables listening for the close events of a WebSocket connection. 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

Example

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

on('error')

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

Enables listening for the error events of a WebSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Example

let ws = webSocket.createWebSocket();
ws.on('error', (err) => {
  console.log("on error, error:" + JSON.stringify(err))
});

off('error')

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

Disables listening for the error events of a WebSocket connection. 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

Example

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

WebSocketRequestOptions

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

System capability: SystemCapability.Communication.NetStack

WebSocketCloseOptions

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

System capability: SystemCapability.Communication.NetStack

Result Codes for Closing a WebSocket Connection

You can customize the result codes sent to the server. The result codes in the following table are for reference only.

System capability: SystemCapability.Communication.NetStack