WebSocket is an underlying network protocol that enables you to build other standard
protocols on top of it.
The WebSocket Protocol enables full duplex communication between a client and
a remote server over the Web, and supports transmission of binary data and text strings.
The protocol consists of an opening handshake followed by basic message framing, and is
layered over TCP.
WebSocket programming follows an asynchronous programming model, which
means that as long as a WebSocket connection is open, your application simply listens
for events. Your client does not need to actively poll the server for more information. To
start listening for the events, you simply add callback functions to the WebSocket object.
Alternatively, you can use the addEventListener() DOM method to add event listeners
to your WebSocket objects.
A WebSocket object dispatches four different events:
· Open
· Message
· Error
· Close
As with all web APIs, you can listen for these events using on<eventname> handler
properties, as well as using the addEventListener(); method.
ws.onopen
ws.onmessage
ws.onerror
ws.onclose
e.data instanceof Blob
ws.binaryType = "blob"
WebSocket objects have two methods: send() and close()
Listing 2-12. Waiting for the Open Event Before Sending a Message
// Wait until the open event before calling send().
var ws = new WebSocket("ws://echo.websocket.org")
ws.onopen = function(e) {
ws.send("Initial data");
}
Listing 2-13. Checking the readyState Property for an Open WebSocket
// Handle outgoing data. Send on a WebSocket if that socket is open.
function myEventHandler(data) {
if (ws.readyState === WebSocket.OPEN) {
// The socket is open, so it is ok to send the data.
ws.send(data);
} else {
// Do something else in this case.
//Possibly ignore the data or enqueue it.
}
}
// Send a Blob
var blob = new Blob("blob contents");
ws.send(blob);
// Send an ArrayBuffer
var a = new Uint8Array([8,6,7,5,3,0,9]);
ws.send(a.buffer);
Listing 2-15. Calling the close() Method
// Close the WebSocket connection
ws.close();
You can optionally pass two arguments to the close() method: code (a numerical
status code) and reason (a text string). Passing these arguments transmits information
to the server about why the client closed the connection. We will discuss the status
codes and reasons in greater detail in Chapter 3, when we cover the WebSocket closing
handshake. Listing 2-16 shows an example of calling the close() method with an
argument.
Listing 2-16. Calling the close() Method with a Reason
// Close the WebSocket connection because the session has ended successfully
ws.close(1000, "Closing normally");
Listing 2-16 uses code 1000, which means, as it states in the code, that the
connection is closing normally.
WebSocket Object Attributes
There are several WebSocket Object attributes you can use to provide more information
about the WebSocket object: readyState, bufferedAmount, and protocol.
Table 2-1. readyState Attributes, Values, and Status Descriptions
Attribute Constant Value Status
WebSocket.CONNECTING 0 The connection is in progress but has not been established.
WebSocket.OPEN 1 The connection has been established. Messages can flow between the client and server.
WebSocket.CLOSING 2 The connection is going through the closing handshake.
WebSocket.CLOSED 3 The connection has been closed or could not be opened.
WebSocket Object Attribute: protocol
The protocol attribute is the empty string before the
opening handshake completes and remains an empty string if the server does not choose
one of the protocols offered by the client.