- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 11 May 2010 08:25:46 +0000
- To: public-html-commits@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 — 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 UTC