W3C home > Mailing lists > Public > public-html-commits@w3.org > May 2010

html5/websockets Overview.html,1.175,1.176

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Tue, 11 May 2010 08:25:46 +0000
To: public-html-commits@w3.org
Message-Id: <E1OBkmg-0007pz-17@lionel-hutz.w3.org>
Update of /sources/public/html5/websockets
In directory hutz:/tmp/cvs-serv30113

Modified Files:
	Overview.html 
Log Message:
regen

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/websockets/Overview.html,v
retrieving revision 1.175
retrieving revision 1.176
diff -u -d -r1.175 -r1.176
--- Overview.html	5 May 2010 08:24:22 -0000	1.175
+++ Overview.html	11 May 2010 08:25:43 -0000	1.176
@@ -183,7 +183,7 @@
    <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
    <h1>The WebSocket API</h1>
 
-   <h2 class="no-num no-toc" id="editor-s-draft-5-may-2010">Editor's Draft 5 May 2010</h2>
+   <h2 class="no-num no-toc" id="editor-s-draft-6-may-2010">Editor's Draft 6 May 2010</h2>
    <dl><dt>Latest Published Version:</dt>
     <dd><a href="http://www.w3.org/TR/websockets/">http://www.w3.org/TR/websockets/</a></dd>
     <dt>Latest Editor's Draft:</dt>
@@ -247,7 +247,7 @@
   Working Group</a> is the W3C working group responsible for this
   specification's progress along the W3C Recommendation track.
 
-  This specification is the 5 May 2010 Editor's Draft.
+  This specification is the 6 May 2010 Editor's Draft.
   <p>This specification is being developed in conjunction with an
   Internet Draft for a wire protocol, the WebSocket Protocol,
   available from the following location:<ul><li>WebSocket Protocol Internet-Draft: <a href="http://www.whatwg.org/specs/web-socket-protocol/">http://www.whatwg.org/specs/web-socket-protocol/</a></li>
@@ -275,32 +275,61 @@
    <li><a href="#event-definitions"><span class="secno">5.1 </span>Event definitions</a></li>
    <li><a href="#garbage-collection"><span class="secno">5.2 </span>Garbage collection</a></ol></li>
  <li><a class="no-num" href="#references">References</a></ol>
-<!--end-toc--><hr><h2 id="network-intro"><span class="secno">1 </span>Introduction</h2><p><i>This section is non-normative.</i><p>To enable Web applications to maintain bidirectional
+<!--end-toc--><hr><div data-component="Web Workers (editor: Ian Hickson)">
+
+  <h2 id="network-intro"><span class="secno">1 </span>Introduction</h2>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>To enable Web applications to maintain bidirectional
   communications with server-side processes, this specification
-  introduces the <code><a href="#websocket">WebSocket</a></code> interface.<p class="note">This interface does not allow for raw access to the
+  introduces the <code><a href="#websocket">WebSocket</a></code> interface.</p>
+
+  <p class="note">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.<h2 id="conformance-requirements"><span class="secno">2 </span>Conformance requirements</h2><p>All diagrams, examples, and notes in this specification are
+  server.</p>
+
+
+
+
+  <h2 id="conformance-requirements"><span class="secno">2 </span>Conformance requirements</h2>
+
+  <p>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.<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
+  Everything else in this specification is normative.</p>
+
+  <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
   NOT",--> "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. <a href="#refsRFC2119">[RFC2119]</a><p>Requirements phrased in the imperative as part of algorithms
+  not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
+
+  <p>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.<p>Some conformance requirements are phrased as requirements on
+  algorithm.</p>
+
+  <p>Some conformance requirements are phrased as requirements on
   attributes, methods or objects. Such requirements are to be
