Short URL: http://html5.org/r/5173
| SVN | Bug | Comment | Time (UTC) |
|---|---|---|---|
| 5173 | 2010-07-21 06:47 |
Index: source
===================================================================
--- source (revision 5172)
+++ source (revision 5173)
@@ -80795,7 +80795,8 @@
<h4>The <code>WebSocket</code> interface</h4>
- <pre class="idl">[<span title="dom-WebSocket">Constructor</span>(in DOMString url, in optional DOMString protocol)]
+ <pre class="idl">[<span title="dom-WebSocket">Constructor</span>(in DOMString url, in optional DOMString protocols)]
+[<span title="dom-WebSocket">Constructor</span>(in DOMString url, in optional DOMString[] protocols)]
interface <dfn>WebSocket</dfn> {
readonly attribute DOMString <span title="dom-WebSocket-url">url</span>;
@@ -80812,20 +80813,25 @@
attribute <span>Function</span> <span title="handler-WebSocket-onmessage">onmessage</span>;
attribute <span>Function</span> <span title="handler-WebSocket-onerror">onerror</span>;
attribute <span>Function</span> <span title="handler-WebSocket-onclose">onclose</span>;
+ readonly attribute DOMString <span title="dom-WebSocket-protocol">protocol</span>;
boolean <span title="dom-WebSocket-send">send</span>(in DOMString data);
void <span title="dom-WebSocket-close">close</span>();
};
<span>WebSocket</span> implements <span>EventTarget</span>;</pre>
<p>The <dfn title="dom-WebSocket"><code>WebSocket(<var
- title="">url</var>, <var title="">protocol</var>)</code></dfn>
+ title="">url</var>, <var title="">protocols</var>)</code></dfn>
constructor takes one or two arguments. The first argument, <var
title="">url</var>, specifies the <span>URL</span> to which to
- connect. The second, <var title="">protocol</var>, if present,
- specifies a sub-protocol that the server must support for the
- connection to be successful. The sub-protocol name must be a
- non-empty ASCII string with no control characters in it (i.e. only
- characters in the range U+0020 to U+007E).</p>
+ connect. The second, <var title="">protocols</var>, if present, is
+ either a string or an array of strings. If it is a string, it is
+ equivalent to an array consisting of just that string; if it is
+ omitted, it is equivalent to the empty array. Each string in the
+ array is a subprotocol name. The connection will only be established
+ if the server reports that it has selected one of these
+ subprotocols. The subprotocol names must all be non-empty ASCII
+ strings with no control characters and not spaces in them (i.e. only
+ characters in the range U+0021 to U+007E).</p>
<p>When the <code>WebSocket()</code> constructor is invoked, the UA
must run these steps:</p>
@@ -80859,10 +80865,21 @@
</li>
- <li><p>If <var title="">protocol</var> is present but is either the
- empty string or contains characters with Unicode code points less
- than U+0020 or greater than U+007E (i.e. any characters that are
- not printable ASCII characters), then throw a
+ <li>
+
+ <p>If <var title="">protocols</var> is absent, let <var
+ title="">protocols</var> be an empty array.</p>
+
+ <p>Otherwise, if <var title="">protocols</var> is present and a
+ string, let <var title="">protocols</var> instead be an array
+ consisting of just that string.</p>
+
+ </li>
+
+ <li><p>If any of the values in <var title="">protocols</var> occur
+ more than once or contain characters with Unicode code points less
+ than U+0021 or greater than U+007E (i.e. the space character or any
+ characters that are not printable ASCII characters), then throw a
<code>SYNTAX_ERR</code> exception and abort these steps.</p></li>
<li><p>Let <var title="">origin</var> be the <span title="ASCII
@@ -80880,8 +80897,8 @@
title="">host</var>, on port <var title="">port</var> (if one was
specified), from <var title="">origin</var>, with the flag <var
title="">secure</var>, with <var title="">resource name</var> as
- the resource name, and with <var title="">protocol</var> as the
- protocol (if it is present).</p>
+ the resource name, and with <var title="">protocols</var> as the
+ (possibly empty) list of protocols.</p>
<p class="note">If the "<span>establish a WebSocket
connection</span>" algorithm fails, it triggers the "<span>fail
@@ -80937,6 +80954,18 @@
title="dom-WebSocket-readyState">readyState</code> must be set to
<code title="dom-WebSocket-CONNECTING">CONNECTING</code> (0).</p>
+ <p>The <dfn
+ title="dom-WebSocket-protocol"><code>protocol</code></dfn> attribute
+ must initially return the empty string. After the <span>WebSocket
+ connection is established</span>, its value might change, as defined
+ below.</p>
+
+ <p class="note">The <code
+ title="dom-WebSocket-protocol">protocol</code> attribute returns the
+ subprotocol selected by the server, if any. It can be used in
+ conjunction with the array form of the constructor's second argument
+ to perform subprotocol negotiation.</p>
+
<p>The <dfn title="dom-WebSocket-send"><code>send(<var
title="">data</var>)</code></dfn> method transmits data using the
connection. If the <code
@@ -81108,8 +81137,10 @@
<p>When the <i>WebSocket connection is established</i>, the user
agent must <span>queue a task</span> to first change the <code
title="dom-WebSocket-readyState">readyState</code> attribute's value
- to <code title="dom-WebSocket-OPEN">OPEN</code> (1), and then
- <span>fire a simple event</span> named <code
+ to <code title="dom-WebSocket-OPEN">OPEN</code> (1); then change the
+ <code title="dom-WebSocket-protocol">protocol</code> attribute's
+ value to the <span>selected WebSocket subprotocol</span>, if there
+ is one; and then <span>fire a simple event</span> named <code
title="event-open">open</code> at the <code>WebSocket</code>
object.</p>
@@ -81435,14 +81466,14 @@
sending cookies to the server (e.g. as an authentication
mechanism). The <code
title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>
- field takes an arbitrary string:</p>
+ field takes a space-separated list of strings:</p>
- <pre>Sec-WebSocket-Protocol: chat</pre>
+ <pre>Sec-WebSocket-Protocol: org.example.chat wsxmpp ACME.COM-IM-2</pre>
- <p>This field indicates the subprotocol (the application-level
- protocol layered over the WebSocket protocol) that the client
- intends to use. The server echoes this field in its handshake to
- indicate that it supports that subprotocol.</p>
+ <p>This field indicates the subprotocols (the application-level
+ protocol layered over the WebSocket protocol) that the client can
+ use. The server reports which subprotocol it is going to use in its
+ handshake response.</p>
<p>The other fields in the handshake are all security-related. The
<code title="http-host">Host</code> field is used to protect against
@@ -81554,12 +81585,13 @@
protocol, the main option field is <code
title="http-sec-websocket-protocol">Sec-WebSocket-Protocol</code>,
which indicates the subprotocol that the server speaks. Web browsers
- verify that the server included the same value as was specified in
- the <code>WebSocket</code> constructor, so a server that speaks
- multiple subprotocols has to make sure it selects one based on the
- client's handshake and specifies the right one in its handshake.</p>
+ verify that the server specified one of the values that was
+ specified in the <code>WebSocket</code> constructor, so a server
+ that speaks multiple subprotocols has to make sure it selects one
+ based on the client's handshake and specifies the right one in its
+ handshake.</p>
- <pre>Sec-WebSocket-Protocol: chat</pre>
+ <pre>Sec-WebSocket-Protocol: org.example.chat</pre>
<p>The server can also set cookie-related option fields to
<em>set</em> cookies, as in HTTP.</p>
@@ -81620,7 +81652,7 @@
<p>Conceptually, WebSocket is really just a layer on top of TCP
that adds a Web "origin"-based security model for browsers; adds an
- addressing and protocol naming mechanism to support multiple
+ addressing and subprotocol naming mechanism to support multiple
services on one port and multiple host names on one IP address;
layers a framing mechanism on top of TCP to get back to the IP
packet mechanism that TCP is built on, but without length
@@ -81721,8 +81753,8 @@
by including the <code
title="http-sec-websocket-protocol">Sec-Websocket-Protocol</code>
field in its handshake. If it is specified, the server needs to
- include the same field and value in its response for the connection
- to be established.</p>
+ include an equivalent field in its response for the connection to be
+ established.</p>
<p>These subprotocol names do not need to be registered, but if a
subprotocol is intended to be implemented by multiple independent
@@ -81732,10 +81764,10 @@
Corporation were to create a Chat subprotocol to be implemented by
many servers around the Web, they could name it
"chat.example.com". If the Example Organisation called their
- competing subprotocol "example.org's chat protocol", then
- the two subprotocols could be implemented by servers simultaneously,
- with the server dynamically selecting which subprotocol to use based
- on the value sent by the client.</p>
+ competing subprotocol "the-example.org-chat-protocol", then the two
+ subprotocols could be implemented by servers simultaneously, with
+ the server dynamically selecting which subprotocol to use based on
+ the value sent by the client.</p>
<p>Subprotocols can be versioned in backwards-incompatible ways by
changing the subprotocol name, eg. going from "bookings.example.net"
@@ -81915,17 +81947,18 @@
title="">port</var>, from an origin whose <span title="ASCII
serialization of an origin">ASCII serialization</span> is <var
title="">origin</var>, with a flag <var title="">secure</var>, with
- a string giving a <var title="">resource name</var>, and optionally
- with a string giving a <var title="">protocol</var>, it must run the
- following steps. The <var title="">host</var> must be ASCII-only
- (i.e. it must have been punycode-encoded already if necessary). The
- <var title="">origin</var> must not contain characters in the range
+ a string giving a <var title="">resource name</var>, and with a
+ (possibly empty) list of strings giving the <var
+ title="">protocols</var>, it must run the following steps. The <var
+ title="">host</var> must be ASCII-only (i.e. it must have been
+ punycode-encoded already if necessary). The <var
+ title="">origin</var> must not contain characters in the range
U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL
- LETTER Z). The <var title="">resource name</var> and <var
- title="">protocol</var> strings must be non-empty strings of ASCII
- characters in the range U+0020 to U+007E. The <var title="">resource
- name</var> string must start with a U+002F SOLIDUS character (/) and
- must not contain a U+0020 SPACE character. <a
+ LETTER Z). The <var title="">resource name</var> string must be a
+ non-empty string of ASCII characters in the range U+0021 to U+007E
+ that starts with a U+002F SOLIDUS character (/). The various strings
+ in <var title="">protocols</var> must all be non-empty strings with
+ characters in the range U+0021 to U+007E, and must all be unique. <a
href="#refsORIGIN">[ORIGIN]</a></p>
<ol>
@@ -82115,12 +82148,14 @@
<li>
- <p>If there is no <var title="">protocol</var>, then skip this step.</p>
+ <p>If the <var title="">protocols</var> list is empty, then skip
+ this step.</p>
<p>Otherwise, add the string consisting of the concatenation of
the string "Sec-WebSocket-Protocol:", a U+0020 SPACE character,
- and the <var title="">protocol</var> value, to <var
- title="">fields</var>.</p>
+ and the strings in <var title="">protocols</var>, maintaining
+ their relative order and each separated from the next by a single
+ U+0020 SPACE character, to <var title="">fields</var>.</p>
</li>
@@ -82634,13 +82669,19 @@
<dt>If the entry's name is "<code
title="http-sec-websocket-protocol">sec-websocket-protocol</code>"</dt>
- <dd><p>If there was a <var title="">protocol</var> specified, and
- the value is not exactly equal to <var title="">protocol</var>,
- then <span>fail the WebSocket connection</span> and abort these
- steps. (If no <var title="">protocol</var> was specified, the
- field is ignored.)</p></dd>
+ <dd>
+ <p>If the <var title="">protocols</var> list was not empty, and
+ the value is not exactly equal to one of the strings in the <var
+ title="">protocols</var> list, then <span>fail the WebSocket
+ connection</span> and abort these steps.</p>
+ <p>Otherwise, let the <dfn>selected WebSocket subprotocol</dfn>
+ be the entry's value.</p>
+
+ </dd>
+
+
<dt>If the entry's name is "<code
title="http-setcookie">set-cookie</code>" or "<code
title="http-setcookie2">set-cookie2</code>" or another
@@ -83233,17 +83274,18 @@
<dd>
- <p>The value gives the name of a subprotocol that the client is
- intending to select. It would be interesting if the server
- supports multiple protocols or protocol versions.</p>
+ <p>The value gives the names of subprotocols that the client is
+ willing to use, as a space-separated list in the order that the
+ client prefers the protocols. It would be interesting if the
+ server supports multiple protocols or protocol versions.</p>
- <p>Can be safely ignored, though the server may <span>abort the WebSocket
- connection</span> if the field is absent but the conventions for
- communicating with the server are such that the field is
- expected; and the server should <span>abort the WebSocket connection</span>
- if the field has a value that does not match one of the
- subprotocols that the server supports, to avoid integrity errors
- once the connection is established.</p>
+ <p>Can be safely ignored, though the server may <span>abort the
+ WebSocket connection</span> if the field is absent but the
+ conventions for communicating with the server are such that the
+ field is expected; and the server should <span>abort the WebSocket
+ connection</span> if the field does not contain a value that does
+ matches one of the subprotocols that the server supports, to avoid
+ integrity errors once the connection is established.</p>
</dd>
@@ -108317,6 +108359,7 @@
James M Snell,
James Perrett,
James Robinson,
+ Jamie Lokier,
Jan-Klaas Kollhof,
Jason Kersey,
Jason Lustig,