mozilla

Revision 74547 of WebSockets reference

  • Revision slug: WebSockets/WebSockets_reference
  • Revision title: WebSockets reference
  • Revision id: 74547
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 18 words removed

Revision Content

{{ IFSummary("content/base/public/nsIWebSocket.idl", "nsISupports", "Scriptable", "6.0", "??? Add brief description of Interface ???", "2.0") }}

{{ draft() }}

Note: As I'm writing the reference, I'm dropping in here some stuff that will be moved later to the client programming guide.

The WebSocket interface enables Web applications to maintain bidirectional communications with server-side processes.

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

The WebSocket 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
);
Parameters
url
The URL to which to connect; this should be the URL to which the WebSocket server will respond.
protocols
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.

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.

Method overview

void close(in optional unsigned long code, in optional DOMString reason);
void send(in DOMString data);

Attributes

Attribute Type Description
binaryType DOMString A string indicating the type of binary data being transmitted by the connection. This should be either "blob" if DOM {{ domxref("Blob") }} objects are being used or "arraybuffer" if ArrayBuffer objects are being used.
bufferedAmount unsigned long The number of bytes of data that have been queued using calls to {{ manch("send") }} but not yet transmitted to the network. This value does not reset to zero when the connection is closed; if you keep calling {{ manch("send") }}, this will continue to climb. Read only.
extensions DOMString The extensions selected by the server. This is currently only the empty string or "deflate-stream", indicating that the data is being compressed. Read only.
onclose {{ domxref("EventListener") }} An event listener to be called when the WebSocket connection's readyState changes to CLOSED. See {{ anch("The close event") }} for details.
onerror {{ domxref("EventListener") }} An event listener to be called when an error occurs. See {{ anch("The error event") }} for details.
onmessage {{ domxref("EventListener") }} An event listener to be called when a message is received from the server. See {{ anch("The message event") }} for details.
onopen {{ domxref("EventListener") }} An event listener to be called when the WebSocket connection's readyState changes to OPEN; this indicates that the connection is ready to send and receive data. See {{ anch("The open event") }} for details.
protocol {{ gecko_minversion_inline("6.0") }} DOMString A string indicating the name of the sub-protocol the server selected; this will be one of the strings specified in the protocols parameter when creating the WebSocket object.
readyState unsigned short The current state of the connection; this is one of the {{ anch("Ready state constants") }}. Read only.
url DOMString The URL as resolved by the constructor. This is always an absolute URL. Read only.

Constants

Ready state constants

These constants are used by the readyState attribute to describe the state of the WebSocket connection.

Constant Value Description
CONNECTING 0 The connection is not yet open.
OPEN 1 The connection is open ready to communicate.
CLOSING 2 The connection is in the process of closing.
CLOSED 3 The connection is closed or couldn't be opened.

Methods

close()

Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.

void close();
Parameters

None.

send()

Transmits data to the server over the WebSocket connection.

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
); 
Parameters
data
A text string to send to the server.
Exceptions thrown
INVALID_STATE_ERR
The connection is not currently OPEN.
SYNTAX_ERR
The data is a string that has unpaired surrogates.
Remarks

{{ gecko_callout_heading("6.0") }}

Gecko's implementation of the send() method differs somewhat from the specification in Gecko 6.0; Gecko returns a boolean indicating whether or not the connection is still open (and, by extension, that the data was successfully queued or transmitted). In addition, at this time, Gecko does not support ArrayBuffer or {{ domxref("Blob") }} data types.

See also

Revision Source