-  interpreted as requirements on user agents.<p>Conformance requirements phrased as algorithms or specific steps
+  interpreted as requirements on user agents.</p>
+
+  <p>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.)<p>The only conformance class defined by this specification is user
-  agents.<p>User agents may impose implementation-specific limits on
+  be performant.)</p>
+
+  <p>The only conformance class defined by this specification is user
+  agents.</p>
+
+  <p>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.<p>When support for a feature is disabled (e.g. as an emergency
+  platform-specific limitations.</p>
+
+  <p>When support for a feature is disabled (e.g. as an emergency
   measure to mitigate a security problem, or to aid in development, or
   for performance reasons), user agents must act as if they had no
   support for the feature whatsoever, and as if the feature was not
@@ -308,8 +337,15 @@
   feature is accessed via an attribute in a Web IDL interface, the
   attribute itself would be omitted from the objects that implement
   that interface &mdash; leaving the attribute on the object but
-  making it return null or throw an exception is insufficient.<h3 id="dependencies"><span class="secno">2.1 </span>Dependencies</h3><p>This specification relies on several other underlying
-  specifications.<dl><dt>HTML</dt>
+  making it return null or throw an exception is insufficient.</p>
+
+
+  <h3 id="dependencies"><span class="secno">2.1 </span>Dependencies</h3>
+
+  <p>This specification relies on several other underlying
+  specifications.</p>
+
+  <dl><dt>HTML</dt>
 
    <dd>
 
@@ -327,16 +363,27 @@
 
    </dd>
 
-  </dl><h2 id="terminology"><span class="secno">3 </span>Terminology</h2><p>The construction "a <code title="">Foo</code> object", where
+  </dl><h2 id="terminology"><span class="secno">3 </span>Terminology</h2>
+
+  <p>The construction "a <code title="">Foo</code> object", where
   <code title="">Foo</code> is actually an interface, is sometimes
   used instead of the more accurate "an object implementing the
-  interface <code title="">Foo</code>".<p>The term DOM is used to refer to the API set made available to
+  interface <code title="">Foo</code>".</p>
+
+  <p>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 <code>Document</code> object or of any other
   <code>Node</code> objects as defined in the DOM Core
-  specifications. <a href="#refsDOMCORE">[DOMCORE]</a><p>An IDL attribute is said to be <em>getting</em> when its value is
+  specifications. <a href="#refsDOMCORE">[DOMCORE]</a></p>
+
+  <p>An IDL attribute is said to be <em>getting</em> when its value is
   being retrieved (e.g. by author script), and is said to be
-  <em>setting</em> when a new value is assigned to it.<h2 id="the-websocket-interface"><span class="secno">4 </span>The <code><a href="#websocket">WebSocket</a></code> interface</h2><pre class="idl">[<a href="#dom-websocket" title="dom-WebSocket">Constructor</a>(in DOMString url, in optional DOMString protocol)]
+  <em>setting</em> when a new value is assigned to it.</p>
+
+
+  <h2 id="the-websocket-interface"><span class="secno">4 </span>The <code><a href="#websocket">WebSocket</a></code> interface</h2>
+
+  <pre class="idl">[<a href="#dom-websocket" title="dom-WebSocket">Constructor</a>(in DOMString url, in optional DOMString protocol)]
 interface <dfn id="websocket">WebSocket</dfn> {
   readonly attribute DOMString <a href="#dom-websocket-url" title="dom-WebSocket-url">url</a>;
 
@@ -356,14 +403,20 @@
   boolean <a href="#dom-websocket-send" title="dom-WebSocket-send">send</a>(in DOMString data);
   void <a href="#dom-websocket-close" title="dom-WebSocket-close">close</a>();
 };
-<a href="#websocket">WebSocket</a> implements <span>EventTarget</span>;</pre><p>The <dfn id="dom-websocket" title="dom-WebSocket"><code>WebSocket(<var title="">url</var>, <var title="">protocol</var>)</code></dfn>
+<a href="#websocket">WebSocket</a> implements <span>EventTarget</span>;</pre>
+
+  <p>The <dfn id="dom-websocket" title="dom-WebSocket"><code>WebSocket(<var 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. 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>When the <code>WebSocket()</code> constructor is invoked, the UA
-  must run these steps:<ol><!-- beware, this is very similar to the steps for what happens
+  characters in the range U+0020 to U+007E).</p>
+
+  <p>When the <code>WebSocket()</code> constructor is invoked, the UA
+  must run these steps:</p>
+
+  <ol><!-- beware, this is very similar to the steps for what happens
    during a redirect, in the protocol section --><li><p><span>Parse a WebSocket URL's components</span> from the
    <var title="">url</var> argument, to obtain <var title="">host</var>, <var title="">port</var>, <var title="">resource name</var>, and <var title="">secure</var>. If
    this fails, throw a <code>SYNTAX_ERR</code> exception and abort
@@ -417,13 +470,19 @@
 
   </ol><p>This constructor must be visible when the <span>script's global
   object</span> is either a <code>Window</code> object or an object
-  implementing the <code>WorkerUtils</code> interface.<hr><p>The <dfn id="dom-websocket-url" title="dom-WebSocket-url"><code>url</code></dfn>
+  implementing the <code>WorkerUtils</code> interface.</p>
+
+  <hr><p>The <dfn id="dom-websocket-url" title="dom-WebSocket-url"><code>url</code></dfn>
   attribute must return the result of <span title="resolve a
   url">resolving</span> the <span>URL</span> that was passed to the
   constructor. (It doesn't matter what it is resolved relative to,
-  since we already know it is an <span>absolute URL</span>.)<p>The <dfn id="dom-websocket-readystate" title="dom-WebSocket-readyState"><code>readyState</code></dfn>
+  since we already know it is an <span>absolute URL</span>.)</p>
+
+  <p>The <dfn id="dom-websocket-readystate" title="dom-WebSocket-readyState"><code>readyState</code></dfn>
   attribute represents the state of the connection. It can have the
