[html5] r2977 - [] (0) Add a protocol flag to WebSocket(), which, if set, must be echoed by the [...]

[whatwg at whatwg.org]

Author: ianh
Date: 2009-04-24 00:33:10 -0700 (Fri, 24 Apr 2009)
New Revision: 2977

Modified:
   source
Log:
[] (0) Add a protocol flag to WebSocket(), which, if set, must be echoed by the server.

Modified: source
===================================================================
--- source	2009-04-24 06:50:57 UTC (rev 2976)
+++ source	2009-04-24 07:33:10 UTC (rev 2977)
@@ -61627,7 +61627,7 @@
 
   <h4>The <code>WebSocket</code> interface</h4>
  
-  <pre class="idl">[<span title="dom-WebSocket">Constructor</span>(in DOMString url)]
+  <pre class="idl">[<span title="dom-WebSocket">Constructor</span>(in DOMString url, [Optional] in DOMString protocol)]
 interface <dfn>WebSocket</dfn> {
   readonly attribute DOMString <span title="dom-WebSocket-URL">URL</span>;
 
@@ -61650,10 +61650,13 @@
   href="#refsDOM3EVENTS">[DOM3EVENTS]</a>
 
   <p>The <dfn title="dom-WebSocket"><code>WebSocket(<var
-  title="">url</var>)</code></dfn> constructor takes one argument,
-  <var title="">url</var>, which specifies the <span>URL</span> to
-  which to connect. When the <code>WebSocket()</code> constructor is
-  invoked, the UA must run these steps:</p>
+  title="">url</var>, <var title="">protocol</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. When the <code>WebSocket()</code>
+  constructor is invoked, the UA must run these steps:</p>
 
   <ol>
 
@@ -61667,6 +61670,11 @@
    case-insensitive</span> manner, then throw a
    <code>SYNTAX_ERR</code> exception.</p></li>
 
+   <li><p>If <var title="">protocol</var> is specified but is either
+   the empty string or contains characters that are not in the range
+   U+0021 .. U+007E, then throw a <code>SYNTAX_ERR</code>
+   exception.</p></li>
+
    <li><p>Return a new <code>WebSocket</code> object, and continue
    these steps in the background (without blocking scripts).</p></li>
 
@@ -61708,8 +61716,9 @@
    <li><p><span>Establish a Web Socket connection</span> to a host
    <var 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>, and with <var title="">resource name</var>
-   as the resource name.</p></li>
+   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></li>
 
   </ol>
 
@@ -61889,9 +61898,10 @@
   <p>When the user agent is to <dfn>establish a Web Socket
   connection</dfn> to a host <var title="">host</var>, optionally on
   port <var title="">port</var>, from an origin <var
-  title="">origin</var>, with a flag <var title="">secure</var>, and
-  with a particular <var title="">resource name</var>, it must run the
-  following steps.</p>
+  title="">origin</var>, with a flag <var title="">secure</var>, with
+  a particular <var title="">resource name</var>, and optionally with
+  a particular <var title="">protocol</var>, it must run the following
+  steps.</p>
 
   <p class="note">The <var title="">host</var> and <var
   title="">origin</var> strings will be all-lowercase when this
@@ -62008,6 +62018,27 @@
 
    <li>
 
+    <p>If there is no <var title="">protocol</var>, then skip this step.</p>
+
+    <p>Othewrise, send the following bytes:</p>
+
+    <pre>57 65 62 53 6f 63 6b 65  74 2d 50 72 6f 74 6f 63
+6f 6c 3a 20</pre>
+
+    <p>Send the <var title="">protocol</var> value, encoded as
+    US-ASCII.</p>
+
+    <p>Send the following bytes:</p>
+
+    <pre>0d 0a</pre>
+
+    <p class="note">The string "WebSocket-Protocol: ", the
+    protocol, and CRLF.</p>
+
+   </li>
+
+   <li>
+
     <p>If the client has any authentication information or cookies
     that would be relevant to a resource accessed over HTTP, if <var
     title="">secure</var> is false, or HTTPS, if it is true, on host
@@ -62237,7 +62268,10 @@
     in the <var title="">headers</var> list whose name is "<code
     title="">websocket-origin</code>", or if there is not exactly one
     entry in the <var title="">headers</var> list whose name is "<code
-    title="">websocket-location</code>", or if there are any entries
+    title="">websocket-location</code>", or if the <var
+    title="">protocol</var> was specified but there is not exactly one
+    entry in the <var title="">headers</var> list whose name is "<code
+    title="">websocket-protocol</code>", or if there are any entries
     in the <var title="">headers</var> list whose names are the empty
     string, then <span>fail the Web Socket connection</span> and abort
     these steps.</p>
@@ -62306,6 +62340,16 @@
      </dd>
 
 
+     <dt>If the entry's name is "<code
+     title="">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 Web Socket connection</span> and abort these
+     steps. (If no <var title="">protocol</var> was specified, the
+     header is ignored.)</p></dd>
+
+
      <dt>If the entry's name is "<code title="">set-cookie</code>" or
      "<code title="">set-cookie2</code>" or another cookie-related
      header name</dt>