Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an API that enables Web pages to use the Web Sockets protocol for two-way communication with a remote host.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the most recently formally published revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives), whatwg@whatwg.org (subscribe, archives), or hybi@ietf.org (subscribe, archives). All feedback is welcome.
Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.
The latest stable version of the editor's draft of this specification is always available on the W3C CVS server. Change tracking for this document is available at the following location:
This specification is automatically generated from the corresponding section in the HTML5 specification's source document, as hosted in the WHATWG Subversion repository. Detailed change history for all of HTML5, including the parts that form this specification, can be found at the following locations:
The W3C Web Apps Working Group is the W3C working group responsible for this specification's progress along the W3C Recommendation track. This specification is the 23 April 2009 First Public Working Draft.
This specification is being developed in conjunction with an Internet Draft for a wire protocol, the Web Socket Protocol, available from the IETF at the following location:
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
WebSocket interfaceThis section is non-normative.
To enable Web applications to maintain bidirectional
communications with server-side processes, this specification
introduces the WebSocket interface.
This interface does not allow for raw access to the underlying network. For example, this interface could not be used to implement an IRC client without proxying messages through a custom server.
An introduction to the client-side and server-side of using the direct connection APIs.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
The only conformance class defined by this specification is user agents.
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
This specification relies on several other underlying specifications.
Many fundamental concepts from HTML5 are used by this specification. [HTML5]
The IDL blocks in this specification use the semantics of the WebIDL specification. [WebIDL]
The construction "a Foo object", where
Foo is actually an interface, is sometimes
used instead of the more accurate "an object implementing the
interface Foo".
The term DOM is used to refer to the API set made available to
scripts in Web applications, and does not necessarily imply the
existence of an actual Document object or of any other
Node objects as defined in the DOM Core
specifications. [DOM3CORE]
A DOM attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.
WebSocket interface[Constructor(in DOMString url)]
interface WebSocket {
readonly attribute DOMString URL;
// ready state
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSED = 2;
readonly attribute long readyState;
// networking
attribute Function onopen;
attribute Function onmessage;
attribute Function onclose;
void postMessage(in DOMString data);
void disconnect();
};WebSocket objects must also implement the
EventTarget interface. [DOM3EVENTS]
The WebSocket(url) constructor takes one argument,
url, which specifies the URL to
which to connect. When the WebSocket() constructor is
invoked, the UA must run these steps:
Parse the url argument.
If the previous step failed, or if url
does not have a <scheme>
component whose value is either "ws" or
"wss", when compared in an ASCII
case-insensitive manner, then throw a
SYNTAX_ERR exception.
Return a new WebSocket object, and continue
these steps in the background (without blocking scripts).
Let origin be the ASCII serialization of the
origin of the script that invoked the WebSocket() constructor,
converted to lowercase.
If the <scheme>
component of url is "ws",
set secure to false; otherwise, the <scheme> component is "wss", set secure to
true.
Let host be the value of the <host> component of url, converted to lowercase.
If url has a <port> component, then let port be that component's value; otherwise, there is no explicit port.
Let resource name be the value of the <path> component (which might be empty) of url.
If resource name is the empty string, set it to a single character U+002F SOLIDUS (/).
If url has a <query> component, then append a single U+003F QUESTION MARK (?) character to resource name, followed by the value of the <query> component.
Establish a Web Socket connection to a host host, on port port (if one was specified), from origin, with the flag secure, and with resource name as the resource name.
The URL
attribute must return the value that was passed to the
constructor.
The readyState
attribute represents the state of the connection. It can have the
following values:
CONNECTING (numeric value 0)OPEN (numeric value 1)CLOSED (numeric value 2)When the object is created its readyState must be set to
CONNECTING (0). The
steps executed when the constructor is invoked change this
attribute's value.
The postMessage(data) method transmits data using the
connection. If the connection is not established (readyState is not OPEN), it must raise an
INVALID_STATE_ERR exception. If the connection
is established, then the user agent must send data using the Web Socket.
The disconnect()
method must close the Web Socket connection or
connection attempt, if any. If the connection is already closed, it
must do nothing. Closing the connection causes a close event to be fired and
the readyState
attribute's value to change, as described
below.
The following are the event handler attributes that
must be supported, as DOM attributes, by all objects implementing
the WebSocket interface:
| event handler attribute | Event handler event type |
|---|---|
onopen | open
|
onmessage | message
|
onclose | close
|
When the Web Socket connection is established, the user agent must run the following steps:
Change the readyState attribute's value
to OPEN (1).
Queue a task to fire a simple event
named open at the
WebSocket object.
When a Web Socket message has been received with text data, the user agent must create an event that uses
the MessageEvent interface, with the event name message, which does not bubble, is
cancelable, has no default action, and whose data attribute is set to data, and queue a task to dispatch it at
the WebSocket object.
When the Web Socket connection is
closed, the readyState attribute's value
must be changed to CLOSED
(2), and the user agent must queue a task to fire
a simple event named close at the
WebSocket object.
The task source for all tasks queued in this section is the Web Socket task source.
A WebSocket object with an open connection must not
be garbage collected if there are any event listeners registered for
message events.
If a WebSocket object is garbage collected while its
connection is still open, the user agent must close the Web
Socket connection.
This section will be written in a future draft.