-  following values:<dl><dt><dfn id="dom-websocket-connecting" title="dom-WebSocket-CONNECTING"><code>CONNECTING</code></dfn> (numeric value 0)</dt>
+  following values:</p>
+
+  <dl><dt><dfn id="dom-websocket-connecting" title="dom-WebSocket-CONNECTING"><code>CONNECTING</code></dfn> (numeric value 0)</dt>
 
    <dd>The connection has not yet been established.</dd>
 
@@ -440,7 +499,9 @@
    <dd>The connection has been closed or could not be opened.</dd>
 
   </dl><p>When the object is created its <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> must be set to
-  <code title="dom-WebSocket-CONNECTING"><a href="#dom-websocket-connecting">CONNECTING</a></code> (0).<p>The <dfn id="dom-websocket-send" title="dom-WebSocket-send"><code>send(<var title="">data</var>)</code></dfn> method transmits data using the
+  <code title="dom-WebSocket-CONNECTING"><a href="#dom-websocket-connecting">CONNECTING</a></code> (0).</p>
+
+  <p>The <dfn id="dom-websocket-send" title="dom-WebSocket-send"><code>send(<var title="">data</var>)</code></dfn> method transmits data using the
   connection. If the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute is
   <code title="dom-WebSocket-CONNECTING"><a href="#dom-websocket-connecting">CONNECTING</a></code>, it must
   raise an <code>INVALID_STATE_ERR</code> exception. Otherwise, if the
@@ -456,8 +517,12 @@
   queued or sent successfully), or false if the connection is closing
   or closed (e.g. because the user agent just had a buffer overflow
   and failed to send the data, or because <span>the WebSocket closing
-  handshake has started</span>).<p>The <dfn id="dom-websocket-close" title="dom-WebSocket-close"><code>close()</code></dfn>
-  method must run the first matching steps from the following list:<dl class="switch"><dt>If the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
+  handshake has started</span>).</p>
+
+  <p>The <dfn id="dom-websocket-close" title="dom-WebSocket-close"><code>close()</code></dfn>
+  method must run the first matching steps from the following list:</p>
+
+  <dl class="switch"><dt>If the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
    attribute is in the <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2) or <code title="dom-WebSocket-CLOSED"><a href="#dom-websocket-closed">CLOSED</a></code> (3) state</dt>
 
    <dd>
@@ -534,7 +599,9 @@
   protocol, or buffering done by the operating system or network
   hardware. If the connection is closed, this attribute's value will
   only increase with each call to the <code title="dom-WebSocket-send"><a href="#dom-websocket-send">send()</a></code> method (the number does not
-  reset to zero once the connection closes).<div class="example">
+  reset to zero once the connection closes).</p>
+
+  <div class="example">
 
    <p>In this simple example, the <code title="dom-WebSocket-bufferedAmount"><a href="#dom-websocket-bufferedamount">bufferedAmount</a></code>
    attribute is used to ensure that updates are sent either at the
