[html5] r2870 - [] (0) Drop <eventsource>. Replace the API with an EventSource object. Rename on [...]
whatwg at whatwg.org
whatwg at whatwg.org
Thu Feb 26 00:33:43 PST 2009
Author: ianh
Date: 2009-02-26 00:33:42 -0800 (Thu, 26 Feb 2009)
New Revision: 2870
Modified:
index
source
Log:
[] (0) Drop <eventsource>. Replace the API with an EventSource object. Rename onclosed to onclose on WebSocket. Remove the mostly worthless event definitions. I'll add more useful intro text to replace them later. Defined garbage collection specialness for WebSocket and EventSource.
Modified: index
===================================================================
--- index 2009-02-25 23:37:24 UTC (rev 2869)
+++ index 2009-02-26 08:33:42 UTC (rev 2870)
@@ -34,7 +34,7 @@
<div class=head>
<p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG src=/images/logo></a></p>
<h1>HTML 5</h1>
- <h2 class="no-num no-toc" id=draft-recommendation-—-date:-01-jan-1901>Draft Recommendation — 25 February 2009</h2>
+ <h2 class="no-num no-toc" id=draft-recommendation-—-date:-01-jan-1901>Draft Recommendation — 26 February 2009</h2>
<p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
<p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
<dl><dt>Multiple-page version:</dt>
@@ -363,8 +363,7 @@
<ol>
<li><a href=#scriptingLanguages><span class=secno>4.3.1.1 </span>Scripting languages</a></li>
<li><a href=#inline-documentation-for-external-scripts><span class=secno>4.3.1.2 </span>Inline documentation for external scripts</a></ol></li>
- <li><a href=#the-noscript-element><span class=secno>4.3.2 </span>The <code>noscript</code> element</a></li>
- <li><a href=#the-eventsource-element><span class=secno>4.3.3 </span>The <code>eventsource</code> element</a></ol></li>
+ <li><a href=#the-noscript-element><span class=secno>4.3.2 </span>The <code>noscript</code> element</a></ol></li>
<li><a href=#sections><span class=secno>4.4 </span>Sections</a>
<ol>
<li><a href=#the-body-element><span class=secno>4.4.1 </span>The <code>body</code> element</a></li>
@@ -865,39 +864,42 @@
<li><a href=#event-definitions><span class=secno>7.1 </span>Event definitions</a></li>
<li><a href=#server-sent-events><span class=secno>7.2 </span>Server-sent events</a>
<ol>
- <li><a href=#the-remoteeventtarget-interface><span class=secno>7.2.1 </span>The <code>RemoteEventTarget</code> interface</a></li>
- <li><a href=#connecting-to-an-event-stream><span class=secno>7.2.2 </span>Connecting to an event stream</a></li>
- <li><a href=#parsing-an-event-stream><span class=secno>7.2.3 </span>Parsing an event stream</a></li>
- <li><a href=#event-stream-interpretation><span class=secno>7.2.4 </span>Interpreting an event stream</a></li>
- <li><a href=#notes><span class=secno>7.2.5 </span>Notes</a></ol></li>
+ <li><a href=#server-sent-events-intro><span class=secno>7.2.1 </span>Introduction</a></li>
+ <li><a href=#the-eventsource-interface><span class=secno>7.2.2 </span>The <code>EventSource</code> interface</a></li>
+ <li><a href=#processing-model-3><span class=secno>7.2.3 </span>Processing model</a></li>
+ <li><a href=#parsing-an-event-stream><span class=secno>7.2.4 </span>Parsing an event stream</a></li>
+ <li><a href=#event-stream-interpretation><span class=secno>7.2.5 </span>Interpreting an event stream</a></li>
+ <li><a href=#notes><span class=secno>7.2.6 </span>Notes</a></li>
+ <li><a href=#garbage-collection-0><span class=secno>7.2.7 </span>Garbage collection</a></ol></li>
<li><a href=#network><span class=secno>7.3 </span>Web sockets</a>
<ol>
<li><a href=#network-intro><span class=secno>7.3.1 </span>Introduction</a></li>
<li><a href=#the-websocket-interface><span class=secno>7.3.2 </span>The <code>WebSocket</code> interface</a></li>
- <li><a href=#websocket-events><span class=secno>7.3.3 </span>WebSocket Events</a></li>
- <li><a href=#feedback-from-the-protocol><span class=secno>7.3.4 </span>Feedback from the protocol</a></li>
+ <li><a href=#feedback-from-the-protocol><span class=secno>7.3.3 </span>Feedback from the protocol</a>
+ <ol>
+ <li><a href=#garbage-collection-1><span class=secno>7.3.3.1 </span>Garbage collection</a></ol></li>
<li><a href=#websocket-protocol title="This protocol enables two-way
communication between a user agent running untrusted code running in
a controlled environment to a remote host that understands the
protocol. It is intended to fail to communicate with servers of
pre-existing protocols like SMTP or HTTP, while allowing HTTP
servers to opt-in to supporting this protocol if desired. It is
- designed to be easy to implement on the server side."><span class=secno>7.3.5 </span>The Web Socket
+ designed to be easy to implement on the server side."><span class=secno>7.3.4 </span>The Web Socket
protocol</a>
<ol>
- <li><a href=#introduction-5><span class=secno>7.3.5.1 </span>Introduction</a></li>
- <li><a href=#client-side-requirements><span class=secno>7.3.5.2 </span>Client-side requirements</a>
+ <li><a href=#introduction-5><span class=secno>7.3.4.1 </span>Introduction</a></li>
+ <li><a href=#client-side-requirements><span class=secno>7.3.4.2 </span>Client-side requirements</a>
<ol>
- <li><a href=#handshake><span class=secno>7.3.5.2.1 </span>Handshake</a></li>
- <li><a href=#data-framing><span class=secno>7.3.5.2.2 </span>Data framing</a></ol></li>
- <li><a href=#server-side-requirements><span class=secno>7.3.5.3 </span>Server-side requirements</a>
+ <li><a href=#handshake><span class=secno>7.3.4.2.1 </span>Handshake</a></li>
+ <li><a href=#data-framing><span class=secno>7.3.4.2.2 </span>Data framing</a></ol></li>
+ <li><a href=#server-side-requirements><span class=secno>7.3.4.3 </span>Server-side requirements</a>
<ol>
- <li><a href=#minimal-handshake><span class=secno>7.3.5.3.1 </span>Minimal handshake</a></li>
- <li><a href=#handshake-details><span class=secno>7.3.5.3.2 </span>Handshake details</a></li>
- <li><a href=#ws-sd-framing><span class=secno>7.3.5.3.3 </span>Data framing</a></ol></li>
- <li><a href=#closing-the-connection><span class=secno>7.3.5.4 </span>Closing the connection</a></li>
- <li><a href=#security-considerations><span class=secno>7.3.5.5 </span>Security considerations</a></li>
- <li><a href=#iana-considerations><span class=secno>7.3.5.6 </span>IANA considerations</a></ol></ol></li>
+ <li><a href=#minimal-handshake><span class=secno>7.3.4.3.1 </span>Minimal handshake</a></li>
+ <li><a href=#handshake-details><span class=secno>7.3.4.3.2 </span>Handshake details</a></li>
+ <li><a href=#ws-sd-framing><span class=secno>7.3.4.3.3 </span>Data framing</a></ol></li>
+ <li><a href=#closing-the-connection><span class=secno>7.3.4.4 </span>Closing the connection</a></li>
+ <li><a href=#security-considerations><span class=secno>7.3.4.5 </span>Security considerations</a></li>
+ <li><a href=#iana-considerations><span class=secno>7.3.4.6 </span>IANA considerations</a></ol></ol></li>
<li><a href=#crossDocumentMessages><span class=secno>7.4 </span>Cross-document messaging</a>
<ol>
<li><a href=#introduction-6><span class=secno>7.4.1 </span>Introduction</a></li>
@@ -7062,7 +7064,6 @@
attribute <a href=#function>Function</a> <a href=#handler-onkeypress title=handler-onkeypress>onkeypress</a>;
attribute <a href=#function>Function</a> <a href=#handler-onkeyup title=handler-onkeyup>onkeyup</a>;
attribute <a href=#function>Function</a> <a href=#handler-onload title=handler-onload>onload</a>;
- attribute <a href=#function>Function</a> <a href=#handler-onmessage title=handler-onmessage>onmessage</a>;
attribute <a href=#function>Function</a> <a href=#handler-onmousedown title=handler-onmousedown>onmousedown</a>;
attribute <a href=#function>Function</a> <a href=#handler-onmousemove title=handler-onmousemove>onmousemove</a>;
attribute <a href=#function>Function</a> <a href=#handler-onmouseout title=handler-onmouseout>onmouseout</a>;
@@ -7122,7 +7123,6 @@
<li><code title=handler-onkeypress><a href=#handler-onkeypress>onkeypress</a></code></li>
<li><code title=handler-onkeyup><a href=#handler-onkeyup>onkeyup</a></code></li>
<li><code title=handler-onload><a href=#handler-onload>onload</a></code>*</li>
- <li><code title=handler-onmessage><a href=#handler-onmessage>onmessage</a></code>*</li>
<li><code title=handler-onmousedown><a href=#handler-onmousedown>onmousedown</a></code></li>
<li><code title=handler-onmousemove><a href=#handler-onmousemove>onmousemove</a></code></li>
<li><code title=handler-onmouseout><a href=#handler-onmouseout>onmouseout</a></code></li>
@@ -7132,10 +7132,11 @@
<li><code title=handler-onscroll><a href=#handler-onscroll>onscroll</a></code></li>
<li><code title=handler-onselect><a href=#handler-onselect>onselect</a></code></li>
<li><code title=handler-onsubmit><a href=#handler-onsubmit>onsubmit</a></code></li>
- </ul><p class=note>The attributes marked with an asterisk cannot be
- specified on <code><a href=#the-body-element>body</a></code> elements as those elements expose
- <a href=#event-handler-attributes-0>event handler attributes</a> of the <code><a href=#window>Window</a></code>
- object with the same names.</p>
+ </ul><p class=note>The attribute<!--s--> marked with an asterisk cannot
+ be specified on <code><a href=#the-body-element>body</a></code> elements as those elements expose
+ <!---->an<!----> <a href=#event-handler-attributes-0 title="event handler attributes">event
+ handler attribute<!--s--></a> of the <code><a href=#window>Window</a></code> object
+ with the same name<!--s-->.</p>
<hr><p>Also, <a href=#custom-data-attribute title="custom data attribute">custom data
attributes</a> (e.g. <code title="">data-foldername</code> or
@@ -10672,104 +10673,6 @@
- <h4 id=the-eventsource-element><span class=secno>4.3.3 </span>The <dfn><code>eventsource</code></dfn> element</h4>
-
- <dl class=element><dt>Categories</dt>
- <dd><a href=#metadata-content-0>Metadata content</a>.</dd>
- <dd><a href=#flow-content-0>Flow content</a>.</dd>
- <dd><a href=#phrasing-content-0>Phrasing content</a>.</dd>
- <dt>Contexts in which this element may be used:</dt>
- <dd>Where <a href=#metadata-content-0>metadata content</a> is expected.</dd>
- <dd>Where <a href=#phrasing-content-0>phrasing content</a> is expected.</dd>
- <dt>Content model:</dt>
- <dd>Empty.</dd>
- <dt>Content attributes:</dt>
- <dd><a href=#global-attributes>Global attributes</a></dd>
- <dd><code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code></dd>
- <dt>DOM interface:</dt>
- <dd>
-<pre class=idl>interface <dfn id=htmleventsourceelement>HTMLEventSourceElement</dfn> : <a href=#htmlelement>HTMLElement</a> {
- attribute DOMString <a href=#dom-eventsource-src title=dom-eventsource-src>src</a>;
-};</pre>
- </dd>
- </dl><p>The <code><a href=#the-eventsource-element>eventsource</a></code> element <a href=#represents>represents</a> a
- target for events generated by a remote server.</p>
-
- <p>The <dfn id=attr-eventsource-src title=attr-eventsource-src><code>src</code></dfn>
- attribute, if specified, must give a <a href=#valid-url>valid URL</a>
- identifying a resource that uses the <code>text/event-stream</code>
- format.</p>
-
- <p>When an <code><a href=#the-eventsource-element>eventsource</a></code> element with a <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code> attribute specified is <a href=#insert-an-element-into-a-document title="insert an element into a document">inserted into the
- document</a>, and when an <code><a href=#the-eventsource-element>eventsource</a></code> element that
- is already in the document<!--XXX xref--> has a <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code> attribute added, the user
- agent must run the <a href=#add-declared-event-source>add declared event source</a>
- algorithm.</p>
-
- <p>While an <code><a href=#the-eventsource-element>eventsource</a></code> element is in a document<!--
- XXX xref -->, if its <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code>
- attribute is mutated, the user agent must must run the <a href=#remove-declared-event-source>remove
- declared event source</a> algorithm followed by the <a href=#add-declared-event-source>add
- declared event source</a> algorithm.</p>
-
- <p>When an <code><a href=#the-eventsource-element>eventsource</a></code> element with a <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code> attribute specified is
- removed from a document<!-- XXX xref -->, and when an
- <code><a href=#the-eventsource-element>eventsource</a></code> element that is in a document<!--XXX
- xref--> with a <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code>
- attribute specified has its <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code> attribute removed, the user
- agent must run the <a href=#remove-declared-event-source>remove declared event source</a>
- algorithm.</p>
-
- <!-- changing the base URL doesn't trigger these algorithms -->
-
- <p>When it is created, an <code><a href=#the-eventsource-element>eventsource</a></code> element must
- have its <i>current declared event source</i> set to
- "undefined".</p>
-
- <p>The <dfn id=add-declared-event-source>add declared event source</dfn> algorithm is as
- follows:</p>
-
- <ol><li><a href=#resolve-a-url title="resolve a url">Resolve</a> the <a href=#url>URL</a>
- specified by the <code><a href=#the-eventsource-element>eventsource</a></code> element's <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code> attribute, relative to the
- element.</li>
-
- <li>If that fails, then set the element's <i>current declared event
- source</i> to "undefined" and abort these steps.</li>
-
- <li>Otherwise, add the resulting <a href=#absolute-url>absolute URL</a> to the
- <a href=#concept-eventsource-list title=concept-eventsource-list>list of event sources</a>
- for the element.</li>
-
- <li>Let the element's <i>current declared event source</i> be that
- <a href=#absolute-url>absolute URL</a>.</li>
-
- </ol><p>The <dfn id=remove-declared-event-source>remove declared event source</dfn> algorithm is as
- follows:</p>
-
- <ol><li>If the element's <i>current declared event source</i> is
- "undefined", abort these steps.</li>
-
- <li>Otherwise, remove the element's <i>current declared event
- source</i> from the <a href=#concept-eventsource-list title=concept-eventsource-list>list of
- event sources</a> for the element.</li>
-
- <li>Let the element's <i>current declared event source</i> be
- "undefined".</li>
-
- </ol><p>There can be more than one <code><a href=#the-eventsource-element>eventsource</a></code> element per
- document, but authors should take care to avoid opening multiple
- connections to the same server as HTTP recommends a limit to the
- number of simultaneous connections that a user agent can open per
- server.</p>
-
- <!-- v2: make 'load', 'error', 'abort' events fire on this element -->
-
- <p>The <dfn id=dom-eventsource-src title=dom-eventsource-src><code>src</code></dfn> DOM
- attribute must <a href=#reflect>reflect</a> the content attribute of the
- same name.</p>
-
-
-
<h3 id=sections><span class=secno>4.4 </span>Sections</h3>
<p id=applyToSection>Some elements, for example
@@ -10835,22 +10738,22 @@
attributes</a> of the <code><a href=#window>Window</a></code> object. It also mirrors
their <a href=#event-handler-dom-attributes>event handler DOM attributes</a>.</p>
- <p>The <code title=handler-window-onerror><a href=#handler-window-onerror>onerror</a></code> and <code title=handler-window-onmessage><a href=#handler-window-onmessage>onmessage</a></code> <a href=#event-handler-attributes-0>event
- handler attributes</a> of the <code><a href=#window>Window</a></code> object, exposed
- on the <code><a href=#the-body-element>body</a></code> element, shadow the generic <code title=handler-onerror><a href=#handler-onerror>onerror</a></code> and <code title=handler-onmessage><a href=#handler-onmessage>onmessage</a></code> <a href=#event-handler-attributes-0>event handler
- attributes</a> normally supported by <a href=#html-elements>HTML
- elements</a>.</p>
+ <p>The <code title=handler-window-onerror><a href=#handler-window-onerror>onerror</a></code> <a href=#event-handler-attributes-0 title="event handler attributes">event handler
+ attribute<!--s--></a> of the <code><a href=#window>Window</a></code> object, exposed
+ on the <code><a href=#the-body-element>body</a></code> element, shadow<!---->s<!----> the generic
+ <code title=handler-onerror><a href=#handler-onerror>onerror</a></code> <a href=#event-handler-attributes-0 title="event
+ handler attributes">event handler attribute<!--s--></a> normally
+ supported by <a href=#html-elements>HTML elements</a>.</p>
- <p class=example>Thus, for example, a bubbling <code title=event-message><a href=#event-message>message</a></code> event fired on a child of
- <a href=#the-body-element-0>the body element</a> of a <code>Document</code> would first
- trigger the <code title=handler-onmessage><a href=#handler-onmessage>onmessage</a></code>
- <a href=#event-handler-content-attributes>event handler content attributes</a> of that element, then
- that of the root <code><a href=#the-html-element>html</a></code> element, and only <em>then</em>
- would it trigger the <code title=handler-window-onmessage><a href=#handler-window-onmessage>onmessage</a></code> <a href=#event-handler-content-attributes title="event
- handler content attributes">event handler content attribute</a>
- on the <code><a href=#the-body-element>body</a></code> element. This is because the event would
- bubble from the target, to the <code><a href=#the-body-element>body</a></code>, to the
- <code><a href=#the-html-element>html</a></code>, to the <code>Document</code>, to the
+ <p class=example>Thus, for example, a bubbling <code title=event-error><a href=#event-error>error</a></code> event fired on a child of <a href=#the-body-element-0>the
+ body element</a> of a <code>Document</code> would first trigger
+ the <code title=handler-onerror><a href=#handler-onerror>onerror</a></code> <a href=#event-handler-content-attributes>event handler
+ content attributes</a> of that element, then that of the root
+ <code><a href=#the-html-element>html</a></code> element, and only <em>then</em> would it trigger
+ the <code title=handler-window-onerror><a href=#handler-window-onerror>onerror</a></code> <a href=#event-handler-content-attributes title="event handler content attributes">event handler content
+ attribute</a> on the <code><a href=#the-body-element>body</a></code> element. This is because
+ the event would bubble from the target, to the <code><a href=#the-body-element>body</a></code>, to
+ the <code><a href=#the-html-element>html</a></code>, to the <code>Document</code>, to the
<code><a href=#window>Window</a></code>, and the event handler attribute on the
<code><a href=#the-body-element>body</a></code> is watching the <code><a href=#window>Window</a></code> not the
<code><a href=#the-body-element>body</a></code>. A regular event listener attached to the
@@ -22768,7 +22671,7 @@
<h4 id=dimension-attributes><span class=secno>4.8.17 </span><dfn>Dimension attributes</dfn></h4>
- <p>The <dfn id=attr-dim-width title=attr-dim-width><code>width</code></dfn> and <dfn id=attr-dim-height title=attr-dim-height><code>height</code></dfn> attributes on
+ <p><strong>Author requirements:</strong> The <dfn id=attr-dim-width title=attr-dim-width><code>width</code></dfn> and <dfn id=attr-dim-height title=attr-dim-height><code>height</code></dfn> attributes on
<code><a href=#the-img-element>img</a></code>, <code><a href=#the-iframe-element>iframe</a></code>, <code><a href=#the-embed-element>embed</a></code>,
<code><a href=#the-object-element>object</a></code>, <code><a href=#video>video</a></code>, and, when their <code title=attr-input-type><a href=#attr-input-type>type</a></code> attribute is in the <a href=#image-button-state title=attr-input-type-image>Image Button</a> state,
<code><a href=#the-input-element>input</a></code> elements may be specified to give the dimensions
@@ -22803,7 +22706,9 @@
<p class=note>Basically, the dimension attributes can't be used to
stretch the image.</p>
- <p>User agents are expected to use these attributes <a href=#dimRendering>as hints for the rendering</a>.</p>
+ <p><strong>User agent requirements:</strong> User agents are
+ expected to use these attributes <a href=#dimRendering>as hints
+ for the rendering</a>.</p>
<p>The <dfn id=dom-dim-width title=dom-dim-width><code>width</code></dfn> and <dfn id=dom-dim-height title=dom-dim-height><code>height</code></dfn> DOM attributes on
the <code><a href=#the-iframe-element>iframe</a></code>, <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-object-element>object</a></code>,
@@ -36711,11 +36616,6 @@
<dd><p>Must be invoked whenever a <code title=event-load><a href=#event-load>load</a></code> event is targeted at or bubbles
through the element.</dd>
- <dt><dfn id=handler-onmessage title=handler-onmessage><code>onmessage</code></dfn></dt> <!-- new for <eventsource> -->
-
- <dd><p>Must be invoked whenever a <code title=event-message><a href=#event-message>message</a></code> event is targeted at or bubbles
- through the element.</dd>
-
</dl><hr><p>The following are the event handler attributes that must be
supported by <code><a href=#window>Window</a></code> objects, as DOM attributes on the
<code><a href=#window>Window</a></code> object, and with corresponding content
@@ -45700,170 +45600,194 @@
attribute must be null.</p>
+
<h3 id=server-sent-events><span class=secno>7.2 </span><dfn>Server-sent events</dfn></h3>
<!-- eventsource -->
- <p>This section describes a mechanism for allowing servers to
- dispatch DOM events into documents that expect it. The
- <code><a href=#the-eventsource-element>eventsource</a></code> element provides a simple interface to
- this mechanism.</p>
+ <h4 id=server-sent-events-intro><span class=secno>7.2.1 </span>Introduction</h4>
+ <p><em>This section is non-normative.</em></p>
+ <p>To enable servers to push data to Web pages over HTTP or using
+ dedicated server-push protocols, this specification introduces the
+ <code><a href=#eventsource>EventSource</a></code> interface.</p>
- <h4 id=the-remoteeventtarget-interface><span class=secno>7.2.1 </span>The <code><a href=#remoteeventtarget>RemoteEventTarget</a></code> interface</h4>
+ <p class=XXX>An introduction to the client-side and
+ server-side of using the direct connection APIs.</p>
- <p>Any object that implements the <code>EventTarget</code> interface
- must also implement the <code><a href=#remoteeventtarget>RemoteEventTarget</a></code>
- interface.</p>
+ <!--BOILERPLATE-->
- <pre class=idl>[NoInterfaceObject, ImplementedOn=<span>EventTarget</span>] interface <dfn id=remoteeventtarget>RemoteEventTarget</dfn> {
- void <a href=#dom-remoteeventtarget-addeventsource title=dom-RemoteEventTarget-addEventSource>addEventSource</a>(in DOMString src);
- void <a href=#dom-remoteeventtarget-removeeventsource title=dom-RemoteEventTarget-removeEventSource>removeEventSource</a>(in DOMString src);
+ <h4 id=the-eventsource-interface><span class=secno>7.2.2 </span>The <code><a href=#eventsource>EventSource</a></code> interface</h4>
+
+ <pre class=idl>[<a href=#dom-eventsource title=dom-EventSource>Constructor</a>(in DOMString url)]
+interface <dfn id=eventsource>EventSource</dfn> {
+ readonly attribute DOMString <a href=#dom-eventsource-url title=dom-EventSource-URL>URL</a>;
+
+ // ready state
+ const unsigned short <a href=#dom-eventsource-connecting title=dom-EventSource-CONNECTING>CONNECTING</a> = 0;
+ const unsigned short <a href=#dom-eventsource-open title=dom-EventSource-OPEN>OPEN</a> = 1;
+ const unsigned short <a href=#dom-eventsource-closed title=dom-EventSource-CLOSED>CLOSED</a> = 2;
+ readonly attribute long <a href=#dom-eventsource-readystate title=dom-EventSource-readyState>readyState</a>;
+
+ // networking
+ attribute <a href=#function>Function</a> <a href=#handler-eventsource-onopen title=handler-EventSource-onopen>onopen</a>;
+ attribute <a href=#function>Function</a> <a href=#handler-eventsource-onmessage title=handler-EventSource-onmessage>onmessage</a>;
+ attribute <a href=#function>Function</a> <a href=#handler-eventsource-onerror title=handler-EventSource-onerror>onerror</a>;
+ void <a href=#dom-eventsource-disconnect title=dom-EventSource-disconnect>disconnect</a>();
};</pre>
- <p>When the <dfn id=dom-remoteeventtarget-addeventsource title=dom-RemoteEventTarget-addEventSource><code>addEventSource(<var title="">src</var>)</code></dfn> method is invoked, the user agent
- must <a href=#resolve-a-url title="resolve a url">resolve</a> the <a href=#url>URL</a>
- specified in <var title="">src</var>, relative to the <a href=#first-script>first
- script</a>'s <a href="#script's-base-url" title="script's base URL">base URL</a>, and
- if that succeeds, add the resulting <a href=#absolute-url>absolute URL</a> to the
- <a href=#concept-eventsource-list title=concept-eventsource-list>list of event sources</a>
- for that object. The same URL can be registered multiple times. If
- the URL fails to resolve, then the user agent must raise a
- <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception.</p>
+ <p><code><a href=#eventsource>EventSource</a></code> objects must also implement the
+ <code>EventTarget</code> interface. <a href=#refsDOM3EVENTS>[DOM3EVENTS]</a></p>
- <p>When the <dfn id=dom-remoteeventtarget-removeeventsource title=dom-RemoteEventTarget-removeEventSource><code>removeEventSource(<var title="">src</var>)</code></dfn> method is invoked, the user agent
- must <a href=#resolve-a-url title="resolve a url">resolve</a> the <a href=#url>URL</a>
- specified in <var title="">src</var>, relative to the <a href=#first-script>first
- script</a>'s <a href="#script's-base-url" title="script's base URL">base URL</a>, and
- if that succeeds, remove the resulting <a href=#absolute-url>absolute URL</a>
- from the <a href=#concept-eventsource-list title=concept-eventsource-list>list of event
- sources</a> for that object. If the same URL has been registered
- multiple times, removing it must remove only one instance of that
- URL for each invocation of the <code title=removeEventSource>removeEventSource()</code> method. If the
- URL fails to resolve, the user agent does nothing.</p>
+ <p>The <dfn id=dom-eventsource title=dom-EventSource><code>EventSource(<var title="">url</var>)</code></dfn> constructor takes one argument,
+ <var title="">url</var>, which specifies the <a href=#url>URL</a> to
+ which to connect. When the <code>EventSource()</code> constructor is
+ invoked, the UA must run these steps:</p>
+ <ol><li><p><a href=#resolve-a-url title="resolve a url">Resolve</a> the
+ <a href=#url>URL</a> specified in <var title="">src</var>, relative to
+ the <a href=#first-script>first script</a>'s <a href="#script's-base-url" title="script's base
+ URL">base URL</a>.</li>
- <h4 id=connecting-to-an-event-stream><span class=secno>7.2.2 </span>Connecting to an event stream</h4>
+ <li><p>If the previous step failed, then throw a
+ <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception.</li>
- <p>Each object implementing the <code>EventTarget</code> and
- <code><a href=#remoteeventtarget>RemoteEventTarget</a></code> interfaces has a <dfn id=concept-eventsource-list title=concept-eventsource-list>list of event sources</dfn> that
- are registered for that object.</p>
+ <li><p>Return a new <code><a href=#eventsource>EventSource</a></code> object, and continue
+ these steps in the background (without blocking scripts).</li>
- <p>When a new <a href=#absolute-url>absolute URL</a> is added to this list, the
- user agent should <a href=#queue-a-task>queue a task</a> to run the following
- steps with the new <a href=#absolute-url>absolute URL</a>:</p>
+ <li><p><a href=#fetch>Fetch</a> the resource identified by the resulting
+ <a href=#absolute-url>absolute URL</a>, as described below.</li>
- <ol><li><p>If the entry for the new <a href=#absolute-url>absolute URL</a> has been
- removed from the list, then abort these steps.</li>
+ </ol><p>The <dfn id=dom-eventsource-url title=dom-EventSource-URL><code>URL</code></dfn>
+ attribute must return the value that was passed to the
+ constructor.</p>
- <li>
+ <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>
- <p><a href=#fetch>Fetch</a> the resource identified by that
- <a href=#absolute-url>absolute URL</a>.</p>
+ <dl><dt><dfn id=dom-eventsource-connecting title=dom-EventSource-CONNECTING><code>CONNECTING</code></dfn> (numeric value 0)</dt>
- <p>As data is received, the <a href=#concept-task title=concept-task>tasks</a> queued by the <a href=#networking-task-source>networking
- task source</a> to handle the data must consist of following
- the rules given in the following sections.</p>
+ <dd>The connection has not yet been established, or it was closed
+ and the user agent is reconnecting.</dd>
- </li>
+ <dt><dfn id=dom-eventsource-open title=dom-EventSource-OPEN><code>OPEN</code></dfn> (numeric value 1)</dt>
- </ol><p>When an event source is removed from the list of event sources
- for an object, if that resource is still being fetched, then the
- relevant connection must be closed.</p>
+ <dd>The user agent has an open connection and is dispatching events
+ as it receives them.</dd>
- <p>Since connections established to remote servers for such
- resources are expected to be long-lived, UAs should ensure that
- appropriate buffering is used. In particular, while line buffering
- may be safe if lines are defined to end with a single U+000A LINE
- FEED character, block buffering or line buffering with different
- expected line endings can cause delays in event dispatch.</p>
+ <dt><dfn id=dom-eventsource-closed title=dom-EventSource-CLOSED><code>CLOSED</code></dfn> (numeric value 2)</dt>
- <p>Each event source in the list must have associated with it the
- following:</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-disconnect><a href=#dom-eventsource-disconnect>disconnect()</a></code> method was
+ invoked.</dd>
- <ul><li>The <dfn id=concept-event-stream-reconnection-time title=concept-event-stream-reconnection-time>reconnection
+ </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-disconnect title=dom-EventSource-disconnect><code>disconnect()</code></dfn>
+ method must close the connection, if any, 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>. If the
+ connection is already closed, the method must do nothing.</p>
+
+ <p>The following are the <a href=#event-handler-attributes-0>event handler attributes</a> that
+ must be supported, as DOM attributes, by all objects implementing
+ the <code><a href=#eventsource>EventSource</a></code> interface:</p>
+
+ <dl><dt><dfn id=handler-eventsource-onopen title=handler-EventSource-onopen><code>onopen</code></dfn></dt>
+
+ <dd><p>Must be invoked whenever an <code title=event-open>open</code> event is targeted at or
+ bubbles through the <code><a href=#eventsource>EventSource</a></code> object.</dd>
+
+ <dt><dfn id=handler-eventsource-onmessage title=handler-EventSource-onmessage><code>onmessage</code></dfn></dt>
+
+ <dd><p>Must be invoked whenever a <code title=event-message><a href=#event-message>message</a></code> event is targeted at or
+ bubbles through the <code><a href=#eventsource>EventSource</a></code> object.</dd>
+
+ <dt><dfn id=handler-eventsource-onerror title=handler-EventSource-onerror><code>onerror</code></dfn></dt>
+
+ <dd><p>Must be invoked whenever an <code title=event-error><a href=#event-error>error</a></code> event is targeted at or
+ bubbles through the <code><a href=#eventsource>EventSource</a></code> object.</dd>
+
+ </dl><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
seconds.</li>
- <li>The <dfn id=concept-event-stream-last-event-id title=concept-event-stream-last-event-id>last event
+ <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>In general, the semantics of the transport protocol specified by
- the URLs for the event sources must be followed, including HTTP
- caching rules.</p>
+ </ul><p>These values are not currently exposed on the interface.</p>
+
+ <h4 id=processing-model-3><span class=secno>7.2.3 </span>Processing model</h4>
+
+ <p>The resource indicated in the argument to the <code title=dom-EventSource><a href=#dom-eventsource>EventSource</a></code> constructor is <a href=#fetch title=fetch>fetched</a> 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>text/event-stream</code>, as described below).</p>
- <p>Other formats of event framing may also be supported in addition
- to <code>text/event-stream</code>, but this specification does not
- define how they are to be parsed or processed.</p>
-
- <p class=note>Such formats could include systems like SMS-push;
- for example servers could use <code title="">Accept</code> headers
- and HTTP redirects to an SMS-push mechanism as a kind of protocol
- negotiation to reduce network load in GSM environments.</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.</p>
-
<p>If the event source's last event ID string is not the empty
string, then a <code title="">Last-Event-ID</code> HTTP header must
be included with the request, whose value is the value of the event
source's last event ID string.</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. User agents should ignore HTTP cache headers in the
+ response, never caching event sources.</p>
+
<p class=XXX>Cross-origin loads are expected to follow the
Access-Control semantics of CORS; without this header, they are
expected to fail as if the site was down.</p>
+ <hr><p>As data is received, the <a href=#concept-task title=concept-task>tasks</a>
+ queued by the <a href=#networking-task-source>networking task source</a> to handle the data
+ must act as follows.</p>
+
<p>HTTP 200 OK responses with a <a href=#content-type-0>Content-Type</a> header
specifying the type <code>text/event-stream</code> must be processed
line by line <a href=#event-stream-interpretation>as described
below</a>.</p>
- <p>For the purposes of such successfully opened event streams only,
- user agents should ignore HTTP cache headers, and instead assume
- that the resource indicates that it does not wish to be cached.</p>
+ <p>When a successful response with a supported MIME type 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>If such a resource (with the correct MIME type) completes loading
(i.e. the entire HTTP response body is received or the connection
- itself closes), the user agent should request the event source
- resource again after a delay equal to the reconnection time of the
- event source. This doesn't apply for the error cases that are listed
- below.</p>
+ itself closes), the user agent must <a href=#reset-the-connection>reset the
+ connection</a>. This doesn't apply for the error cases that are
+ listed below.</p>
<p>HTTP 200 OK responses that have a <a href=#content-type-0>Content-Type</a> other
than <code>text/event-stream</code> (or some other supported type)
- must be ignored.</p>
+ must cause the user agent to <a href=#fail-the-connection>fail the connection</a>.</p>
- <p>HTTP 204 No Content, and 205 Reset Content responses must be
- treated as if they were 200 OK responses with the right MIME type
- but no content, and should therefore cause the user agent to refetch
- the resource after a delay equal to the reconnection time of the
- event source.</p>
+ <p>HTTP 204 No Content, and 205 Reset Content responses are
+ equivalent to 200 OK responses with the right MIME type but no
+ content, and thus must <a href=#reset-the-connection>reset the connection</a>.</p>
<p>Other HTTP response codes in the 2xx range <!--201 Created, 202
Accepted, 203 Non-Authoritative Information, and 206 Partial
- Content-->must be treated like HTTP 200 OK responses for the
- purposes of reopening event source resources. They are, however,
- likely to indicate an error has occurred somewhere and may cause the
- user agent to emit a warning.</p>
+ Content-->must similarly <a href=#reset-the-connection>reset the connection</a>. They
+ are, however, likely to indicate an error has occurred somewhere and
+ may cause the user agent to emit a warning.</p>
- <p>HTTP 300 Multiple Choices responses should be handled
- automatically if possible (treating the responses as if they were
- 302 Found responses pointing to the appropriate resource), and
- otherwise must be treated as HTTP 404 responses.</p>
-
<p>HTTP 301 Moved Permanently responses must cause the user agent to
reconnect using the new server specified URL instead of the
previously specified URL for all subsequent requests for this event
- source. (It doesn't affect other event sources with the same URL
- unless they also receive 301 responses, and it doesn't affect future
- sessions, e.g. if the page is reloaded.)</p>
+ source. (It doesn't affect other <code><a href=#eventsource>EventSource</a></code> objects
+ with the same URL unless they also receive 301 responses, and it
+ doesn't affect future sessions, e.g. if the page is reloaded.)</p>
<p>HTTP 302 Found, 303 See Other, and 307 Temporary Redirect
responses must cause the user agent to connect to the new
@@ -45871,33 +45795,52 @@
the resource at a later point, it must return to the previously
specified URL for this event source.</p>
- <p>HTTP 304 Not Modified responses should be handled like HTTP 200
- OK responses, with the content coming from the user agent cache. A
- new request should then be made after a delay equal to the
- reconnection time of the event source.</p>
-
<p>HTTP 305 Use Proxy, HTTP 401 Unauthorized, and 407 Proxy
Authentication Required should be treated transparently as for any
other subresource.</p>
<p>Any other HTTP response code not listed here or network error
- (e.g. DNS errors) must be ignored.</p> <!-- including: HTTP 400 Bad
- Request, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 406
- Not Acceptable, 408 Request Timeout, 409 Conflict, 410 Gone, 411
- Length Required, 412 Precondition Failed, 413 Request Entity Too
- Large, 414 Request-URI Too Long, 415 Unsupported Media Type, 416
- Requested Range Not Satisfiable, 417 Expectation Failed, 500
- Internal Server Error, 501 Not Implemented, 502 Bad Gateway, 503
- Service Unavailable, 504 Gateway Timeout, and 505 HTTP Version Not
- Supported responses -->
+ (e.g. DNS errors) must cause the user agent to <a href=#fail-the-connection>fail the
+ connection</a>.</p> <!-- including: HTTP 300 Multiple Choices,
+ HTTP 304 Not Modified, HTTP 400 Bad Request, 403 Forbidden, 404 Not
+ Found, 405 Method Not Allowed, 406 Not Acceptable, 408 Request
+ Timeout, 409 Conflict, 410 Gone, 411 Length Required, 412
+ Precondition Failed, 413 Request Entity Too Large, 414 Request-URI
+ Too Long, 415 Unsupported Media Type, 416 Requested Range Not
+ Satisfiable, 417 Expectation Failed, 500 Internal Server Error, 501
+ Not Implemented, 502 Bad Gateway, 503 Service Unavailable, 504
+ Gateway Timeout, and 505 HTTP Version Not Supported responses -->
<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 set 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 <a href=#queue-a-task>queue a
+ task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-open>open</code> at the
+ <code><a href=#eventsource>EventSource</a></code> object.</p>
- <h4 id=parsing-an-event-stream><span class=secno>7.2.3 </span>Parsing an event stream</h4>
+ <p>When a user agent is to <dfn id=reset-the-connection>reset the connection</dfn>, the user
+ agent must 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>,
+ <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named
+ <code title=event-error><a href=#event-error>error</a></code> at the
+ <code><a href=#eventsource>EventSource</a></code> object, and then <a href=#fetch>fetch</a> the
+ event source resource again after a delay equal to the reconnection
+ time of the event source.</p>
- <!-- XXX Wladimir Palant pointed out problems with HTTP chunking with server-sent-events -->
+ <p>When a user agent is to <dfn id=fail-the-connection>fail the connection</dfn>, the user
+ agent 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> and <a href=#queue-a-task>queue a
+ task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named <code title=event-error><a href=#event-error>error</a></code> at the
+ <code><a href=#eventsource>EventSource</a></code> object.</p>
+ <hr><p>The <a href=#task-source>task source</a> for any <a href=#concept-task title=concept-task>tasks</a> that are <a href=#queue-a-task title="queue a
+ task">queued</a> by <code><a href=#eventsource>EventSource</a></code> objects is the
+ <dfn id=remote-event-task-source>remote event task source</dfn>.</p>
+
+
+ <h4 id=parsing-an-event-stream><span class=secno>7.2.4 </span>Parsing an event stream</h4>
+
<p>This event stream format's MIME type is
<code>text/event-stream</code>.</p>
@@ -45930,9 +45873,15 @@
LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF)
character, or a single U+000D CARRIAGE RETURN (CR) character.</p>
+ <p>Since connections established to remote servers for such
+ resources are expected to be long-lived, UAs should ensure that
+ appropriate buffering is used. In particular, while line buffering
+ with lines are defined to end with a single U+000A LINE FEED
+ character is safe, block buffering or line buffering with different
+ expected line endings can cause delays in event dispatch.</p>
- <h4 id=event-stream-interpretation><span class=secno>7.2.4 </span>Interpreting an event stream</h4>
+ <h4 id=event-stream-interpretation><span class=secno>7.2.5 </span>Interpreting an event stream</h4>
<p>Bytes or sequences of bytes that are not valid UTF-8 sequences
must be interpreted as the U+FFFD REPLACEMENT CHARACTER.</p>
@@ -46077,10 +46026,7 @@
<li><p>Set the <var title="">data</var> buffer and the <var title="">event name</var> buffer to the empty string.</li>
<li><p><a href=#queue-a-task>Queue a task</a> to dispatch the newly created
- event at the <code><a href=#remoteeventtarget>RemoteEventTarget</a></code> object to which the
- event stream is registered. The <a href=#task-source>task source</a> for this
- <a href=#concept-task title=concept-task>task</a> is the <dfn id=remote-event-task-source>remote event
- task source</dfn>.</li>
+ event at the <code><a href=#eventsource>EventSource</a></code> object.</li>
</ol><p class=note>If an event doesn't have an "id" field, but an
earlier event did set the event source's <span>last event ID
@@ -46092,20 +46038,26 @@
<p>The following event stream, once followed by a blank line:</p>
<pre>data: YHOO
-data: -2
+data: +2
data: 10</pre>
<p>...would cause an event <code title=event-message><a href=#event-message>message</a></code> with the interface
<code><a href=#messageevent>MessageEvent</a></code> to be dispatched on the
- <code><a href=#the-eventsource-element>eventsource</a></code> element, whose <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute would contain
- the string <code>YHOO\n-2\n10</code> (where <code>\n</code>
+ <code><a href=#eventsource>EventSource</a></code> object. The event's <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute would contain
+ the string <code>YHOO\n+2\n10</code> (where <code>\n</code>
represents a newline).</p>
<p>This could be used as follows:
- <pre><eventsource src="http://stocks.example.com/ticker.php"
- onmessage="var data = event.data.split('\n'); updateStocks(data[0], data[1], data[2]);"></pre>
+ <pre>var stocks = new EventSource("http://stocks.example.com/ticker.php");
+stocks.onmessage = function (event) {
+ var data = event.data.split('\n');
+ updateStocks(data[0], data[1], data[2]);
+};</pre>
+
<p>...where <code title="">updateStocks()</code> is a function defined as:</p>
+
<pre>function updateStocks(symbol, delta, value) { ... }</pre>
+
<p>...or some such.</p>
</div>
@@ -46169,7 +46121,7 @@
</div>
- <h4 id=notes><span class=secno>7.2.5 </span>Notes</h4>
+ <h4 id=notes><span class=secno>7.2.6 </span>Notes</h4>
<p>Legacy proxy servers are known to, in certain cases, drop HTTP
connections after a short timeout. To protect against such proxy
@@ -46183,19 +46135,44 @@
individual IP addresses can have multiple clients (due to sharing a
proxy server). It is better to include a unique identifier in the
document when it is served and then pass that identifier as part of
- the URL in the <code title=attr-eventsource-src><a href=#attr-eventsource-src>src</a></code>
- attribute of the <code><a href=#the-eventsource-element>eventsource</a></code> element.</p>
+ the URL in the <code title=attr-eventsource-src>src</code>
+ attribute of the <code><a href=#eventsource>eventsource</a></code> element.</p>
+ <p>Authors are also cautioned that HTTP chunking can have unexpected
+ negative effects on the reliability of this protocol. Where
+ possible, chunking should be disabled for serving event streams
+ unless the rate of messages is high enough for this not to
+ matter.</p> <!-- v2 can we get a better solution? -->
+
<p>Implementations that support HTTP's per-server connection
limitation might run into trouble when opening multiple pages from a
- site if each page has an <code><a href=#the-eventsource-element>eventsource</a></code> to the same
+ site if each page has an <code><a href=#eventsource>EventSource</a></code> to the same
domain. Authors can avoid this using the relatively complex
mechanism of using unique domain names per connection, or by
- allowing the user to enable or disable the <code><a href=#the-eventsource-element>eventsource</a></code>
+ allowing the user to enable or disable the <code><a href=#eventsource>EventSource</a></code>
functionality on a per-page basis.</p>
+ <hr><p>Other formats of event framing may also be supported in addition
+ to <code>text/event-stream</code>, but this specification does not
+ define how they are to be parsed or processed.</p>
+ <p class=note>Such formats could include systems like SMS-push;
+ for example servers could use <code title="">Accept</code> headers
+ and HTTP redirects to an SMS-push mechanism as a kind of protocol
+ negotiation to reduce network load in GSM environments.</p>
+
+ <h4 id=garbage-collection-0><span class=secno>7.2.7 </span>Garbage collection</h4>
+
+ <p>An <code><a href=#eventsource>EventSource</a></code> object with an open connection must not
+ be garbage collected if there are any event listeners registered for
+ <code title=event-message><a href=#event-message>message</a></code> events.</p>
+
+ <p>If an <code><a href=#eventsource>EventSource</a></code> object is garbage collected while
+ its connection is still open, the connection must be closed.</p>
+
+
+
<h3 id=network><span class=secno>7.3 </span><dfn>Web sockets</dfn></h3>
<h4 id=network-intro><span class=secno>7.3.1 </span>Introduction</h4>
@@ -46231,7 +46208,7 @@
// networking
attribute <a href=#function>Function</a> <a href=#handler-websocket-onopen title=handler-WebSocket-onopen>onopen</a>;
attribute <a href=#function>Function</a> <a href=#handler-websocket-onmessage title=handler-WebSocket-onmessage>onmessage</a>;
- attribute <a href=#function>Function</a> <a href=#handler-websocket-onclosed title=handler-WebSocket-onclosed>onclosed</a>;
+ attribute <a href=#function>Function</a> <a href=#handler-websocket-onclose title=handler-WebSocket-onclose>onclose</a>;
void <a href=#dom-websocket-postmessage title=dom-WebSocket-postMessage>postMessage</a>(in DOMString data);
void <a href=#dom-websocket-disconnect title=dom-WebSocket-disconnect>disconnect</a>();
};</pre>
@@ -46320,37 +46297,18 @@
<p>The <dfn id=dom-websocket-disconnect title=dom-WebSocket-disconnect><code>disconnect()</code></dfn>
method must <a href=#close-the-web-socket-connection>close the Web Socket connection</a> or
connection attempt, if any. If the connection is already closed, it
- must do nothing. Closing the connection causes a <code title=event-WebSocket-close><a href=#event-websocket-close>close</a></code> event to be fired and
+ must do nothing. Closing the connection causes a <code title=event-close>close</code> event to be fired and
the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code>
attribute's value to change, as <a href=#closeWebSocket>described
below</a>.</p>
-
- <h4 id=websocket-events><span class=secno>7.3.3 </span>WebSocket Events</h4>
-
- <p>The <dfn id=event-websocket-open title=event-WebSocket-open><code>open</code></dfn>
- event is fired when the <a href=#web-socket-connection-is-established>Web Socket connection is
- established</a>.</p>
-
- <p>The <dfn id=event-websocket-close title=event-WebSocket-close><code>close</code></dfn>
- event is fired when the connection is closed (whether by the author,
- calling the <code title=dom-WebSocket-disconnect><a href=#dom-websocket-disconnect>disconnect()</a></code> method, or by
- the server, or by a network error).</p>
-
- <p class=note>No information regarding why the connection was
- closed is passed to the application in this version of this
- specification.</p>
-
- <p>The <code title=event-message><a href=#event-message>message</a></code> event is fired
- when when data is received for a connection.</p>
-
<hr><p>The following are the <a href=#event-handler-attributes-0>event handler attributes</a> that
must be supported, as DOM attributes, by all objects implementing
the <code><a href=#websocket>WebSocket</a></code> interface:</p>
<dl><dt><dfn id=handler-websocket-onopen title=handler-WebSocket-onopen><code>onopen</code></dfn></dt>
- <dd><p>Must be invoked whenever an <code title=event-WebSocket-open><a href=#event-websocket-open>open</a></code> event is targeted at or
+ <dd><p>Must be invoked whenever an <code title=event-open>open</code> event is targeted at or
bubbles through the <code><a href=#websocket>WebSocket</a></code> object.</dd>
<dt><dfn id=handler-websocket-onmessage title=handler-WebSocket-onmessage><code>onmessage</code></dfn></dt>
@@ -46358,12 +46316,12 @@
<dd><p>Must be invoked whenever a <code title=event-message><a href=#event-message>message</a></code> event is targeted at or
bubbles through the <code><a href=#websocket>WebSocket</a></code> object.</dd>
- <dt><dfn id=handler-websocket-onclosed title=handler-WebSocket-onclosed><code>onclosed</code></dfn></dt>
+ <dt><dfn id=handler-websocket-onclose title=handler-WebSocket-onclose><code>onclose</code></dfn></dt>
- <dd><p>Must be invoked whenever an <code title=event-WebSocket-closed>closed</code> event is targeted at or
+ <dd><p>Must be invoked whenever an <code title=event-close>close</code> event is targeted at or
bubbles through the <code><a href=#websocket>WebSocket</a></code> object.</dd>
- </dl><h4 id=feedback-from-the-protocol><span class=secno>7.3.4 </span>Feedback from the protocol</h4>
+ </dl><h4 id=feedback-from-the-protocol><span class=secno>7.3.3 </span>Feedback from the protocol</h4>
<p>When the <i><a href=#web-socket-connection-is-established>Web Socket connection is established</a></i>, the user
agent must run the following steps:</p>
@@ -46378,7 +46336,7 @@
<li>
<p><a href=#queue-a-task>Queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a>
- named <code title=event-WebSocket-open><a href=#event-websocket-open>open</a></code> at the
+ named <code title=event-open>open</code> at the
<code><a href=#websocket>WebSocket</a></code> object.</p>
</li>
@@ -46392,7 +46350,7 @@
closed</a></i>, the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's value
must be changed to <code title=dom-WebSocket-CLOSED><a href=#dom-websocket-closed>CLOSED</a></code>
(2), and the user agent must <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire
- a simple event</a> named <code title=event-WebSocket-close><a href=#event-websocket-close>close</a></code> at the
+ a simple event</a> named <code title=event-close>close</code> at the
<code><a href=#websocket>WebSocket</a></code> object.</p>
<hr><p>The <a href=#task-source>task source</a> for all <a href=#concept-task title=concept-task>tasks</a> <a href=#queue-a-task title="queue a
@@ -46400,14 +46358,25 @@
source</dfn>.</p>
+ <h5 id=garbage-collection-1><span class=secno>7.3.3.1 </span>Garbage collection</h5>
+ <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><a href=#event-message>message</a></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 <a href=#close-the-web-socket-connection>close the Web
+ Socket connection</a>.</p>
+
+
+
<h4 id=websocket-protocol title="This protocol enables two-way
communication between a user agent running untrusted code running in
a controlled environment to a remote host that understands the
protocol. It is intended to fail to communicate with servers of
pre-existing protocols like SMTP or HTTP, while allowing HTTP
servers to opt-in to supporting this protocol if desired. It is
- designed to be easy to implement on the server side."><span class=secno>7.3.5 </span>The Web Socket
+ designed to be easy to implement on the server side."><span class=secno>7.3.4 </span>The Web Socket
protocol</h4>
<div class=no-rfc>
@@ -46415,11 +46384,11 @@
course.</p>
</div>
- <h5 id=introduction-5><span class=secno>7.3.5.1 </span>Introduction</h5>
+ <h5 id=introduction-5><span class=secno>7.3.4.1 </span>Introduction</h5>
<p class=XXX>...</p>
- <h5 id=client-side-requirements><span class=secno>7.3.5.2 </span>Client-side requirements</h5>
+ <h5 id=client-side-requirements><span class=secno>7.3.4.2 </span>Client-side requirements</h5>
<p><em>This section only applies to user agents, not to
servers.</em></p>
@@ -46429,7 +46398,7 @@
establish to a server.</p>
- <h6 id=handshake><span class=secno>7.3.5.2.1 </span>Handshake</h6>
+ <h6 id=handshake><span class=secno>7.3.4.2.1 </span>Handshake</h6>
<p>When the user agent is to <dfn id=establish-a-web-socket-connection>establish a Web Socket
connection</dfn> to a host <var title="">host</var>, optionally on
@@ -46826,7 +46795,7 @@
distinguishable from the Web Socket being closed normally.</p>
- <h6 id=data-framing><span class=secno>7.3.5.2.2 </span>Data framing</h6>
+ <h6 id=data-framing><span class=secno>7.3.4.2.2 </span>Data framing</h6>
<p>Once a <a href=#web-socket-connection-is-established>Web Socket connection is established</a>, the
user agent must run through the following state machine for the
@@ -46923,11 +46892,11 @@
</ol><!-- v2: People often request the ability to send binary blobs over
this API; we should also look into allowing name/value pairs,
arrays, and numbers using postMessage() instead of just strings and
- binary data. --><h5 id=server-side-requirements><span class=secno>7.3.5.3 </span>Server-side requirements</h5>
+ binary data. --><h5 id=server-side-requirements><span class=secno>7.3.4.3 </span>Server-side requirements</h5>
<p><em>This section only applies to servers.</em></p> <!-- XXX that's not a defined conformance class -->
- <h6 id=minimal-handshake><span class=secno>7.3.5.3.1 </span>Minimal handshake</h6>
+ <h6 id=minimal-handshake><span class=secno>7.3.4.3.1 </span>Minimal handshake</h6>
<p class=note>This section describes the minimal requirements for
a server-side implementation of Web Sockets.</p>
@@ -46977,7 +46946,7 @@
<p>If the connection isn't dropped at this point, go to the <a href=#ws-sd-framing>data framing</a> section.</p>
- <h6 id=handshake-details><span class=secno>7.3.5.3.2 </span>Handshake details</h6>
+ <h6 id=handshake-details><span class=secno>7.3.4.3.2 </span>Handshake details</h6>
<p>The previous section ignores the data that is transmitted by the
client during the handshake.</p>
@@ -47040,7 +47009,7 @@
</dd>
- </dl><h6 id=ws-sd-framing><span class=secno>7.3.5.3.3 </span>Data framing</h6>
+ </dl><h6 id=ws-sd-framing><span class=secno>7.3.4.3.3 </span>Data framing</h6>
<p class=note>This section only describes how to handle content
that this specification allows user agents to send (text). It
@@ -47081,7 +47050,7 @@
<li><p>Send a 0xff byte to the client to indicate the end of the
message.</li>
- </ol><h5 id=closing-the-connection><span class=secno>7.3.5.4 </span>Closing the connection</h5>
+ </ol><h5 id=closing-the-connection><span class=secno>7.3.4.4 </span>Closing the connection</h5>
<p>To <dfn id=close-the-web-socket-connection>close the Web Socket connection</dfn>, either the user
agent or the server closes the TCP/IP connection. There is no
@@ -47096,12 +47065,12 @@
connection</a> arbitrarily.</p>
- <h5 id=security-considerations><span class=secno>7.3.5.5 </span>Security considerations</h5>
+ <h5 id=security-considerations><span class=secno>7.3.4.5 </span>Security considerations</h5>
<p class=XXX>...</p>
- <h5 id=iana-considerations><span class=secno>7.3.5.6 </span>IANA considerations</h5>
+ <h5 id=iana-considerations><span class=secno>7.3.4.6 </span>IANA considerations</h5>
<p class=XXX>...(two URI schemes, two ports, HTTP Upgrade keyword)</p>
@@ -47802,11 +47771,11 @@
<dl><dt><dfn id=void-elements>Void elements</dfn></dt>
- <dd><code><a href=#the-base-element>base</a></code>, <code><a href=#the-command>command</a></code>,
- <code><a href=#the-eventsource-element>eventsource</a></code>, <code><a href=#the-link-element>link</a></code>, <code><a href=#meta>meta</a></code>,
- <code><a href=#the-hr-element>hr</a></code>, <code><a href=#the-br-element>br</a></code>, <code><a href=#the-img-element>img</a></code>,
- <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-param-element>param</a></code>, <code><a href=#the-area-element>area</a></code>,
- <code><a href=#the-col-element>col</a></code>, <code><a href=#the-input-element>input</a></code>, <code><a href=#the-source-element>source</a></code></dd>
+ <dd><code><a href=#the-base-element>base</a></code>, <code><a href=#the-command>command</a></code>, <code><a href=#the-link-element>link</a></code>,
+ <code><a href=#meta>meta</a></code>, <code><a href=#the-hr-element>hr</a></code>, <code><a href=#the-br-element>br</a></code>,
+ <code><a href=#the-img-element>img</a></code>, <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-param-element>param</a></code>,
+ <code><a href=#the-area-element>area</a></code>, <code><a href=#the-col-element>col</a></code>, <code><a href=#the-input-element>input</a></code>,
+ <code><a href=#the-source-element>source</a></code></dd>
<dt>CDATA elements</dt>
@@ -49240,24 +49209,24 @@
<code><a href=#the-command>command</a></code>, <code><a href=#datagrid>datagrid</a></code>, <code><a href=#the-dd-element>dd</a></code>,
<code><a href=#the-details-element>details</a></code>, <code><a href=#the-dialog-element>dialog</a></code>, <code>dir</code>,
<code><a href=#the-div-element>div</a></code>, <code><a href=#the-dl-element>dl</a></code>, <code><a href=#the-dt-element>dt</a></code>,
- <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-eventsource-element>eventsource</a></code>, <code><a href=#the-fieldset-element>fieldset</a></code>,
- <code><a href=#the-figure-element>figure</a></code>, <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>,
- <code>frame</code>, <code>frameset</code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>,
- <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>,
- <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code>, <code><a href=#the-head-element>head</a></code>, <code><a href=#the-header-element>header</a></code>,
- <code><a href=#the-hr-element>hr</a></code>, <code><a href=#the-iframe-element>iframe</a></code>, <!-- <code>image</code>,
- (commented out because this isn't an element that can end up on the
- stack, so it doesn't matter) --> <code><a href=#the-img-element>img</a></code>,
- <code><a href=#the-input-element>input</a></code>, <code>isindex</code>, <code><a href=#the-li-element>li</a></code>,
- <code><a href=#the-link-element>link</a></code>, <code>listing</code>, <code><a href=#menus>menu</a></code>,
- <code><a href=#meta>meta</a></code>, <code><a href=#the-nav-element>nav</a></code>, <code>noembed</code>,
- <code>noframes</code>, <code><a href=#the-noscript-element>noscript</a></code>, <code><a href=#the-ol-element>ol</a></code>,
- <code><a href=#the-p-element>p</a></code>, <code><a href=#the-param-element>param</a></code>, <code>plaintext</code>,
- <code><a href=#the-pre-element>pre</a></code>, <code><a href=#script>script</a></code>, <code><a href=#the-section-element>section</a></code>,
- <code><a href=#the-select-element>select</a></code>, <code>spacer</code>, <code><a href=#the-style-element>style</a></code>,
- <code><a href=#the-tbody-element>tbody</a></code>, <code><a href=#the-textarea-element>textarea</a></code>, <code><a href=#the-tfoot-element>tfoot</a></code>,
- <code><a href=#the-thead-element>thead</a></code>, <code><a href=#the-title-element>title</a></code>, <code><a href=#the-tr-element>tr</a></code>,
- <code><a href=#the-ul-element>ul</a></code>, and <code>wbr</code>.</dd>
+ <code><a href=#the-embed-element>embed</a></code>, <code><a href=#the-fieldset-element>fieldset</a></code>, <code><a href=#the-figure-element>figure</a></code>,
+ <code><a href=#the-footer-element>footer</a></code>, <code><a href=#the-form-element>form</a></code>, <code>frame</code>,
+ <code>frameset</code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h1</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h2</a></code>,
+ <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h3</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h4</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h5</a></code>, <code><a href=#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements>h6</a></code>,
+ <code><a href=#the-head-element>head</a></code>, <code><a href=#the-header-element>header</a></code>, <code><a href=#the-hr-element>hr</a></code>,
+ <code><a href=#the-iframe-element>iframe</a></code>, <!-- <code>image</code>, (commented out
+ because this isn't an element that can end up on the stack, so it
+ doesn't matter) --> <code><a href=#the-img-element>img</a></code>, <code><a href=#the-input-element>input</a></code>,
+ <code>isindex</code>, <code><a href=#the-li-element>li</a></code>, <code><a href=#the-link-element>link</a></code>,
+ <code>listing</code>, <code><a href=#menus>menu</a></code>, <code><a href=#meta>meta</a></code>,
+ <code><a href=#the-nav-element>nav</a></code>, <code>noembed</code>, <code>noframes</code>,
+ <code><a href=#the-noscript-element>noscript</a></code>, <code><a href=#the-ol-element>ol</a></code>, <code><a href=#the-p-element>p</a></code>,
+ <code><a href=#the-param-element>param</a></code>, <code>plaintext</code>, <code><a href=#the-pre-element>pre</a></code>,
+ <code><a href=#script>script</a></code>, <code><a href=#the-section-element>section</a></code>, <code><a href=#the-select-element>select</a></code>,
+ <code>spacer</code>, <code><a href=#the-style-element>style</a></code>, <code><a href=#the-tbody-element>tbody</a></code>,
+ <code><a href=#the-textarea-element>textarea</a></code>, <code><a href=#the-tfoot-element>tfoot</a></code>, <code><a href=#the-thead-element>thead</a></code>,
+ <code><a href=#the-title-element>title</a></code>, <code><a href=#the-tr-element>tr</a></code>, <code><a href=#the-ul-element>ul</a></code>, and
+ <code>wbr</code>.</dd>
<dt><dfn id=scoping>Scoping</dfn></dt>
<dd><p>The following HTML elements introduce new <a href=#has-an-element-in-scope title="has
@@ -51406,7 +51375,7 @@
</dd>
<dt>A start tag whose tag name is one of: "base", "command",
- "eventsource", "link"</dt>
+ "link"</dt>
<dd>
<p><a href=#insert-an-html-element>Insert an HTML element</a> for the token. Immediately
@@ -51726,8 +51695,7 @@
</dd>
<dt>A start tag token whose tag name is one of: "base", "command",
- "eventsource", "link", "meta", "noframes", "script", "style",
- "title"</dt>
+ "link", "meta", "noframes", "script", "style", "title"</dt>
<dd>
<p>Process the token <a href=#using-the-rules-for>using the rules for</a> the "<a href=#parsing-main-inhead title="insertion mode: in head">in head</a>" <a href=#insertion-mode>insertion
mode</a>.</p>
@@ -52803,11 +52771,11 @@
"col", "colgroup", "frame", "head", "tbody", "td", "tfoot", "th",
"thead", "tr"</dt>
<!--<dt>An end tag whose tag name is one of: "area", "base",
- "basefont", "bgsound", "command", "embed", "eventsource", "hr",
- "iframe", "image", "img", "input", "isindex", "link", "meta",
- "noembed", "noframes", "param", "script", "select", "source",
- "spacer", "style", "table", "textarea", "title", "wbr"</dt>--> <!--
- add keygen if we add the start tag -->
+ "basefont", "bgsound", "command", "embed", "hr", "iframe", "image",
+ "img", "input", "isindex", "link", "meta", "noembed", "noframes",
+ "param", "script", "select", "source", "spacer", "style", "table",
+ "textarea", "title", "wbr"</dt>--> <!-- add keygen if we add the
+ start tag -->
<!--<dt>An end tag whose tag name is "noscript", if the
<span>scripting flag</span> is enabled</dt>-->
<dd>
@@ -54513,8 +54481,7 @@
node at this point.</p> <!-- also, i guess: image, isindex,
and keygen, but we don't list those because we don't consider
those "elements", more "macros", and thus we should never
- serialize them --> <!-- XXX when we get around to it, add
- eventsource -->
+ serialize them -->
<p>If <var title="">current node</var> is a <code><a href=#the-pre-element>pre</a></code>,
<code><a href=#the-textarea-element>textarea</a></code>, or <code>listing</code> element, append
@@ -57237,9 +57204,10 @@
<pre class=css>@namespace url(http://www.w3.org/1999/xhtml);
[hidden], area, audio:not([controls]), base, basefont, command,
-datalist, eventsource, head, input[type=hidden], link,
-menu[type=context], meta, noembed, noframes, param, script, source,
-style, title { display: none; }
+datalist, head, input[type=hidden], link, menu[type=context], meta,
+noembed, noframes, param, script, source, style, title {
+ display: none;
+}
address, article, aside, blockquote, body, center, dd, dialog, dir,
div, dl, dt, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hr,
@@ -59672,9 +59640,10 @@
Dutta, Tantek Çelik, Terrence Wood, Thomas Broyer, Thomas
O'Connor, Tim Altman, Tim Johansson, Tommy Thorsen, Travis Leithead,
Tyler Close, Vladimir Vukićević, Wakaba, Wayne
- Pollock, Wellington Fernando de Macedo, William Swanson, Wolfram
- Kriesing, Yi-An Huang, Zhenbin Xu, and Øistein E. Andersen,
- for their useful and substantial comments.</p>
+ Pollock, Wellington Fernando de Macedo, William Swanson, Wladimir
+ Palant, Wolfram Kriesing, Yi-An Huang, Zhenbin Xu, and
+ Øistein E. Andersen, for their useful and substantial
+ comments.</p>
<p>Thanks also to everyone who has ever posted about HTML5 to their
blogs, public mailing lists, or forums, including the <a href=http://lists.w3.org/Archives/Public/public-html/>W3C
Modified: source
===================================================================
--- source 2009-02-25 23:37:24 UTC (rev 2869)
+++ source 2009-02-26 08:33:42 UTC (rev 2870)
@@ -7156,7 +7156,6 @@
attribute <span>Function</span> <span title="handler-onkeypress">onkeypress</span>;
attribute <span>Function</span> <span title="handler-onkeyup">onkeyup</span>;
attribute <span>Function</span> <span title="handler-onload">onload</span>;
- attribute <span>Function</span> <span title="handler-onmessage">onmessage</span>;
attribute <span>Function</span> <span title="handler-onmousedown">onmousedown</span>;
attribute <span>Function</span> <span title="handler-onmousemove">onmousemove</span>;
attribute <span>Function</span> <span title="handler-onmouseout">onmouseout</span>;
@@ -7220,7 +7219,6 @@
<li><code title="handler-onkeypress">onkeypress</code></li>
<li><code title="handler-onkeyup">onkeyup</code></li>
<li><code title="handler-onload">onload</code>*</li>
- <li><code title="handler-onmessage">onmessage</code>*</li>
<li><code title="handler-onmousedown">onmousedown</code></li>
<li><code title="handler-onmousemove">onmousemove</code></li>
<li><code title="handler-onmouseout">onmouseout</code></li>
@@ -7232,10 +7230,11 @@
<li><code title="handler-onsubmit">onsubmit</code></li>
</ul>
- <p class="note">The attributes marked with an asterisk cannot be
- specified on <code>body</code> elements as those elements expose
- <span>event handler attributes</span> of the <code>Window</code>
- object with the same names.</p>
+ <p class="note">The attribute<!--s--> marked with an asterisk cannot
+ be specified on <code>body</code> elements as those elements expose
+ <!---->an<!----> <span title="event handler attributes">event
+ handler attribute<!--s--></span> of the <code>Window</code> object
+ with the same name<!--s-->.</p>
<hr>
@@ -11290,121 +11289,6 @@
- <h4>The <dfn><code>eventsource</code></dfn> element</h4>
-
- <dl class="element">
- <dt>Categories</dt>
- <dd><span>Metadata content</span>.</dd>
- <dd><span>Flow content</span>.</dd>
- <dd><span>Phrasing content</span>.</dd>
- <dt>Contexts in which this element may be used:</dt>
- <dd>Where <span>metadata content</span> is expected.</dd>
- <dd>Where <span>phrasing content</span> is expected.</dd>
- <dt>Content model:</dt>
- <dd>Empty.</dd>
- <dt>Content attributes:</dt>
- <dd><span>Global attributes</span></dd>
- <dd><code title="attr-eventsource-src">src</code></dd>
- <dt>DOM interface:</dt>
- <dd>
-<pre class="idl">interface <dfn>HTMLEventSourceElement</dfn> : <span>HTMLElement</span> {
- attribute DOMString <span title="dom-eventsource-src">src</span>;
-};</pre>
- </dd>
- </dl>
-
- <p>The <code>eventsource</code> element <span>represents</span> a
- target for events generated by a remote server.</p>
-
- <p>The <dfn title="attr-eventsource-src"><code>src</code></dfn>
- attribute, if specified, must give a <span>valid URL</span>
- identifying a resource that uses the <code>text/event-stream</code>
- format.</p>
-
- <p>When an <code>eventsource</code> element with a <code
- title="attr-eventsource-src">src</code> attribute specified is <span
- title="insert an element into a document">inserted into the
- document</span>, and when an <code>eventsource</code> element that
- is already in the document<!--XXX xref--> has a <code
- title="attr-eventsource-src">src</code> attribute added, the user
- agent must run the <span>add declared event source</span>
- algorithm.</p>
-
- <p>While an <code>eventsource</code> element is in a document<!--
- XXX xref -->, if its <code title="attr-eventsource-src">src</code>
- attribute is mutated, the user agent must must run the <span>remove
- declared event source</span> algorithm followed by the <span>add
- declared event source</span> algorithm.</p>
-
- <p>When an <code>eventsource</code> element with a <code
- title="attr-eventsource-src">src</code> attribute specified is
- removed from a document<!-- XXX xref -->, and when an
- <code>eventsource</code> element that is in a document<!--XXX
- xref--> with a <code title="attr-eventsource-src">src</code>
- attribute specified has its <code
- title="attr-eventsource-src">src</code> attribute removed, the user
- agent must run the <span>remove declared event source</span>
- algorithm.</p>
-
- <!-- changing the base URL doesn't trigger these algorithms -->
-
- <p>When it is created, an <code>eventsource</code> element must
- have its <i>current declared event source</i> set to
- "undefined".</p>
-
- <p>The <dfn>add declared event source</dfn> algorithm is as
- follows:</p>
-
- <ol>
-
- <li><span title="resolve a url">Resolve</span> the <span>URL</span>
- specified by the <code>eventsource</code> element's <code
- title="attr-eventsource-src">src</code> attribute, relative to the
- element.</li>
-
- <li>If that fails, then set the element's <i>current declared event
- source</i> to "undefined" and abort these steps.</li>
-
- <li>Otherwise, add the resulting <span>absolute URL</span> to the
- <span title="concept-eventsource-list">list of event sources</span>
- for the element.</li>
-
- <li>Let the element's <i>current declared event source</i> be that
- <span>absolute URL</span>.</li>
-
- </ol>
-
- <p>The <dfn>remove declared event source</dfn> algorithm is as
- follows:</p>
-
- <ol>
-
- <li>If the element's <i>current declared event source</i> is
- "undefined", abort these steps.</li>
-
- <li>Otherwise, remove the element's <i>current declared event
- source</i> from the <span title="concept-eventsource-list">list of
- event sources</span> for the element.</li>
-
- <li>Let the element's <i>current declared event source</i> be
- "undefined".</li>
-
- </ol>
-
- <p>There can be more than one <code>eventsource</code> element per
- document, but authors should take care to avoid opening multiple
- connections to the same server as HTTP recommends a limit to the
- number of simultaneous connections that a user agent can open per
- server.</p>
-
- <!-- v2: make 'load', 'error', 'abort' events fire on this element -->
-
- <p>The <dfn title="dom-eventsource-src"><code>src</code></dfn> DOM
- attribute must <span>reflect</span> the content attribute of the
- same name.</p>
-
-
-
<h3>Sections</h3>
<p id="applyToSection">Some elements, for example
@@ -11475,27 +11359,25 @@
attributes</span> of the <code>Window</code> object. It also mirrors
their <span>event handler DOM attributes</span>.</p>
- <p>The <code title="handler-window-onerror">onerror</code> and <code
- title="handler-window-onmessage">onmessage</code> <span>event
- handler attributes</span> of the <code>Window</code> object, exposed
- on the <code>body</code> element, shadow the generic <code
- title="handler-onerror">onerror</code> and <code
- title="handler-onmessage">onmessage</code> <span>event handler
- attributes</span> normally supported by <span>HTML
- elements</span>.</p>
+ <p>The <code title="handler-window-onerror">onerror</code> <span
+ title="event handler attributes">event handler
+ attribute<!--s--></span> of the <code>Window</code> object, exposed
+ on the <code>body</code> element, shadow<!---->s<!----> the generic
+ <code title="handler-onerror">onerror</code> <span title="event
+ handler attributes">event handler attribute<!--s--></span> normally
+ supported by <span>HTML elements</span>.</p>
<p class="example">Thus, for example, a bubbling <code
- title="event-message">message</code> event fired on a child of
- <span>the body element</span> of a <code>Document</code> would first
- trigger the <code title="handler-onmessage">onmessage</code>
- <span>event handler content attributes</span> of that element, then
- that of the root <code>html</code> element, and only <em>then</em>
- would it trigger the <code
- title="handler-window-onmessage">onmessage</code> <span title="event
- handler content attributes">event handler content attribute</span>
- on the <code>body</code> element. This is because the event would
- bubble from the target, to the <code>body</code>, to the
- <code>html</code>, to the <code>Document</code>, to the
+ title="event-error">error</code> event fired on a child of <span>the
+ body element</span> of a <code>Document</code> would first trigger
+ the <code title="handler-onerror">onerror</code> <span>event handler
+ content attributes</span> of that element, then that of the root
+ <code>html</code> element, and only <em>then</em> would it trigger
+ the <code title="handler-window-onerror">onerror</code> <span
+ title="event handler content attributes">event handler content
+ attribute</span> on the <code>body</code> element. This is because
+ the event would bubble from the target, to the <code>body</code>, to
+ the <code>html</code>, to the <code>Document</code>, to the
<code>Window</code>, and the event handler attribute on the
<code>body</code> is watching the <code>Window</code> not the
<code>body</code>. A regular event listener attached to the
@@ -25081,7 +24963,8 @@
<h4><dfn>Dimension attributes</dfn></h4>
- <p>The <dfn title="attr-dim-width"><code>width</code></dfn> and <dfn
+ <p><strong>Author requirements:</strong> The <dfn
+ title="attr-dim-width"><code>width</code></dfn> and <dfn
title="attr-dim-height"><code>height</code></dfn> attributes on
<code>img</code>, <code>iframe</code>, <code>embed</code>,
<code>object</code>, <code>video</code>, and, when their <code
@@ -25126,8 +25009,9 @@
<p class="note">Basically, the dimension attributes can't be used to
stretch the image.</p>
- <p>User agents are expected to use these attributes <a
- href="#dimRendering">as hints for the rendering</a>.</p>
+ <p><strong>User agent requirements:</strong> User agents are
+ expected to use these attributes <a href="#dimRendering">as hints
+ for the rendering</a>.</p>
<p>The <dfn title="dom-dim-width"><code>width</code></dfn> and <dfn
title="dom-dim-height"><code>height</code></dfn> DOM attributes on
@@ -41749,12 +41633,6 @@
title="event-load">load</code> event is targeted at or bubbles
through the element.</p></dd>
- <dt><dfn title="handler-onmessage"><code>onmessage</code></dfn></dt> <!-- new for <eventsource> -->
-
- <dd><p>Must be invoked whenever a <code
- title="event-message">message</code> event is targeted at or bubbles
- through the element.</p></dd>
-
</dl>
<hr>
@@ -52201,186 +52079,227 @@
attribute must be null.</p>
+
<h3 id="server-sent-events"><dfn>Server-sent events</dfn></h3>
<!-- eventsource -->
- <p>This section describes a mechanism for allowing servers to
- dispatch DOM events into documents that expect it. The
- <code>eventsource</code> element provides a simple interface to
- this mechanism.</p>
+ <h4 id="server-sent-events-intro">Introduction</h4>
+ <p><em>This section is non-normative.</em></p>
+ <p>To enable servers to push data to Web pages over HTTP or using
+ dedicated server-push protocols, this specification introduces the
+ <code>EventSource</code> interface.</p>
- <h4>The <code>RemoteEventTarget</code> interface</h4>
+ <p class="XXX">An introduction to the client-side and
+ server-side of using the direct connection APIs.</p>
- <p>Any object that implements the <code>EventTarget</code> interface
- must also implement the <code>RemoteEventTarget</code>
- interface.</p>
+ <!--BOILERPLATE-->
- <pre class="idl">[NoInterfaceObject, ImplementedOn=<span>EventTarget</span>] interface <dfn>RemoteEventTarget</dfn> {
- void <span title="dom-RemoteEventTarget-addEventSource">addEventSource</span>(in DOMString src);
- void <span title="dom-RemoteEventTarget-removeEventSource">removeEventSource</span>(in DOMString src);
+ <h4>The <code>EventSource</code> interface</h4>
+
+ <pre class="idl">[<span title="dom-EventSource">Constructor</span>(in DOMString url)]
+interface <dfn>EventSource</dfn> {
+ readonly attribute DOMString <span title="dom-EventSource-URL">URL</span>;
+
+ // ready state
+ const unsigned short <span title="dom-EventSource-CONNECTING">CONNECTING</span> = 0;
+ const unsigned short <span title="dom-EventSource-OPEN">OPEN</span> = 1;
+ const unsigned short <span title="dom-EventSource-CLOSED">CLOSED</span> = 2;
+ readonly attribute long <span title="dom-EventSource-readyState">readyState</span>;
+
+ // networking
+ attribute <span>Function</span> <span title="handler-EventSource-onopen">onopen</span>;
+ attribute <span>Function</span> <span title="handler-EventSource-onmessage">onmessage</span>;
+ attribute <span>Function</span> <span title="handler-EventSource-onerror">onerror</span>;
+ void <span title="dom-EventSource-disconnect">disconnect</span>();
};</pre>
- <p>When the <dfn
- title="dom-RemoteEventTarget-addEventSource"><code>addEventSource(<var
- title="">src</var>)</code></dfn> method is invoked, the user agent
- must <span title="resolve a url">resolve</span> the <span>URL</span>
- specified in <var title="">src</var>, relative to the <span>first
- script</span>'s <span title="script's base URL">base URL</span>, and
- if that succeeds, add the resulting <span>absolute URL</span> to the
- <span title="concept-eventsource-list">list of event sources</span>
- for that object. The same URL can be registered multiple times. If
- the URL fails to resolve, then the user agent must raise a
- <code>SYNTAX_ERR</code> exception.</p>
+ <p><code>EventSource</code> objects must also implement the
+ <code>EventTarget</code> interface. <a
+ href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
- <p>When the <dfn
- title="dom-RemoteEventTarget-removeEventSource"><code>removeEventSource(<var
- title="">src</var>)</code></dfn> method is invoked, the user agent
- must <span title="resolve a url">resolve</span> the <span>URL</span>
- specified in <var title="">src</var>, relative to the <span>first
- script</span>'s <span title="script's base URL">base URL</span>, and
- if that succeeds, remove the resulting <span>absolute URL</span>
- from the <span title="concept-eventsource-list">list of event
- sources</span> for that object. If the same URL has been registered
- multiple times, removing it must remove only one instance of that
- URL for each invocation of the <code
- title="removeEventSource">removeEventSource()</code> method. If the
- URL fails to resolve, the user agent does nothing.</p>
+ <p>The <dfn title="dom-EventSource"><code>EventSource(<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>EventSource()</code> constructor is
+ invoked, the UA must run these steps:</p>
+ <ol>
- <h4>Connecting to an event stream</h4>
+ <li><p><span title="resolve a url">Resolve</span> the
+ <span>URL</span> specified in <var title="">src</var>, relative to
+ the <span>first script</span>'s <span title="script's base
+ URL">base URL</span>.</p></li>
- <p>Each object implementing the <code>EventTarget</code> and
- <code>RemoteEventTarget</code> interfaces has a <dfn
- title="concept-eventsource-list">list of event sources</dfn> that
- are registered for that object.</p>
+ <li><p>If the previous step failed, then throw a
+ <code>SYNTAX_ERR</code> exception.</p></li>
- <p>When a new <span>absolute URL</span> is added to this list, the
- user agent should <span>queue a task</span> to run the following
- steps with the new <span>absolute URL</span>:</p>
+ <li><p>Return a new <code>EventSource</code> object, and continue
+ these steps in the background (without blocking scripts).</p></li>
- <ol>
+ <li><p><span>Fetch</span> the resource identified by the resulting
+ <span>absolute URL</span>, as described below.</p></li>
- <li><p>If the entry for the new <span>absolute URL</span> has been
- removed from the list, then abort these steps.</p></li>
+ </ol>
- <li>
+ <p>The <dfn title="dom-EventSource-URL"><code>URL</code></dfn>
+ attribute must return the value that was passed to the
+ constructor.</p>
- <p><span>Fetch</span> the resource identified by that
- <span>absolute URL</span>.</p>
+ <p>The <dfn
+ title="dom-EventSource-readyState"><code>readyState</code></dfn>
+ attribute represents the state of the connection. It can have the
+ following values:</p>
- <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 consist of following
- the rules given in the following sections.</p>
+ <dl>
- </li>
+ <dt><dfn title="dom-EventSource-CONNECTING"><code>CONNECTING</code></dfn> (numeric value 0)</dt>
- </ol>
+ <dd>The connection has not yet been established, or it was closed
+ and the user agent is reconnecting.</dd>
- <p>When an event source is removed from the list of event sources
- for an object, if that resource is still being fetched, then the
- relevant connection must be closed.</p>
+ <dt><dfn title="dom-EventSource-OPEN"><code>OPEN</code></dfn> (numeric value 1)</dt>
- <p>Since connections established to remote servers for such
- resources are expected to be long-lived, UAs should ensure that
- appropriate buffering is used. In particular, while line buffering
- may be safe if lines are defined to end with a single U+000A LINE
- FEED character, block buffering or line buffering with different
- expected line endings can cause delays in event dispatch.</p>
+ <dd>The user agent has an open connection and is dispatching events
+ as it receives them.</dd>
- <p>Each event source in the list must have associated with it the
- following:</p>
+ <dt><dfn 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-disconnect">disconnect()</code> method was
+ invoked.</dd>
+
+ </dl>
+
+ <p>When the object is created its <code
+ title="dom-EventSource-readyState">readyState</code> must be set to
+ <code title="dom-EventSource-CONNECTING">CONNECTING</code> (0). The
+ rules given below for handling the connection define when the value
+ changes.</p>
+
+ <p>The <dfn
+ title="dom-EventSource-disconnect"><code>disconnect()</code></dfn>
+ method must close the connection, if any, and must set the <code
+ title="dom-EventSource-readyState">readyState</code> attribute to
+ <code title="dom-EventSource-CLOSED">CLOSED</code>. If the
+ connection is already closed, the method must do nothing.</p>
+
+ <p>The following are the <span>event handler attributes</span> that
+ must be supported, as DOM attributes, by all objects implementing
+ the <code>EventSource</code> interface:</p>
+
+ <dl>
+
+ <dt><dfn title="handler-EventSource-onopen"><code>onopen</code></dfn></dt>
+
+ <dd><p>Must be invoked whenever an <code
+ title="event-open">open</code> event is targeted at or
+ bubbles through the <code>EventSource</code> object.</p></dd>
+
+ <dt><dfn title="handler-EventSource-onmessage"><code>onmessage</code></dfn></dt>
+
+ <dd><p>Must be invoked whenever a <code
+ title="event-message">message</code> event is targeted at or
+ bubbles through the <code>EventSource</code> object.</p></dd>
+
+ <dt><dfn title="handler-EventSource-onerror"><code>onerror</code></dfn></dt>
+
+ <dd><p>Must be invoked whenever an <code
+ title="event-error">error</code> event is targeted at or
+ bubbles through the <code>EventSource</code> object.</p></dd>
+
+ </dl>
+
+ <hr>
+
+ <p>In addition to the above, each <code>EventSource</code> object
+ has the following associated with it:</p>
+
<ul>
- <li>The <dfn
+ <li>A <dfn
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>The <dfn title="concept-event-stream-last-event-id">last event
+ <li>A <dfn title="concept-event-stream-last-event-id">last event
ID string</dfn>. This must initially be the empty string.</li>
</ul>
- <p>In general, the semantics of the transport protocol specified by
- the URLs for the event sources must be followed, including HTTP
- caching rules.</p>
+ <p>These values are not currently exposed on the interface.</p>
+
+ <h4>Processing model</h4>
+
+ <p>The resource indicated in the argument to the <code
+ title="dom-EventSource">EventSource</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>text/event-stream</code>, as described below).</p>
- <p>Other formats of event framing may also be supported in addition
- to <code>text/event-stream</code>, but this specification does not
- define how they are to be parsed or processed.</p>
-
- <p class="note">Such formats could include systems like SMS-push;
- for example servers could use <code title="">Accept</code> headers
- and HTTP redirects to an SMS-push mechanism as a kind of protocol
- negotiation to reduce network load in GSM environments.</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.</p>
-
<p>If the event source's last event ID string is not the empty
string, then a <code title="">Last-Event-ID</code> HTTP header must
be included with the request, whose value is the value of the event
source's last event ID string.</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. User agents should ignore HTTP cache headers in the
+ response, never caching event sources.</p>
+
<p class="XXX">Cross-origin loads are expected to follow the
Access-Control semantics of CORS; without this header, they are
expected to fail as if the site was down.</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>text/event-stream</code> must be processed
line by line <a href="#event-stream-interpretation">as described
below</a>.</p>
- <p>For the purposes of such successfully opened event streams only,
- user agents should ignore HTTP cache headers, and instead assume
- that the resource indicates that it does not wish to be cached.</p>
+ <p>When a successful response with a supported MIME type is
+ received, such that the user agent begins parsing the contents of
+ the stream, the user agent must <span>announce the
+ connection</span>.</p>
<p>If such a resource (with the correct MIME type) completes loading
(i.e. the entire HTTP response body is received or the connection
- itself closes), the user agent should request the event source
- resource again after a delay equal to the reconnection time of the
- event source. This doesn't apply for the error cases that are listed
- below.</p>
+ itself closes), the user agent must <span>reset the
+ connection</span>. This doesn't apply for the error cases that are
+ listed below.</p>
<p>HTTP 200 OK responses that have a <span>Content-Type</span> other
than <code>text/event-stream</code> (or some other supported type)
- must be ignored.</p>
+ must cause the user agent to <span>fail the connection</span>.</p>
- <p>HTTP 204 No Content, and 205 Reset Content responses must be
- treated as if they were 200 OK responses with the right MIME type
- but no content, and should therefore cause the user agent to refetch
- the resource after a delay equal to the reconnection time of the
- event source.</p>
+ <p>HTTP 204 No Content, and 205 Reset Content responses are
+ equivalent to 200 OK responses with the right MIME type but no
+ content, and thus must <span>reset the connection</span>.</p>
<p>Other HTTP response codes in the 2xx range <!--201 Created, 202
Accepted, 203 Non-Authoritative Information, and 206 Partial
- Content-->must be treated like HTTP 200 OK responses for the
- purposes of reopening event source resources. They are, however,
- likely to indicate an error has occurred somewhere and may cause the
- user agent to emit a warning.</p>
+ Content-->must similarly <span>reset the connection</span>. They
+ are, however, likely to indicate an error has occurred somewhere and
+ may cause the user agent to emit a warning.</p>
- <p>HTTP 300 Multiple Choices responses should be handled
- automatically if possible (treating the responses as if they were
- 302 Found responses pointing to the appropriate resource), and
- otherwise must be treated as HTTP 404 responses.</p>
-
<p>HTTP 301 Moved Permanently responses must cause the user agent to
reconnect using the new server specified URL instead of the
previously specified URL for all subsequent requests for this event
- source. (It doesn't affect other event sources with the same URL
- unless they also receive 301 responses, and it doesn't affect future
- sessions, e.g. if the page is reloaded.)</p>
+ source. (It doesn't affect other <code>EventSource</code> objects
+ with the same URL unless they also receive 301 responses, and it
+ doesn't affect future sessions, e.g. if the page is reloaded.)</p>
<p>HTTP 302 Found, 303 See Other, and 307 Temporary Redirect
responses must cause the user agent to connect to the new
@@ -52388,33 +52307,62 @@
the resource at a later point, it must return to the previously
specified URL for this event source.</p>
- <p>HTTP 304 Not Modified responses should be handled like HTTP 200
- OK responses, with the content coming from the user agent cache. A
- new request should then be made after a delay equal to the
- reconnection time of the event source.</p>
-
<p>HTTP 305 Use Proxy, HTTP 401 Unauthorized, and 407 Proxy
Authentication Required should be treated transparently as for any
other subresource.</p>
<p>Any other HTTP response code not listed here or network error
- (e.g. DNS errors) must be ignored.</p> <!-- including: HTTP 400 Bad
- Request, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 406
- Not Acceptable, 408 Request Timeout, 409 Conflict, 410 Gone, 411
- Length Required, 412 Precondition Failed, 413 Request Entity Too
- Large, 414 Request-URI Too Long, 415 Unsupported Media Type, 416
- Requested Range Not Satisfiable, 417 Expectation Failed, 500
- Internal Server Error, 501 Not Implemented, 502 Bad Gateway, 503
- Service Unavailable, 504 Gateway Timeout, and 505 HTTP Version Not
- Supported responses -->
+ (e.g. DNS errors) must cause the user agent to <span>fail the
+ connection</span>.</p> <!-- including: HTTP 300 Multiple Choices,
+ HTTP 304 Not Modified, HTTP 400 Bad Request, 403 Forbidden, 404 Not
+ Found, 405 Method Not Allowed, 406 Not Acceptable, 408 Request
+ Timeout, 409 Conflict, 410 Gone, 411 Length Required, 412
+ Precondition Failed, 413 Request Entity Too Large, 414 Request-URI
+ Too Long, 415 Unsupported Media Type, 416 Requested Range Not
+ Satisfiable, 417 Expectation Failed, 500 Internal Server Error, 501
+ Not Implemented, 502 Bad Gateway, 503 Service Unavailable, 504
+ Gateway Timeout, and 505 HTTP Version Not Supported responses -->
<p>For non-HTTP protocols, UAs should act in equivalent ways.</p>
+ <hr>
- <h4>Parsing an event stream</h4>
+ <p>When a user agent is to <dfn>announce the connection</dfn>, the
+ user agent must set the <code
+ title="dom-EventSource-readyState">readyState</code> attribute to
+ <code title="dom-EventSource-OPEN">OPEN</code> and <span>queue a
+ task</span> to <span>fire a simple event</span> named <code
+ title="event-open">open</code> at the
+ <code>EventSource</code> object.</p>
- <!-- XXX Wladimir Palant pointed out problems with HTTP chunking with server-sent-events -->
+ <p>When a user agent is to <dfn>reset the connection</dfn>, the user
+ agent must set the <code
+ title="dom-EventSource-readyState">readyState</code> attribute to
+ <code title="dom-EventSource-CONNECTING">CONNECTING</code>,
+ <span>queue a task</span> to <span>fire a simple event</span> named
+ <code title="event-error">error</code> at the
+ <code>EventSource</code> object, and then <span>fetch</span> the
+ event source resource again after a delay equal to the reconnection
+ time of the event source.</p>
+ <p>When a user agent is to <dfn>fail the connection</dfn>, the user
+ agent must set the <code
+ title="dom-EventSource-readyState">readyState</code> attribute to
+ <code title="dom-EventSource-CLOSED">CLOSED</code> and <span>queue a
+ task</span> to <span>fire a simple event</span> named <code
+ title="event-error">error</code> at the
+ <code>EventSource</code> object.</p>
+
+ <hr>
+
+ <p>The <span>task source</span> for any <span
+ title="concept-task">tasks</span> that are <span title="queue a
+ task">queued</span> by <code>EventSource</code> objects is the
+ <dfn>remote event task source</dfn>.</p>
+
+
+ <h4>Parsing an event stream</h4>
+
<p>This event stream format's MIME type is
<code>text/event-stream</code>.</p>
@@ -52449,6 +52397,12 @@
LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF)
character, or a single U+000D CARRIAGE RETURN (CR) character.</p>
+ <p>Since connections established to remote servers for such
+ resources are expected to be long-lived, UAs should ensure that
+ appropriate buffering is used. In particular, while line buffering
+ with lines are defined to end with a single U+000A LINE FEED
+ character is safe, block buffering or line buffering with different
+ expected line endings can cause delays in event dispatch.</p>
<h4 id="event-stream-interpretation">Interpreting an event stream</h4>
@@ -52618,10 +52572,7 @@
title="">event name</var> buffer to the empty string.</p></li>
<li><p><span>Queue a task</span> to dispatch the newly created
- event at the <code>RemoteEventTarget</code> object to which the
- event stream is registered. The <span>task source</span> for this
- <span title="concept-task">task</span> is the <dfn>remote event
- task source</dfn>.</p></li>
+ event at the <code>EventSource</code> object.</p></li>
</ol>
@@ -52636,22 +52587,28 @@
<p>The following event stream, once followed by a blank line:</p>
<pre>data: YHOO
-data: -2
+data: +2
data: 10</pre>
<p>...would cause an event <code
title="event-message">message</code> with the interface
<code>MessageEvent</code> to be dispatched on the
- <code>eventsource</code> element, whose <code
+ <code>EventSource</code> object. The event's <code
title="dom-MessageEvent-data">data</code> attribute would contain
- the string <code>YHOO\n-2\n10</code> (where <code>\n</code>
+ the string <code>YHOO\n+2\n10</code> (where <code>\n</code>
represents a newline).</p>
<p>This could be used as follows:
- <pre><eventsource src="http://stocks.example.com/ticker.php"
- onmessage="var data = event.data.split('\n'); updateStocks(data[0], data[1], data[2]);"></pre>
+ <pre>var stocks = new EventSource("http://stocks.example.com/ticker.php");
+stocks.onmessage = function (event) {
+ var data = event.data.split('\n');
+ updateStocks(data[0], data[1], data[2]);
+};</pre>
+
<p>...where <code title="">updateStocks()</code> is a function defined as:</p>
+
<pre>function updateStocks(symbol, delta, value) { ... }</pre>
+
<p>...or some such.</p>
</div>
@@ -52733,16 +52690,43 @@
the URL in the <code title="attr-eventsource-src">src</code>
attribute of the <code>eventsource</code> element.</p>
+ <p>Authors are also cautioned that HTTP chunking can have unexpected
+ negative effects on the reliability of this protocol. Where
+ possible, chunking should be disabled for serving event streams
+ unless the rate of messages is high enough for this not to
+ matter.</p> <!-- v2 can we get a better solution? -->
+
<p>Implementations that support HTTP's per-server connection
limitation might run into trouble when opening multiple pages from a
- site if each page has an <code>eventsource</code> to the same
+ site if each page has an <code>EventSource</code> to the same
domain. Authors can avoid this using the relatively complex
mechanism of using unique domain names per connection, or by
- allowing the user to enable or disable the <code>eventsource</code>
+ allowing the user to enable or disable the <code>EventSource</code>
functionality on a per-page basis.</p>
+ <hr>
+ <p>Other formats of event framing may also be supported in addition
+ to <code>text/event-stream</code>, but this specification does not
+ define how they are to be parsed or processed.</p>
+ <p class="note">Such formats could include systems like SMS-push;
+ for example servers could use <code title="">Accept</code> headers
+ and HTTP redirects to an SMS-push mechanism as a kind of protocol
+ negotiation to reduce network load in GSM environments.</p>
+
+
+ <h4>Garbage collection</h4>
+
+ <p>An <code>EventSource</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>
+
+ <p>If an <code>EventSource</code> object is garbage collected while
+ its connection is still open, the connection must be closed.</p>
+
+
+
<h3 id="network"><dfn>Web sockets</dfn></h3>
<h4 id="network-intro">Introduction</h4>
@@ -52778,7 +52762,7 @@
// networking
attribute <span>Function</span> <span title="handler-WebSocket-onopen">onopen</span>;
attribute <span>Function</span> <span title="handler-WebSocket-onmessage">onmessage</span>;
- attribute <span>Function</span> <span title="handler-WebSocket-onclosed">onclosed</span>;
+ attribute <span>Function</span> <span title="handler-WebSocket-onclose">onclose</span>;
void <span title="dom-WebSocket-postMessage">postMessage</span>(in DOMString data);
void <span title="dom-WebSocket-disconnect">disconnect</span>();
};</pre>
@@ -52898,31 +52882,11 @@
method must <span>close the Web Socket connection</span> or
connection attempt, if any. If the connection is already closed, it
must do nothing. Closing the connection causes a <code
- title="event-WebSocket-close">close</code> event to be fired and
+ title="event-close">close</code> event to be fired and
the <code title="dom-WebSocket-readyState">readyState</code>
attribute's value to change, as <a href="#closeWebSocket">described
below</a>.</p>
-
- <h4>WebSocket Events</h4>
-
- <p>The <dfn title="event-WebSocket-open"><code>open</code></dfn>
- event is fired when the <span>Web Socket connection is
- established</span>.</p>
-
- <p>The <dfn title="event-WebSocket-close"><code>close</code></dfn>
- event is fired when the connection is closed (whether by the author,
- calling the <code
- title="dom-WebSocket-disconnect">disconnect()</code> method, or by
- the server, or by a network error).</p>
-
- <p class="note">No information regarding why the connection was
- closed is passed to the application in this version of this
- specification.</p>
-
- <p>The <code title="event-message">message</code> event is fired
- when when data is received for a connection.</p>
-
<hr>
<p>The following are the <span>event handler attributes</span> that
@@ -52934,7 +52898,7 @@
<dt><dfn title="handler-WebSocket-onopen"><code>onopen</code></dfn></dt>
<dd><p>Must be invoked whenever an <code
- title="event-WebSocket-open">open</code> event is targeted at or
+ title="event-open">open</code> event is targeted at or
bubbles through the <code>WebSocket</code> object.</p></dd>
<dt><dfn title="handler-WebSocket-onmessage"><code>onmessage</code></dfn></dt>
@@ -52943,10 +52907,10 @@
title="event-message">message</code> event is targeted at or
bubbles through the <code>WebSocket</code> object.</p></dd>
- <dt><dfn title="handler-WebSocket-onclosed"><code>onclosed</code></dfn></dt>
+ <dt><dfn title="handler-WebSocket-onclose"><code>onclose</code></dfn></dt>
<dd><p>Must be invoked whenever an <code
- title="event-WebSocket-closed">closed</code> event is targeted at or
+ title="event-close">close</code> event is targeted at or
bubbles through the <code>WebSocket</code> object.</p></dd>
</dl>
@@ -52971,7 +52935,7 @@
<li>
<p><span>Queue a task</span> to <span>fire a simple event</span>
- named <code title="event-WebSocket-open">open</code> at the
+ named <code title="event-open">open</code> at the
<code>WebSocket</code> object.</p>
</li>
@@ -52997,7 +52961,7 @@
must be changed to <code title="dom-WebSocket-CLOSED">CLOSED</code>
(2), and the user agent must <span>queue a task</span> to <span>fire
a simple event</span> named <code
- title="event-WebSocket-close">close</code> at the
+ title="event-close">close</code> at the
<code>WebSocket</code> object.</p>
<hr>
@@ -53008,7 +52972,18 @@
source</dfn>.</p>
+ <h5>Garbage collection</h5>
+ <p>A <code>WebSocket</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>
+
+ <p>If a <code>WebSocket</code> object is garbage collected while its
+ connection is still open, the user agent must <span>close the Web
+ Socket connection</span>.</p>
+
+
+
<h4 id="websocket-protocol" title="This protocol enables two-way
communication between a user agent running untrusted code running in
a controlled environment to a remote host that understands the
@@ -54639,11 +54614,11 @@
<dt><dfn>Void elements</dfn></dt>
- <dd><code>base</code>, <code>command</code>,
- <code>eventsource</code>, <code>link</code>, <code>meta</code>,
- <code>hr</code>, <code>br</code>, <code>img</code>,
- <code>embed</code>, <code>param</code>, <code>area</code>,
- <code>col</code>, <code>input</code>, <code>source</code></dd>
+ <dd><code>base</code>, <code>command</code>, <code>link</code>,
+ <code>meta</code>, <code>hr</code>, <code>br</code>,
+ <code>img</code>, <code>embed</code>, <code>param</code>,
+ <code>area</code>, <code>col</code>, <code>input</code>,
+ <code>source</code></dd>
<dt>CDATA elements</dt>
@@ -56275,24 +56250,24 @@
<code>command</code>, <code>datagrid</code>, <code>dd</code>,
<code>details</code>, <code>dialog</code>, <code>dir</code>,
<code>div</code>, <code>dl</code>, <code>dt</code>,
- <code>embed</code>, <code>eventsource</code>, <code>fieldset</code>,
- <code>figure</code>, <code>footer</code>, <code>form</code>,
- <code>frame</code>, <code>frameset</code>, <code>h1</code>,
- <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>,
- <code>h6</code>, <code>head</code>, <code>header</code>,
- <code>hr</code>, <code>iframe</code>, <!-- <code>image</code>,
- (commented out because this isn't an element that can end up on the
- stack, so it doesn't matter) --> <code>img</code>,
- <code>input</code>, <code>isindex</code>, <code>li</code>,
- <code>link</code>, <code>listing</code>, <code>menu</code>,
- <code>meta</code>, <code>nav</code>, <code>noembed</code>,
- <code>noframes</code>, <code>noscript</code>, <code>ol</code>,
- <code>p</code>, <code>param</code>, <code>plaintext</code>,
- <code>pre</code>, <code>script</code>, <code>section</code>,
- <code>select</code>, <code>spacer</code>, <code>style</code>,
- <code>tbody</code>, <code>textarea</code>, <code>tfoot</code>,
- <code>thead</code>, <code>title</code>, <code>tr</code>,
- <code>ul</code>, and <code>wbr</code>.</p></dd>
+ <code>embed</code>, <code>fieldset</code>, <code>figure</code>,
+ <code>footer</code>, <code>form</code>, <code>frame</code>,
+ <code>frameset</code>, <code>h1</code>, <code>h2</code>,
+ <code>h3</code>, <code>h4</code>, <code>h5</code>, <code>h6</code>,
+ <code>head</code>, <code>header</code>, <code>hr</code>,
+ <code>iframe</code>, <!-- <code>image</code>, (commented out
+ because this isn't an element that can end up on the stack, so it
+ doesn't matter) --> <code>img</code>, <code>input</code>,
+ <code>isindex</code>, <code>li</code>, <code>link</code>,
+ <code>listing</code>, <code>menu</code>, <code>meta</code>,
+ <code>nav</code>, <code>noembed</code>, <code>noframes</code>,
+ <code>noscript</code>, <code>ol</code>, <code>p</code>,
+ <code>param</code>, <code>plaintext</code>, <code>pre</code>,
+ <code>script</code>, <code>section</code>, <code>select</code>,
+ <code>spacer</code>, <code>style</code>, <code>tbody</code>,
+ <code>textarea</code>, <code>tfoot</code>, <code>thead</code>,
+ <code>title</code>, <code>tr</code>, <code>ul</code>, and
+ <code>wbr</code>.</p></dd>
<dt><dfn>Scoping</dfn></dt>
<dd><p>The following HTML elements introduce new <span title="has
@@ -58711,7 +58686,7 @@
</dd>
<dt>A start tag whose tag name is one of: "base", "command",
- "eventsource", "link"</dt>
+ "link"</dt>
<dd>
<p><span>Insert an HTML element</span> for the token. Immediately
@@ -59068,8 +59043,7 @@
</dd>
<dt>A start tag token whose tag name is one of: "base", "command",
- "eventsource", "link", "meta", "noframes", "script", "style",
- "title"</dt>
+ "link", "meta", "noframes", "script", "style", "title"</dt>
<dd>
<p>Process the token <span>using the rules for</span> the "<span
title="insertion mode: in head">in head</span>" <span>insertion
@@ -60221,11 +60195,11 @@
"col", "colgroup", "frame", "head", "tbody", "td", "tfoot", "th",
"thead", "tr"</dt>
<!--<dt>An end tag whose tag name is one of: "area", "base",
- "basefont", "bgsound", "command", "embed", "eventsource", "hr",
- "iframe", "image", "img", "input", "isindex", "link", "meta",
- "noembed", "noframes", "param", "script", "select", "source",
- "spacer", "style", "table", "textarea", "title", "wbr"</dt>--> <!--
- add keygen if we add the start tag -->
+ "basefont", "bgsound", "command", "embed", "hr", "iframe", "image",
+ "img", "input", "isindex", "link", "meta", "noembed", "noframes",
+ "param", "script", "select", "source", "spacer", "style", "table",
+ "textarea", "title", "wbr"</dt>--> <!-- add keygen if we add the
+ start tag -->
<!--<dt>An end tag whose tag name is "noscript", if the
<span>scripting flag</span> is enabled</dt>-->
<dd>
@@ -62096,8 +62070,7 @@
node at this point.</p> <!-- also, i guess: image, isindex,
and keygen, but we don't list those because we don't consider
those "elements", more "macros", and thus we should never
- serialize them --> <!-- XXX when we get around to it, add
- eventsource -->
+ serialize them -->
<p>If <var title="">current node</var> is a <code>pre</code>,
<code>textarea</code>, or <code>listing</code> element, append
@@ -62770,9 +62743,10 @@
<pre class="css">@namespace url(http://www.w3.org/1999/xhtml);
[hidden], area, audio:not([controls]), base, basefont, command,
-datalist, eventsource, head, input[type=hidden], link,
-menu[type=context], meta, noembed, noframes, param, script, source,
-style, title { display: none; }
+datalist, head, input[type=hidden], link, menu[type=context], meta,
+noembed, noframes, param, script, source, style, title {
+ display: none;
+}
address, article, aside, blockquote, body, center, dd, dialog, dir,
div, dl, dt, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hr,
@@ -65533,9 +65507,10 @@
Dutta, Tantek Çelik, Terrence Wood, Thomas Broyer, Thomas
O'Connor, Tim Altman, Tim Johansson, Tommy Thorsen, Travis Leithead,
Tyler Close, Vladimir Vukićević, Wakaba, Wayne
- Pollock, Wellington Fernando de Macedo, William Swanson, Wolfram
- Kriesing, Yi-An Huang, Zhenbin Xu, and Øistein E. Andersen,
- for their useful and substantial comments.</p>
+ Pollock, Wellington Fernando de Macedo, William Swanson, Wladimir
+ Palant, Wolfram Kriesing, Yi-An Huang, Zhenbin Xu, and
+ Øistein E. Andersen, for their useful and substantial
+ comments.</p>
<p>Thanks also to everyone who has ever posted about HTML5 to their
blogs, public mailing lists, or forums, including the <a
More information about the Commit-Watchers
mailing list