Writing WebSocket client applications

  • Revision slug: WebSockets/Writing_WebSocket_client_applications
  • Revision title: Writing WebSocket client applications
  • Revision id: 721
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment more content, still wip; 172 words added

Revision Content

{{ draft() }}

WebSockets is a technology that makes it possible to open an interactive communication session between the user's browser and a server. Using a WebSocket connection, Web applications can perform real-time communication instead of having to poll for changes back and forth.

Availability of WebSockets

The WebSocket API is available to JavaScript code whose scope is either a DOM {{ domxref("Window") }} object or any object implementing {{ domxref("WorkerUtils") }}; that is, you can use it from Web Workers.

Creating a WebSocket object

In order to communicate using the WebSocket protocol, you need to create a WebSocket object; its constructor accepts one required and one optional parameter:

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
url
The URL to which to connect; this should be the URL to which the WebSocket server will respond.
protocols {{ optional_inline() }}
Either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols (for example, you might want one server to be able to handle different types of interactions depending on the specified protocol). If you don't specify a protocol string, an empty string is assumed.

The constructor can throw exceptions:

SECURITY_ERR
The port to which the connection is being attempted is being blocked.

Examples

This simple example creates a new WebSocket, connecting to the server at http://www.example.com/socketserver. It specifies a protocol of "my-custom-protocol".

var mySocket = new WebSocket("http://www.example.com/socketserver", "my-custom-protocol");

On return, mySocket's readyState is CONNECTING. The readyState will become OPEN once the connection is ready to transfer data.

If you want to open a connection and are flexible about the protocols you support, you can specify an array of protocols:

var mySocket = new WebSocket("http://www.example.com/socketserver", ["protocol1", "protocol2"]);

Once the connection is established (that is, readyState is OPEN), the protocol attribute will tell you which protocol the server selected.

Sending data to the server

Once you've opened your connection, you can begin transmitting data to the server. To do this, simply call the WebSocket object's send() method for each message you want to send:

mySocket.send("Here's some text that the server is urgently awaiting!"); 

You can send strings, {{ domxref("Blob") }}s, or ArrayBuffers.

Note: Firefox currently only supports sending strings.

Receiving messages from the server

WebSockets is an event-driven API; when messages are received, a "message" event is delivered to the onmessage function. To begin listening for incoming data, you can do something like this:

mySocket.onmessage = function(e) {
  console.log(e.data);
}

Closing the connection

When you've finished using the WebSocket connection, call the WebSocket method close():

mySocket.close();

Revision Source

<p>{{ draft() }}</p>
<p>WebSockets is a technology that makes it possible to open an interactive communication session between the user's browser and a server. Using a WebSocket connection, Web applications can perform real-time communication instead of having to poll for changes back and forth.</p>
<h2>Availability of WebSockets</h2>
<p>The WebSocket API is available to JavaScript code whose scope is either a DOM {{ domxref("Window") }} object or any object implementing {{ domxref("WorkerUtils") }}; that is, you can use it from Web Workers.</p>
<h2>Creating a WebSocket object</h2>
<p>In order to communicate using the WebSocket protocol, you need to create a <a href="/en/WebSockets/WebSockets_reference/WebSocket" title="en/WebSockets/WebSockets reference/WebSocket"><code>WebSocket</code></a> object; its constructor accepts one required and one optional parameter:</p>
<pre>WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
</pre>
<dl> <dt><code>url</code></dt> <dd>The URL to which to connect; this should be the URL to which the WebSocket server will respond.</dd> <dt><code>protocols</code> {{ optional_inline() }}</dt> <dd>Either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols (for example, you might want one server to be able to handle different types of interactions depending on the specified <code>protocol</code>). If you don't specify a protocol string, an empty string is assumed.</dd>
</dl>
<p>The constructor can throw exceptions:</p>
<dl> <dt><code>SECURITY_ERR</code></dt> <dd>The port to which the connection is being attempted is being blocked.</dd>
</dl>
<dl> <h3>Examples</h3> <p>This simple example creates a new WebSocket, connecting to the server at <code><span class="nowiki">http://www.example.com/socketserver</span></code>. It specifies a protocol of "my-custom-protocol".</p> <pre>var mySocket = new WebSocket("<span class="plain">http://www.example.com/socketserver</span>", "my-custom-protocol");
</pre> <p>On return, <code>mySocket</code>'s <code>readyState</code> is <code>CONNECTING</code>. The <code>readyState</code> will become <code>OPEN</code> once the connection is ready to transfer data.</p> <p>If you want to open a connection and are flexible about the protocols you support, you can specify an array of protocols:</p> <pre>var mySocket = new WebSocket("<span class="plain">http://www.example.com/socketserver</span>", ["protocol1", "protocol2"]);
</pre> <p>Once the connection is established (that is, <code>readyState</code> is <code>OPEN</code>), the <code>protocol</code> attribute will tell you which protocol the server selected.</p> <h2>Sending data to the server</h2> <p>Once you've opened your connection, you can begin transmitting data to the server. To do this, simply call the <code>WebSocket</code> object's <a href="/en/WebSockets/WebSockets_reference/WebSocket#send()" title="en/WebSockets/WebSockets reference/WebSocket#send()"><code>send()</code></a> method for each message you want to send:</p> <pre>mySocket.send("Here's some text that the server is urgently awaiting!"); 
</pre> <p>You can send strings, {{ domxref("Blob") }}s, or <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a>s.</p> <div class="note"><strong>Note:</strong> Firefox currently only supports sending strings.</div> <h2>Receiving messages from the server</h2> <p>WebSockets is an event-driven API; when messages are received, a "message" event is delivered to the <code>onmessage</code> function. To begin listening for incoming data, you can do something like this:</p> <pre class="brush: js">mySocket.onmessage = function(e) {
  console.log(e.data);
}
</pre> <h2>Closing the connection</h2> <p>When you've finished using the WebSocket connection, call the WebSocket method <a href="/en/WebSockets/WebSockets_reference/WebSocket#close()" title="en/WebSockets/WebSockets reference/WebSocket#close()"><code>close()</code></a>:</p> <pre>mySocket.close();
</pre></dl>
Revert to this revision