@@ -556,34 +623,48 @@
    requires more careful monitoring of the value of the attribute over
    time.</p>
 
-  </div><hr><p>The following are the <span>event handlers</span> that must be
+  </div>
+
+  <hr><p>The following are the <span>event handlers</span> that must be
   supported, as IDL attributes, by all objects implementing the
-  <code><a href="#websocket">WebSocket</a></code> interface:<table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
+  <code><a href="#websocket">WebSocket</a></code> interface:</p>
+
+  <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
    <tbody><tr><td><dfn id="handler-websocket-onopen" title="handler-WebSocket-onopen"><code>onopen</code></dfn> <td> <code title="event-open">open</code>
     <tr><td><dfn id="handler-websocket-onmessage" title="handler-WebSocket-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message">message</code>
     <tr><td><dfn id="handler-websocket-onerror" title="handler-WebSocket-onerror"><code>onerror</code></dfn> <td> <code title="event-error">error</code>
     <tr><td><dfn id="handler-websocket-onclose" title="handler-WebSocket-onclose"><code>onclose</code></dfn> <td> <code title="event-close">close</code>
-  </table><h2 id="feedback-from-the-protocol"><span class="secno">5 </span>Feedback from the protocol</h2><p>When the <i>WebSocket connection is established</i>, the user
+  </table><h2 id="feedback-from-the-protocol"><span class="secno">5 </span>Feedback from the protocol</h2>
+
+  <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"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
   to <code title="dom-WebSocket-OPEN"><a href="#dom-websocket-open">OPEN</a></code> (1), and then
   <span>fire a simple event</span> named <code title="event-open">open</code> at the <code><a href="#websocket">WebSocket</a></code>
-  object.<p>When <i>a WebSocket message has been received</i> with text <var title="">data</var>, the user agent must create an event that uses
+  object.</p>
+
+  <p>When <i>a WebSocket message has been received</i> with text <var title="">data</var>, the user agent must create an event that uses
   the <code>MessageEvent</code> interface, with the event name <code title="event-message">message</code>, which does not bubble, is not
   cancelable, has no default action, and whose <code title="dom-MessageEvent-data">data</code> attribute is set to <var title="">data</var>, and <span>queue a task</span> to check to see
   if the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
   attribute's value is <code title="dom-WebSocket-OPEN"><a href="#dom-websocket-open">OPEN</a></code>
   (1) or <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2), and
-  if so, dispatch the event at the <code><a href="#websocket">WebSocket</a></code> object.<p>When <i>a WebSocket error has been detected</i>, the user agent
+  if so, dispatch the event at the <code><a href="#websocket">WebSocket</a></code> object.</p>
+
+  <p>When <i>a WebSocket error has been detected</i>, the user agent
   must <span>queue a task</span> to check to see if the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
   is <code title="dom-WebSocket-OPEN"><a href="#dom-websocket-open">OPEN</a></code> (1) or <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2), and if so,
   <span>fire a simple event</span> named <code title="event-error">error</code> at the <code><a href="#websocket">WebSocket</a></code>
-  object.<p>When <i>the WebSocket closing handshake has started</i>, the user
+  object.</p>
+
+  <p>When <i>the WebSocket closing handshake has started</i>, the user
   agent must <span>queue a task</span> to change the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's value
   to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2). (If the
   <code title="dom-WebSocket-close"><a href="#dom-websocket-close">close()</a></code> method was called,
   the <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code>
   attribute's value will already be set to <code title="dom-WebSocket-CLOSING"><a href="#dom-websocket-closing">CLOSING</a></code> (2) when this task
-  runs.)<p id="closeWebSocket">When the <i>WebSocket connection is
+  runs.)</p>
+
+  <p id="closeWebSocket">When the <i>WebSocket connection is
   closed</i>, possibly <i title="">cleanly</i>, the user agent must
   create an event that uses the <code><a href="#closeevent">CloseEvent</a></code> interface,
   with the event name <code title="event-close">close</code>, which
@@ -593,21 +674,51 @@
   false otherwise; and <span>queue a task</span> to first change the
   <code title="dom-WebSocket-readyState"><a href="#dom-websocket-readystate">readyState</a></code> attribute's
   value to <code title="dom-WebSocket-CLOSED"><a href="#dom-websocket-closed">CLOSED</a></code> (3), and
