- From: CVS User ihickson <cvsmail@w3.org>
- Date: Wed, 31 Jul 2013 19:27:42 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/eventsource
In directory roscoe:/tmp/cvs-serv24201
Modified Files:
Overview.html
Log Message:
Cleanup (whatwg r8106)
--- /sources/public/html5/eventsource/Overview.html 2013/07/26 17:57:13 1.245
+++ /sources/public/html5/eventsource/Overview.html 2013/07/31 19:27:42 1.246
@@ -216,7 +216,7 @@
<h1>Server-Sent Events</h1>
- <h2 class="no-num no-toc" id="editor-s-draft-26-july-2013">Editor's Draft 26 July 2013</h2>
+ <h2 class="no-num no-toc" id="editor-s-draft-31-july-2013">Editor's Draft 31 July 2013</h2>
<dl><dt>Latest Published Version:</dt>
<dd><a href="http://www.w3.org/TR/eventsource/">http://www.w3.org/TR/eventsource/</a></dd>
<dt>Latest Editor's Draft:</dt>
@@ -354,7 +354,7 @@
</dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
Working Group</a> is the W3C working group responsible for this
specification's progress along the W3C Recommendation track.
- This specification is the 26 July 2013 Editor's Draft.
+ This specification is the 31 July 2013 Editor's Draft.
</p>
@@ -571,16 +571,13 @@
boolean <dfn id="dom-eventsourceinit-withcredentials" title="dom-EventSourceInit-withCredentials">withCredentials</dfn> = false;
};</pre>
- <p>The <dfn id="dom-eventsource" title="dom-EventSource"><code>EventSource()</code></dfn>
- constructor takes one or two arguments. The first specifies the
- <span>URL</span> to which to connect. The second specifies the
- settings, if any, in the form of an <code><a href="#eventsourceinit">EventSourceInit</a></code>
- dictionary. When the <code>EventSource()</code> constructor is
- invoked, the UA must run these steps:</p>
-
- <ol><li><p><span title="resolve a url">Resolve</span> the
- <span>URL</span> specified in the first argument, relative to the
- <span>entry script</span>'s <span title="script's base URL">base
+ <p>The <dfn id="dom-eventsource" title="dom-EventSource"><code>EventSource()</code></dfn> constructor takes one or two
+ arguments. The first specifies the <span>URL</span> to which to connect. The second specifies the
+ settings, if any, in the form of an <code><a href="#eventsourceinit">EventSourceInit</a></code> dictionary. When the
+ <code>EventSource()</code> constructor is invoked, the UA must run these steps:</p>
+
+ <ol><li><p><span title="resolve a url">Resolve</span> the <span>URL</span> specified in the first
+ argument, relative to the <span>entry script</span>'s <span title="script's base URL">base
URL</span>.
<a href="#refsHTML">[HTML]</a>
@@ -594,132 +591,111 @@
<li><p>Let <var title="">CORS mode</var> be <span title="attr-crossorigin-anonymous">Anonymous</span>.</li>
- <li><p>If the second argument is present, and the <code title="dom-EventSourceInit-withCredentials"><a href="#dom-eventsourceinit-withcredentials">withCredentials</a></code>
- dictionary member has the value true, then set <var title="">CORS
- mode</var> to <span title="attr-crossorigin-use-credentials">Use
- Credentials</span> and initialize the new <code><a href="#eventsource">EventSource</a></code>
- object's <code title="dom-EventSource-withCredentials"><a href="#dom-eventsource-withcredentials">withCredentials</a></code>
- attribute to true.</li>
+ <li><p>If the second argument is present, and the <code title="dom-EventSourceInit-withCredentials"><a href="#dom-eventsourceinit-withcredentials">withCredentials</a></code> dictionary member has the
+ value true, then set <var title="">CORS mode</var> to <span title="attr-crossorigin-use-credentials">Use Credentials</span> and initialize the new
+ <code><a href="#eventsource">EventSource</a></code> object's <code title="dom-EventSource-withCredentials"><a href="#dom-eventsource-withcredentials">withCredentials</a></code> attribute to true.</li>
- <li><p>Return the new <code><a href="#eventsource">EventSource</a></code> object, but continue
- these steps asynchronously.</li>
+ <li><p>Return the new <code><a href="#eventsource">EventSource</a></code> object, but continue these steps
+ asynchronously.</li>
<li>
- <p>Do a <span>potentially CORS-enabled fetch</span> of
- the resulting <span>absolute URL</span> using the <span>entry
- script</span>'s <span title="script's referrer source">referrer
- source</span>, with the <i>mode</i> being <var title="">CORS
- mode</var>, and the <i title="">origin</i> being the <span>entry
- script</span>'s <span>origin</span>, and process the
- resource obtained in this fashion, if any, as described below.</p>
-
- <p class="note">The definition of the <span title="fetch">fetching</span> algorithm (which is used by CORS) is
- such that if the browser is already fetching the resource
- identified by the given <span>absolute URL</span>, that connection
- can be reused, instead of a new connection being established. All
- messages received up to this point are dispatched immediately, in
- this case.</p>
+ <p>Do a <span>potentially CORS-enabled fetch</span> of the resulting <span>absolute
+ URL</span> using the <span>entry script</span>'s <span title="script's referrer source">referrer
+ source</span>, with the <i>mode</i> being <var title="">CORS mode</var>, and the <i title="">origin</i> being the <span>entry script</span>'s <span>origin</span>, and process the resource obtained in this fashion, if any, as
+ described below.</p>
+
+ <p class="note">The definition of the <span title="fetch">fetching</span> algorithm (which is
+ used by CORS) is such that if the browser is already fetching the resource identified by the
+ given <span>absolute URL</span>, that connection can be reused, instead of a new connection
+ being established. All messages received up to this point are dispatched immediately, in this
+ case.</p>
</li>
- </ol><hr><p>The <dfn id="dom-eventsource-url" title="dom-EventSource-url"><code>url</code></dfn>
- attribute must return the <span>absolute URL</span> that resulted
- from <span title="resolve a url">resolving</span> the value that was
- passed to the constructor.</p>
-
- <p>The <dfn id="dom-eventsource-withcredentials" title="dom-EventSource-withCredentials"><code>withCredentials</code></dfn>
- attribute must return the value to which it was last initialized.
- When the object is created, it must be initialized to false.</p>
-
- <p>The <dfn id="dom-eventsource-readystate" title="dom-EventSource-readyState"><code>readyState</code></dfn>
- attribute represents the state of the connection. It can have the
- following values:</p>
+ </ol><hr><p>The <dfn id="dom-eventsource-url" title="dom-EventSource-url"><code>url</code></dfn> attribute must return the
+ <span>absolute URL</span> that resulted from <span title="resolve a url">resolving</span> the
+ value that was passed to the constructor.</p>
+
+ <p>The <dfn id="dom-eventsource-withcredentials" title="dom-EventSource-withCredentials"><code>withCredentials</code></dfn> attribute
+ must return the value to which it was last initialized. When the object is created, it must be
+ initialized to false.</p>
+
+ <p>The <dfn id="dom-eventsource-readystate" title="dom-EventSource-readyState"><code>readyState</code></dfn> attribute represents
+ the state of the connection. It can have the following values:</p>
<dl><dt><dfn id="dom-eventsource-connecting" title="dom-EventSource-CONNECTING"><code>CONNECTING</code></dfn> (numeric value 0)</dt>
- <dd>The connection has not yet been established, or it was closed
- and the user agent is reconnecting.</dd>
+ <dd>The connection has not yet been established, or it was closed and the user agent is
+ reconnecting.</dd>
<dt><dfn id="dom-eventsource-open" title="dom-EventSource-OPEN"><code>OPEN</code></dfn> (numeric value 1)</dt>
- <dd>The user agent has an open connection and is dispatching events
- as it receives them.</dd>
+ <dd>The user agent has an open connection and is dispatching events as it receives them.</dd>
<dt><dfn id="dom-eventsource-closed" title="dom-EventSource-CLOSED"><code>CLOSED</code></dfn> (numeric value 2)</dt>
- <dd>The connection is not open, and the user agent is not trying to
- reconnect. Either there was a fatal error or the <code title="dom-EventSource-close"><a href="#dom-eventsource-close">close()</a></code> method was
- invoked.</dd>
-
- </dl><p>When the object is created its <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> must be set to
- <code title="dom-EventSource-CONNECTING"><a href="#dom-eventsource-connecting">CONNECTING</a></code> (0). The
- rules given below for handling the connection define when the value
- changes.</p>
-
- <p>The <dfn id="dom-eventsource-close" title="dom-EventSource-close"><code>close()</code></dfn>
- method must abort any instances of the <span>fetch</span> algorithm
- started for this <code><a href="#eventsource">EventSource</a></code> object, and must set the
- <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute
- to <code title="dom-EventSource-CLOSED"><a href="#dom-eventsource-closed">CLOSED</a></code>.</p>
-
- <p>The following are the <span>event handlers</span> (and their
- corresponding <span title="event handler event type">event handler
- event types</span>) that must be supported, as <span>event handler IDL attributes</span>, by
- all objects implementing the <code><a href="#eventsource">EventSource</a></code> interface:</p>
+ <dd>The connection is not open, and the user agent is not trying to reconnect. Either there was a
+ fatal error or the <code title="dom-EventSource-close"><a href="#dom-eventsource-close">close()</a></code> method was invoked.</dd>
+
+ </dl><p>When the object is created its <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> must
+ be set to <code title="dom-EventSource-CONNECTING"><a href="#dom-eventsource-connecting">CONNECTING</a></code> (0). The rules given below
+ for handling the connection define when the value changes.</p>
+
+ <p>The <dfn id="dom-eventsource-close" title="dom-EventSource-close"><code>close()</code></dfn> method must abort any
+ instances of the <span>fetch</span> algorithm started for this <code><a href="#eventsource">EventSource</a></code> object,
+ and must set the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute to <code title="dom-EventSource-CLOSED"><a href="#dom-eventsource-closed">CLOSED</a></code>.</p>
+
+ <p>The following are the <span>event handlers</span> (and their corresponding <span title="event
+ handler event type">event handler event types</span>) that must be supported, as <span>event
+ handler IDL attributes</span>, by all objects implementing the <code><a href="#eventsource">EventSource</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-eventsource-onopen" title="handler-EventSource-onopen"><code>onopen</code></dfn> <td> <code title="event-open">open</code>
<tr><td><dfn id="handler-eventsource-onmessage" title="handler-EventSource-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message">message</code>
<tr><td><dfn id="handler-eventsource-onerror" title="handler-EventSource-onerror"><code>onerror</code></dfn> <td> <code title="event-error">error</code>
- </table><hr><p>In addition to the above, each <code><a href="#eventsource">EventSource</a></code> object
- has the following associated with it:</p>
+ </table><hr><p>In addition to the above, each <code><a href="#eventsource">EventSource</a></code> object has the following associated
+ with it:</p>
- <ul><li>A <dfn id="concept-event-stream-reconnection-time" title="concept-event-stream-reconnection-time">reconnection
- time</dfn>, in milliseconds. This must initially be a
- user-agent-defined value, probably in the region of a few
+ <ul><li>A <dfn id="concept-event-stream-reconnection-time" title="concept-event-stream-reconnection-time">reconnection time</dfn>, in
+ milliseconds. This must initially be a user-agent-defined value, probably in the region of a few
seconds.</li>
- <li>A <dfn id="concept-event-stream-last-event-id" title="concept-event-stream-last-event-id">last event
- ID string</dfn>. This must initially be the empty string.</li>
+ <li>A <dfn id="concept-event-stream-last-event-id" title="concept-event-stream-last-event-id">last event ID string</dfn>. This must
+ initially be the empty string.</li>
</ul><p>These values are not currently exposed on the interface.</p>
<h2 id="processing-model"><span class="secno">5 </span>Processing model</h2>
- <p>The resource indicated in the argument to the <code title="dom-EventSource"><a href="#dom-eventsource">EventSource</a></code> constructor is <span title="fetch">fetched</span> when the constructor is run.</p>
+ <p>The resource indicated in the argument to the <code title="dom-EventSource"><a href="#dom-eventsource">EventSource</a></code>
+ constructor is <span title="fetch">fetched</span> when the constructor is run.</p>
- <p>For HTTP connections, the <code title="">Accept</code> header may
- be included; if included, it must contain only formats of event
- framing that are supported by the user agent (one of which must be
- <code><a href="#text-event-stream">text/event-stream</a></code>, as described below).</p>
+ <p>For HTTP connections, the <code title="">Accept</code> header may be included; if included, it
+ must contain only formats of event framing that are supported by the user agent (one of which must
+ be <code><a href="#text-event-stream">text/event-stream</a></code>, as described below).</p>
<p>If the event source's <a href="#concept-event-stream-last-event-id" title="concept-event-stream-last-event-id">last event ID
- string</a> is not the empty string, then a <code title="http-last-event-id"><a href="#last-event-id">Last-Event-ID</a></code> HTTP header must be
- included with the request, whose value is the value of the event
- source's <a href="#concept-event-stream-last-event-id" title="concept-event-stream-last-event-id">last event
- ID string</a>, encoded as UTF-8.</p>
-
- <p>User agents should use the <code>Cache-Control: no-cache</code>
- header in requests to bypass any caches for requests of event
- sources. (This header is not a <span title="custom request
- headers">custom request header</span>, so the user agent will still
- use the CORS <span>simple cross-origin request</span> mechanism.)
- User agents should ignore HTTP cache headers in the response, never
- caching event sources.</p>
-
- <hr><p>As data is received, the <span title="concept-task">tasks</span>
- queued by the <span>networking task source</span> to handle the data
- must act as follows.</p>
-
- <p>HTTP 200 OK responses with a <span>Content-Type</span> header
- specifying the type <code><a href="#text-event-stream">text/event-stream</a></code>, ignoring any
- <span>MIME type</span> parameters, must be processed line by line <a href="#event-stream-interpretation">as described below</a>.</p>
-
- <p>When a successful response with a supported <span>MIME
- type</span> is received, such that the user agent begins parsing the
- contents of the stream, the user agent must <a href="#announce-the-connection">announce the
+ string</a> is not the empty string, then a <code title="http-last-event-id"><a href="#last-event-id">Last-Event-ID</a></code> HTTP header must be included with the request,
+ whose value is the value of the event source's <a href="#concept-event-stream-last-event-id" title="concept-event-stream-last-event-id">last event ID string</a>, encoded as UTF-8.</p>
+
+ <p>User agents should use the <code>Cache-Control: no-cache</code> header in requests to bypass
+ any caches for requests of event sources. (This header is not a <span title="custom request
+ headers">custom request header</span>, so the user agent will still use the CORS <span>simple
+ cross-origin request</span> mechanism.) User agents should ignore HTTP cache headers in the
+ response, never caching event sources.</p>
+
+ <hr><p>As data is received, the <span title="concept-task">tasks</span> queued by the <span>networking
+ task source</span> to handle the data must act as follows.</p>
+
+ <p>HTTP 200 OK responses with a <span>Content-Type</span> header specifying the type
+ <code><a href="#text-event-stream">text/event-stream</a></code>, ignoring any <span>MIME type</span> parameters, must be processed
+ line by line <a href="#event-stream-interpretation">as described below</a>.</p>
+
+ <p>When a successful response with a supported <span>MIME type</span> is received, such that the
+ user agent begins parsing the contents of the stream, the user agent must <a href="#announce-the-connection">announce the
connection</a>.</p>
<p>The <span title="concept-task">task</span> that the <span>networking task source</span> places
@@ -751,36 +727,31 @@
<p>For non-HTTP protocols, UAs should act in equivalent ways.</p>
- <hr><p>When a user agent is to <dfn id="announce-the-connection">announce the connection</dfn>, the
- user agent must <span>queue a task</span> which, if the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute is
- set to a value other than <code title="dom-EventSource-CLOSED"><a href="#dom-eventsource-closed">CLOSED</a></code>, sets the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute to
- <code title="dom-EventSource-OPEN"><a href="#dom-eventsource-open">OPEN</a></code> and <span title="fire
- a simple event">fires a simple event</span> named <code title="event-open">open</code> at the <code><a href="#eventsource">EventSource</a></code>
+ <hr><p>When a user agent is to <dfn id="announce-the-connection">announce the connection</dfn>, the user agent must <span>queue a
+ task</span> which, if the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute is
+ set to a value other than <code title="dom-EventSource-CLOSED"><a href="#dom-eventsource-closed">CLOSED</a></code>, sets the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute to <code title="dom-EventSource-OPEN"><a href="#dom-eventsource-open">OPEN</a></code> and <span title="fire a simple event">fires a simple
+ event</span> named <code title="event-open">open</code> at the <code><a href="#eventsource">EventSource</a></code>
object.</p>
- <p>When a user agent is to <dfn id="reestablish-the-connection">reestablish the connection</dfn>,
- the user agent must run the following steps. These steps are run
- asynchronously, not as part of a <span title="concept-task">task</span>. (The tasks that it queues, of
- course, are run like normal tasks and not asynchronously.)</p>
+ <p>When a user agent is to <dfn id="reestablish-the-connection">reestablish the connection</dfn>, the user agent must run the
+ following steps. These steps are run asynchronously, not as part of a <span title="concept-task">task</span>. (The tasks that it queues, of course, are run like normal tasks
+ and not asynchronously.)</p>
<ol><li>
<p><span>Queue a task</span> to run the following steps:</p>
- <ol><li><p>If the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute is
- set to <code title="dom-EventSource-CLOSED"><a href="#dom-eventsource-closed">CLOSED</a></code>, abort
- the task.</li>
+ <ol><li><p>If the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute is set to
+ <code title="dom-EventSource-CLOSED"><a href="#dom-eventsource-closed">CLOSED</a></code>, abort the task.</li>
- <li><p>Set the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute to
- <code title="dom-EventSource-CONNECTING"><a href="#dom-eventsource-connecting">CONNECTING</a></code>.</li>
+ <li><p>Set the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute to <code title="dom-EventSource-CONNECTING"><a href="#dom-eventsource-connecting">CONNECTING</a></code>.</li>
- <li><p><span>Fire a simple event</span> named <code title="event-error">error</code> at the <code><a href="#eventsource">EventSource</a></code>
- object.</li>
+ <li><p><span>Fire a simple event</span> named <code title="event-error">error</code> at the
+ <code><a href="#eventsource">EventSource</a></code> object.</li>
</ol></li>
- <li><p>Wait a delay equal to the reconnection time of the event
- source.</li>
+ <li><p>Wait a delay equal to the reconnection time of the event source.</li>
<li><p>Optionally, wait some more. In particular, if the previous attempt failed, then user
agents might introduce an exponential backoff delay to avoid overloading a potentially already
@@ -788,24 +759,20 @@
connectivity, user agents might wait for the operating system to announce that the network
connection has returned before retrying.</li>
- <li><p>Wait until the aforementioned task has run, if it has not
- yet run.</li>
+ <li><p>Wait until the aforementioned task has run, if it has not yet run.</li>
<li>
<p><span>Queue a task</span> to run the following steps:</p>
- <ol><li><p>If the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute is
- not set to <code title="dom-EventSource-CONNECTING"><a href="#dom-eventsource-connecting">CONNECTING</a></code>, abort these
- steps.</li>
-
- <li><p>Perform a <span>potentially CORS-enabled
- fetch</span> of the <span>absolute URL</span> of the
- event source resource, using the same <i>referrer source</i>, and
- with the same <i>mode</i> and <i title="">origin</i>, as those used in
- the original request triggered by the <code title="dom-EventSource"><a href="#dom-eventsource">EventSource()</a></code> constructor, and
- process the resource obtained in this fashion, if any, as
- described earlier in this section.</li>
+ <ol><li><p>If the <code title="dom-EventSource-readyState"><a href="#dom-eventsource-readystate">readyState</a></code> attribute is not set
+ to <code title="dom-EventSource-CONNECTING"><a href="#dom-eventsource-connecting">CONNECTING</a></code>, abort these steps.</li>
+
+ <li><p>Perform a <span>potentially CORS-enabled fetch</span> of the <span>absolute
+ URL</span> of the event source resource, using the same <i>referrer source</i>, and with the
+ same <i>mode</i> and <i title="">origin</i>, as those
+ used in the original request triggered by the <code title="dom-EventSource"><a href="#dom-eventsource">EventSource()</a></code> constructor, and process the resource obtained in
+ this fashion, if any, as described earlier in this section.</li>
</ol></li>
@@ -904,46 +871,39 @@
<dd>
- <p><a href="#processField">Process the field</a> using the steps
- described below, using the whole line as the field name, and
- the empty string as the field value.</p>
+ <p><a href="#processField">Process the field</a> using the steps described below, using the
+ whole line as the field name, and the empty string as the field value.</p>
</dd>
- </dl><p>Once the end of the file is reached, any pending data must be
- discarded. (If the file ends in the middle of an event, before the
- final empty line, the incomplete event is not dispatched.)</p>
-
- <hr><p id="processField">The steps to <dfn title="">process the
- field</dfn> given a field name and a field value depend on the field
- name, as given in the following list. Field names must be compared
+ </dl><p>Once the end of the file is reached, any pending data must be discarded. (If the file ends in
+ the middle of an event, before the final empty line, the incomplete event is not dispatched.)</p>
+
+ <hr><p id="processField">The steps to <dfn title="">process the field</dfn> given a field name and a
+ field value depend on the field name, as given in the following list. Field names must be compared
literally, with no case folding performed.</p>
<dl class="switch"><dt>If the field name is "event"</dt>
- <dd><p>Set the <var title="">event type</var> buffer to field
- value.</dd>
+ <dd><p>Set the <var title="">event type</var> buffer to field value.</dd>
<dt>If the field name is "data"</dt>
- <dd><p>Append the field value to the <var title="">data</var>
- buffer, then append a single U+000A LINE FEED (LF) character to the
- <var title="">data</var> buffer.</dd>
+ <dd><p>Append the field value to the <var title="">data</var> buffer, then append a single U+000A
+ LINE FEED (LF) character to the <var title="">data</var> buffer.</dd>
<dt>If the field name is "id"</dt>
- <dd><p>Set the <var title="">last event ID</var> buffer to the
- field value.</dd>
+ <dd><p>Set the <var title="">last event ID</var> buffer to the field value.</dd>
<dt>If the field name is "retry"</dt>
- <dd><p>If the field value consists of only <span>ASCII digits</span>, then interpret the
- field value as an integer in base ten, and set the event stream's
- <a href="#concept-event-stream-reconnection-time" title="concept-event-stream-reconnection-time">reconnection
- time</a> to that integer. Otherwise, ignore the field.</dd>
+ <dd><p>If the field value consists of only <span>ASCII digits</span>, then interpret the field
+ value as an integer in base ten, and set the event stream's <a href="#concept-event-stream-reconnection-time" title="concept-event-stream-reconnection-time">reconnection time</a> to that integer.
+ Otherwise, ignore the field.</dd>
@@ -953,23 +913,20 @@
<dd><p>The field is ignored.</dd>
- </dl><p id="dispatchMessage">When the user agent is required to <dfn title="">dispatch the event</dfn>, then the user agent must act as
- follows:
[391 lines skipped]
Received on Wednesday, 31 July 2013 19:27:44 UTC