{{ SeeCompatTable() }}
The WebSocket
object provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
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 );
-
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.
Method overview
void close(in optional unsigned long code, in optional DOMString reason); |
void send(in DOMString data); |
Attributes
Attribute | Type | Description |
binaryType |
{{ DOMXref("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 |
{{ DOMXref("DOMString") }} | The extensions selected by the server. This is currently only the empty string or a list of extensions as negotiated by the connection. |
onclose |
{{ domxref("EventListener") }} | An event listener to be called when the WebSocket connection's readyState changes to CLOSED . The listener receives a CloseEvent named "close". |
onerror |
{{ domxref("EventListener") }} | An event listener to be called when an error occurs. This is a simple event named "error". |
onmessage |
{{ domxref("EventListener") }} | An event listener to be called when a message is received from the server. The listener receives a MessageEvent named "message". |
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. The event is a simple one with the name "open". |
protocol |
{{ DOMXref("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 |
{{ DOMXref("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 and 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( in optional unsigned short code, in optional DOMString reason );
Parameters
-
code
{{ optional_inline() }} -
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" closure) is assumed. See the list of status codes on the
CloseEvent
page for permitted values. -
reason
{{ optional_inline() }} - A human-readable string explaining why the connection is closing. This string must be no longer than 123 bytes of UTF-8 text (not characters).
Exceptions thrown
-
INVALID_ACCESS_ERR
-
An invalid
code
was specified. -
SYNTAX_ERR
-
The
reason
string is too long or contains unpaired surrogates.
Notes
In Gecko, this method didn't support any parameters prior to Gecko 8.0 {{ geckoRelease("8.0") }}.
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
Note: 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); this is corrected in {{Gecko("8.0")}}.
As of {{Gecko("11.0")}}, support for ArrayBuffer
is implemented but not {{ domxref("Blob") }} data types.
See also
Browser compatibility
{{ CompatibilityTable() }}
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | {{ CompatUnknown() }} | {{ CompatGeckoDesktop("2.0") }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} |
Sub-protocol support | {{ CompatUnknown() }} | {{ CompatGeckoDesktop("6.0") }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} |
Feature | Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | {{ CompatUnknown() }} | {{ CompatGeckoMobile("7.0") }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} |
Sub-protocol support | {{ CompatUnknown() }} | {{ CompatGeckoMobile("7.0") }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} | {{ CompatUnknown() }} |
Gecko notes
Starting in Gecko 6.0, the constructor is prefixed; you will need to use MozWebSocket()
:
var mySocket = new MozWebSocket("https://www.example.com/socketserver");
The extensions
attribute was not supported in Gecko until Gecko 8.0.
{{ languages ( {"zh-tw": "zh_tw/WebSockets/WebSockets_reference/WebSocket"} ) }}