-  then dispatch the event at the <code><a href="#websocket">WebSocket</a></code> object.<p>The <span>task source</span> for all <span title="concept-task">tasks</span> <span title="queue a
+  then dispatch the event at the <code><a href="#websocket">WebSocket</a></code> object.</p>
+
+  <p>The <span>task source</span> for all <span title="concept-task">tasks</span> <span title="queue a
   task">queued</span> in this section is the <dfn id="websocket-task-source">WebSocket task
-  source</dfn>.<h3 id="event-definitions"><span class="secno">5.1 </span>Event definitions</h3><pre class="idl">interface <dfn id="closeevent">CloseEvent</dfn> : <span>Event</span> {
+  source</dfn>.</p>
+
+
+  <h3 id="event-definitions"><span class="secno">5.1 </span>Event definitions</h3>
+
+  <pre class="idl">interface <dfn id="closeevent">CloseEvent</dfn> : <span>Event</span> {
   readonly attribute boolean <a href="#dom-closeevent-wasclean" title="dom-CloseEvent-wasClean">wasClean</a>;
   void <a href="#dom-closeevent-initcloseevent" title="dom-CloseEvent-initCloseEvent">initCloseEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in boolean wasCleanArg);
-};</pre><p>The <dfn id="dom-closeevent-initcloseevent" title="dom-CloseEvent-initCloseEvent"><code>initCloseEvent()</code></dfn>
+};</pre>
+
+  <p>The <dfn id="dom-closeevent-initcloseevent" title="dom-CloseEvent-initCloseEvent"><code>initCloseEvent()</code></dfn>
   method must initialize the event in a manner analogous to the
-  similarly-named method in the DOM Events interfaces. <a href="#refsDOMEVENTS">[DOMEVENTS]</a><p>The <dfn id="dom-closeevent-wasclean" title="dom-CloseEvent-wasClean"><code>wasClean</code></dfn>
+  similarly-named method in the DOM Events interfaces. <a href="#refsDOMEVENTS">[DOMEVENTS]</a></p>
+
+  <p>The <dfn id="dom-closeevent-wasclean" title="dom-CloseEvent-wasClean"><code>wasClean</code></dfn>
   attribute represents whether the connection closed cleanly or
-  not.<h3 id="garbage-collection"><span class="secno">5.2 </span>Garbage collection</h3><p>A <code><a href="#websocket">WebSocket</a></code> object with an open connection must not
+  not.</p>
+
+
+
+  <h3 id="garbage-collection"><span class="secno">5.2 </span>Garbage collection</h3>
+
+  <p>A <code><a href="#websocket">WebSocket</a></code> object with an open connection must not
   be garbage collected if there are any event listeners registered for
-  <code title="event-message">message</code> events.<p>If a <code><a href="#websocket">WebSocket</a></code> object is garbage collected while its
+  <code title="event-message">message</code> events.</p>
+
+  <p>If a <code><a href="#websocket">WebSocket</a></code> object is garbage collected while its
   connection is still open, the user agent must <span>close the
-  WebSocket connection</span>.<h2 class="no-num" id="references">References</h2><!--REFS--><p>All references are normative unless marked "Non-normative".</p><!-- Dates are only included for standards older than the Web,
-  because the newer ones keep changing. --><dl><dt id="refsDOMCORE">[DOMCORE]</dt>
+  WebSocket connection</span>.</p>
+
+
+
+
+  <h2 class="no-num" id="references">References</h2><!--REFS-->
+
+  <p>All references are normative unless marked "Non-normative".</p>
+
+  <!-- Dates are only included for standards older than the Web,
+  because the newer ones keep changing. -->
+
+  <dl><dt id="refsDOMCORE">[DOMCORE]</dt>
    <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-Core/">Document
    Object Model (DOM) Level 3 Core Specification</a></cite>, A. Le
    Hors, P. Le Hegaret, L. Wood, G. Nicol, J. Robie, M. Champion,
@@ -644,4 +755,4 @@
    <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web
    IDL</a></cite>, C. McCormack. W3C.</dd>
 
-  </dl>
+  </dl></div>
Received on Tuesday, 11 May 2010 08:25:48 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 11 May 2010 08:25:49 GMT