1# WebSocket Connection
2
3## When to Use
4
5You 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.
6
7If an error occurs in any of the preceding processes, the client will receive a callback of the **error** event.
8
9The WebSocket module supports the heartbeat detection mechanism. After a WebSocket connection is established between the client and server, the client sends a ping frame to the server at a specified interval. On receiving the ping frame, the server immediately returns a Pong frame.
10
11## Available APIs
12
13The WebSocket connection function is mainly implemented by the [WebSocket module](../reference/apis-network-kit/js-apis-webSocket.md). To use related APIs, you must declare the **ohos.permission.INTERNET** permission. The following table describes the related APIs.
14
15| API             | Description                                     |
16| ------------------ | ----------------------------------------- |
17| createWebSocket()  | Creates a WebSocket connection.                   |
18| connect()          | Establishes a WebSocket connection to a given URL.      |
19| send()             | Sends data through the WebSocket connection.               |
20| close()            | Closes a WebSocket connection.                       |
21| on(type: 'open')   | Enables listening for **open** events of a WebSocket connection.                 |
22| off(type: 'open')   | Disables listening for **open** events of a WebSocket connection.            |
23| on(type: 'message') | Enables listening for **message** events of a WebSocket connection.     |
24| off(type: 'message') | Disables listening for **message** events of a WebSocket connection.|
25| on(type: 'close')   | Enables listening for **close** events of a WebSocket connection.                |
26| off(type: 'close') | Disables listening for **close** events of a WebSocket connection.               |
27| on(type: 'error')  | Enables listening for **error** events of a WebSocket connection.                |
28| off(type: 'error') | Disables listening for **error** events of a WebSocket connection.            |
29
30## How to Develop
31
321. Import the required webSocket module.
33
342. Create a **WebSocket** object.
35
363. (Optional) Subscribe to WebSocket **open**, **message**, **close**, and **error** events.
37
384. Establish a WebSocket connection to a given URL.
39
405. Close the WebSocket connection if it is no longer needed.
41
42```js
43import { webSocket } from '@kit.NetworkKit';
44import { BusinessError } from '@kit.BasicServicesKit';
45
46let defaultIpAddress = "ws://";
47let ws = webSocket.createWebSocket();
48ws.on('open', (err: BusinessError, value: Object) => {
49  console.log("on open, status:" + JSON.stringify(value));
50  // When receiving the on('open') event, the client can use the send() API to communicate with the server.
51  ws.send("Hello, server!", (err: BusinessError, value: boolean) => {
52    if (!err) {
53      console.log("Message send successfully");
54    } else {
55      console.log("Failed to send the message. Err:" + JSON.stringify(err));
56    }
57  });
58});
59ws.on('message', (err: BusinessError, value: string | ArrayBuffer) => {
60  console.log("on message, message:" + value);
61  // When receiving the `bye` message (the actual message name may differ) from the server, the client proactively disconnects from the server.
62  if (value === 'bye') {
63    ws.close((err: BusinessError, value: boolean) => {
64      if (!err) {
65        console.log("Connection closed successfully");
66      } else {
67        console.log("Failed to close the connection. Err: " + JSON.stringify(err));
68      }
69    });
70  }
71});
72ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => {
73  console.log("on close, code is " + value.code + ", reason is " + value.reason);
74});
75ws.on('error', (err: BusinessError) => {
76  console.log("on error, error:" + JSON.stringify(err));
77});
78ws.connect(defaultIpAddress, (err: BusinessError, value: boolean) => {
79  if (!err) {
80    console.log("Connected successfully");
81  } else {
82    console.log("Connection failed. Err:" + JSON.stringify(err));
83  }
84});
85```
86