Revision 752533 of WebSocket

<p>{{APIRef("Web Sockets API")}}{{ SeeCompatTable() }}</p>

<p>The <code>WebSocket</code> object provides the API&nbsp;for creating and managing a <a href="/en/WebSockets" title="en/WebSockets">WebSocket</a> connection to a server, as well as for sending and receiving data on the connection.</p>

<p>The WebSocket constructor accepts one required and one optional parameter:</p>

<pre>
WebSocket WebSocket(
&nbsp; in DOMString url,
&nbsp; in optional DOMString protocols
);

WebSocket WebSocket(
&nbsp; in DOMString url,
&nbsp; in optional DOMString[] protocols
);
</pre>

<dl>
 <dt><code>url</code></dt>
 <dd>The URL&nbsp;to which to connect; this should be the URL&nbsp;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>
</dl>

<h2 id="Method_overview" 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 id="Attributes" 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>{{ DOMXref("DOMString") }}</td>
   <td>A string indicating the type of binary data being transmitted by the connection. This should be either "blob"&nbsp;if DOM&nbsp;{{ domxref("Blob") }}&nbsp;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>{{ DOMXref("DOMString") }}</td>
   <td>The extensions selected by the server. This is currently only the empty string or a list of extensions as negotiated by the connection.</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>. The listener receives a <a href="/en/WebSockets/WebSockets_reference/CloseEvent" title="en/WebSockets/WebSockets reference/CloseEvent"><code>CloseEvent</code></a> named "close".</td>
  </tr>
  <tr>
   <td><code>onerror</code></td>
   <td>{{ domxref("EventListener") }}</td>
   <td>An event listener to be called when an error occurs. This is a simple event named "error".</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. The listener receives a <a href="/en/WebSockets/WebSockets_reference/MessageEvent" title="en/WebSockets/WebSockets reference/MessageEvent"><code>MessageEvent</code></a> named "message".</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. The event is a simple one with the name "open".</td>
  </tr>
  <tr>
   <td><code>protocol</code></td>
   <td>{{ DOMXref("DOMString") }}</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>{{ DOMXref("DOMString") }}</td>
   <td>The URL&nbsp;as resolved by the constructor. This is always an absolute URL. <strong>Read only.</strong></td>
  </tr>
 </tbody>
</table>

<h2 id="Constants" name="Constants">Constants</h2>

<h3 id="Ready_state_constants">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 and 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 id="Methods" name="Methods">Methods</h2>

<h3 id="close()" 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(
&nbsp; in optional unsigned short code,
&nbsp;&nbsp;in optional DOMString reason
);
</pre>

<h6 id="Parameters" name="Parameters">Parameters</h6>

<dl>
 <dt><code>code</code> {{ optional_inline() }}</dt>
 <dd>A numeric value indicating the status code explaining why the connection is being closed. If this parameter is not specified, a default value of 1000 (indicating a normal "transaction complete"&nbsp;closure)&nbsp;is assumed. See the <a href="/en/WebSockets/WebSockets_reference/CloseEvent#Status_codes" title="en/WebSockets/WebSockets reference/CloseEvent#Status codes">list of status codes</a> on the <a href="/en/WebSockets/WebSockets_reference/CloseEvent" title="en/WebSockets/WebSockets reference/CloseEvent"><code>CloseEvent</code></a> page for permitted values.</dd>
 <dt><code>reason</code> {{ optional_inline() }}</dt>
 <dd>A human-readable string explaining why the connection is closing. This string must be no longer than 123 bytes of UTF-8 text (<strong>not</strong> characters).</dd>
</dl>

<h6 id="Exceptions_thrown">Exceptions thrown</h6>

<dl>
 <dt><code>INVALID_ACCESS_ERR</code></dt>
 <dd>An invalid <code>code</code> was specified.</dd>
 <dt><code>SYNTAX_ERR</code></dt>
 <dd>The <code>reason</code> string is too long or contains unpaired surrogates.</dd>
</dl>

<h6 id="Notes">Notes</h6>

<p>In Gecko, this method didn't support any parameters prior to Gecko 8.0 {{ geckoRelease("8.0") }}.</p>

<h3 id="send()" 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(
&nbsp; in ArrayBuffer data
);

void send(
&nbsp; in Blob data
); 
</pre>

<h6 id="Parameters" name="Parameters">Parameters</h6>

<dl>
 <dt><code>data</code></dt>
 <dd>A text string to send to the server.</dd>
</dl>

<h6 id="Exceptions_thrown_2">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 id="Remarks">Remarks</h6>

<div class="note">
<p><strong>Note:</strong> Gecko's implementation of the <code>send()</code>&nbsp;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); this is corrected in {{Gecko("8.0")}}.</p>

<p>As of {{Gecko("11.0")}}, support for&nbsp;<code><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer">ArrayBuffer</a></code>&nbsp;is implemented but not {{ domxref("Blob") }} data types.</p>
</div>

<h2 id="See_also" name="See_also">See also</h2>

<ul>
 <li><a href="/en/WebSockets/Writing_WebSocket_client_applications" title="en/WebSockets/Writing WebSocket client applications">Writing WebSocket client applications</a></li>
 <li><a class="external" href="https://dev.w3.org/html5/websockets/" title="https://dev.w3.org/html5/websockets/">HTML5:&nbsp;WebSockets</a></li>
</ul>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoDesktop("2.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
  <tr>
   <td>Sub-protocol support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoDesktop("6.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoMobile("7.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
  <tr>
   <td>Sub-protocol support</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoMobile("7.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<h3 id="Gecko_notes">Gecko notes</h3>

<p>Starting in&nbsp;Gecko 6.0, the constructor is prefixed; you will need to use <code>MozWebSocket()</code>:</p>

<pre>
var mySocket = new MozWebSocket("<span class="plain">https://www.example.com/socketserver</span>");
</pre>

<p>The <code>extensions</code> attribute was not supported in Gecko until Gecko 8.0.</p>

<div class="note"><strong>Note:</strong> Prior to {{Gecko("11.0")}}, outbound messages sent using the {{ manch("send") }} method were limited to 16 MB. They can now be up to 2 GB in size.</div>

<p>{{ languages ( {"zh-tw": "zh_tw/WebSockets/WebSockets_reference/WebSocket"} ) }}</p>