<p>{{ IFSummary("content/base/public/nsIWebSocket.idl", "nsISupports", "Scriptable", "6.0", "??? Add brief description of Interface ???", "2.0") }}</p>
<p>{{ draft() }}</p>
<div class="note"><strong>Note:</strong> As I'm writing the reference, I'm dropping in here some stuff that will be moved later to the client programming guide.</div>
<p>The <code>WebSocket</code> interface enables Web applications to maintain bidirectional communications with server-side processes.</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>The WebSocket 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>
<h6>Parameters</h6>
<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></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>
<h3>Examples</h3>
<p>This simple example creates a new WebSocket, connecting to the server at <span class="nowiki">http://www.example.com/socketserver</span>. 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 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#close()">close</a>(in optional unsigned long code, in optional DOMString reason);</code></td> </tr> <tr> <td><code>void <a href="#send()">send</a>(in DOMString data);</code></td> </tr> </tbody>
</table>
<h2 name="Attributes">Attributes</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>binaryType</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>A string indicating the type of binary data being transmitted by the connection. This should be either "blob" if DOM {{ domxref("Blob") }} objects are being used or "arraybuffer" if <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> objects are being used.</td> </tr> <tr> <td><code>bufferedAmount</code></td> <td><code><a href="/en/unsigned_long" title="en/unsigned long">unsigned long</a></code></td> <td>The number of bytes of data that have been queued using calls to {{ manch("send") }} but not yet transmitted to the network. This value does not reset to zero when the connection is closed; if you keep calling {{ manch("send") }}, this will continue to climb. <strong>Read only.</strong></td> </tr> <tr> <td><code>extensions</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>The extensions selected by the server. This is currently only the empty string or "deflate-stream", indicating that the data is being compressed. <strong>Read only.</strong></td> </tr> <tr> <td><code>onclose</code></td> <td>{{ domxref("EventListener") }}</td> <td>An event listener to be called when the WebSocket connection's <code>readyState</code> changes to <code>CLOSED</code>. See {{ anch("The close event") }} for details.</td> </tr> <tr> <td><code>onerror</code></td> <td>{{ domxref("EventListener") }}</td> <td>An event listener to be called when an error occurs. See {{ anch("The error event") }} for details.</td> </tr> <tr> <td><code>onmessage</code></td> <td>{{ domxref("EventListener") }}</td> <td>An event listener to be called when a message is received from the server. See {{ anch("The message event") }} for details.</td> </tr> <tr> <td><code>onopen</code></td> <td>{{ domxref("EventListener") }}</td> <td>An event listener to be called when the WebSocket connection's <code>readyState</code> changes to <code>OPEN</code>; this indicates that the connection is ready to send and receive data. See {{ anch("The open event") }} for details.</td> </tr> <tr> <td><code>protocol</code> {{ gecko_minversion_inline("6.0") }}</td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>A string indicating the name of the sub-protocol the server selected; this will be one of the strings specified in the <code>protocols</code> parameter when creating the WebSocket object.</td> </tr> <tr> <td><code>readyState</code></td> <td><code><a href="/en/unsigned_short" title="en/unsigned short">unsigned short</a></code></td> <td>The current state of the connection; this is one of the {{ anch("Ready state constants") }}. <strong>Read only.</strong></td> </tr> <tr> <td><code>url</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>The URL as resolved by the constructor. This is always an absolute URL. <strong>Read only.</strong></td> </tr> </tbody>
</table><h2 name="Constants">Constants</h2>
<h3>Ready state constants</h3>
<p>These constants are used by the <code>readyState</code> attribute to describe the state of the WebSocket connection.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Value</td> <td class="header">Description</td> </tr> <tr> <td><code>CONNECTING</code></td> <td><code>0</code></td> <td>The connection is not yet open.</td> </tr> <tr> <td><code>OPEN</code></td> <td><code>1</code></td> <td>The connection is open ready to communicate.</td> </tr> <tr> <td><code>CLOSING</code></td> <td><code>2</code></td> <td>The connection is in the process of closing.</td> </tr> <tr> <td><code>CLOSED</code></td> <td><code>3</code></td> <td>The connection is closed or couldn't be opened.</td> </tr> </tbody>
</table>
<h2 name="Methods">Methods</h2>
<h3 name="close()">close()</h3>
<p>Closes the WebSocket connection or connection attempt, if any. If the connection is already <code>CLOSED</code>, this method does nothing.</p>
<pre class="eval">void close();
</pre>
<h6 name="Parameters">Parameters</h6>
<p>None.</p>
<h3 name="send()">send()</h3>
<p>Transmits data to the server over the WebSocket connection.</p>
<pre class="eval">void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
); 
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>data</code></dt> <dd>A text string to send to the server.</dd>
</dl>
<h6>Exceptions thrown</h6>
<dl> <dt><code>INVALID_STATE_ERR</code></dt> <dd>The connection is not currently <code>OPEN</code>.</dd> <dt><code>SYNTAX_ERR</code></dt> <dd>The data is a string that has unpaired surrogates.</dd>
</dl>
<h6>Remarks</h6>
<div class="geckoVersionNote">
<p>{{ gecko_callout_heading("6.0") }}</p>
<p>Gecko's implementation of the <code>send()</code> method differs somewhat from the specification in Gecko 6.0; Gecko returns a <code>boolean</code> indicating whether or not the connection is still open (and, by extension, that the data was successfully queued or transmitted). In addition, at this time, Gecko does not support <code><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer">ArrayBuffer</a></code> or {{ domxref("Blob") }} data types.</p>
</div><h2 name="See_also">See also</h2>
<ul> <li> <a class=" external" href="http://dev.w3.org/html5/websockets/" title="http://dev.w3.org/html5/websockets/">HTML5: WebSockets</a></li>
</ul>
Revert to this revision