[html5] r2877 - [] (0) Extract Web Sockets, Event Source, and Web Storage out of HTML5.
whatwg at whatwg.org
whatwg at whatwg.org
Wed Mar 18 12:31:54 PDT 2009
Author: ianh
Date: 2009-03-18 12:31:53 -0700 (Wed, 18 Mar 2009)
New Revision: 2877
Modified:
index
source
Log:
[] (0) Extract Web Sockets, Event Source, and Web Storage out of HTML5.
Modified: index
===================================================================
--- index 2009-03-18 06:49:56 UTC (rev 2876)
+++ index 2009-03-18 19:31:53 UTC (rev 2877)
@@ -183,7 +183,7 @@
document.getElementById('updatesEnabled').checked = true;
configureUpdates(true);
}
- </script><h3 class="no-num no-toc" id=stability-0>Stability</h3>
+ </script><!--START html5--><h3 class="no-num no-toc" id=stability-0>Stability</h3>
<p>Different parts of this specification are at different levels of
maturity.</p>
@@ -749,74 +749,42 @@
<li><a href=#unloading-documents><span class=secno>5.10.10 </span>Unloading documents</a>
<ol>
<li><a href=#event-definition><span class=secno>5.10.10.1 </span>Event definition</a></ol></ol></li>
- <li><a href=#structured-client-side-storage><span class=secno>5.11 </span>Structured client-side storage</a>
+ <li><a href=#links><span class=secno>5.11 </span>Links</a>
<ol>
- <li><a href=#storage><span class=secno>5.11.1 </span>Storing name/value pairs</a>
+ <li><a href=#hyperlink-elements><span class=secno>5.11.1 </span>Hyperlink elements</a></li>
+ <li><a href=#following-hyperlinks><span class=secno>5.11.2 </span>Following hyperlinks</a>
<ol>
- <li><a href=#introduction-3><span class=secno>5.11.1.1 </span>Introduction</a></li>
- <li><a href=#the-storage-interface><span class=secno>5.11.1.2 </span>The <code>Storage</code> interface</a></li>
- <li><a href=#the-sessionstorage-attribute><span class=secno>5.11.1.3 </span>The <code title=dom-sessionStorage>sessionStorage</code> attribute</a></li>
- <li><a href=#the-localstorage-attribute><span class=secno>5.11.1.4 </span>The <code title=dom-localStorage>localStorage</code> attribute</a></li>
- <li><a href=#the-storage-event><span class=secno>5.11.1.5 </span>The <code title=event-storage>storage</code> event</a>
- <ol>
- <li><a href=#event-definition-0><span class=secno>5.11.1.5.1 </span>Event definition</a></ol></li>
- <li><a href=#threads><span class=secno>5.11.1.6 </span>Threads</a></ol></li>
- <li><a href=#sql><span class=secno>5.11.2 </span>Database storage</a>
+ <li><a href=#hyperlink-auditing><span class=secno>5.11.2.1 </span>Hyperlink auditing</a></ol></li>
+ <li><a href=#linkTypes><span class=secno>5.11.3 </span>Link types</a>
<ol>
- <li><a href=#introduction-4><span class=secno>5.11.2.1 </span>Introduction</a></li>
- <li><a href=#databases><span class=secno>5.11.2.2 </span>Databases</a></li>
- <li><a href=#executing-sql-statements><span class=secno>5.11.2.3 </span>Executing SQL statements</a></li>
- <li><a href=#database-query-results><span class=secno>5.11.2.4 </span>Database query results</a></li>
- <li><a href=#errors><span class=secno>5.11.2.5 </span>Errors</a></li>
- <li><a href=#processing-model-2><span class=secno>5.11.2.6 </span>Processing model</a></ol></li>
- <li><a href=#disk-space><span class=secno>5.11.3 </span>Disk space</a></li>
- <li><a href=#privacy><span class=secno>5.11.4 </span>Privacy</a>
- <ol>
- <li><a href=#user-tracking><span class=secno>5.11.4.1 </span>User tracking</a></li>
- <li><a href=#cookie-resurrection><span class=secno>5.11.4.2 </span>Cookie resurrection</a></ol></li>
- <li><a href=#security-4><span class=secno>5.11.5 </span>Security</a>
- <ol>
- <li><a href=#dns-spoofing-attacks><span class=secno>5.11.5.1 </span>DNS spoofing attacks</a></li>
- <li><a href=#cross-directory-attacks><span class=secno>5.11.5.2 </span>Cross-directory attacks</a></li>
- <li><a href=#implementation-risks><span class=secno>5.11.5.3 </span>Implementation risks</a></li>
- <li><a href=#sql-and-user-agents><span class=secno>5.11.5.4 </span>SQL and user agents</a></li>
- <li><a href=#sql-injection><span class=secno>5.11.5.5 </span>SQL injection</a></ol></ol></li>
- <li><a href=#links><span class=secno>5.12 </span>Links</a>
- <ol>
- <li><a href=#hyperlink-elements><span class=secno>5.12.1 </span>Hyperlink elements</a></li>
- <li><a href=#following-hyperlinks><span class=secno>5.12.2 </span>Following hyperlinks</a>
- <ol>
- <li><a href=#hyperlink-auditing><span class=secno>5.12.2.1 </span>Hyperlink auditing</a></ol></li>
- <li><a href=#linkTypes><span class=secno>5.12.3 </span>Link types</a>
- <ol>
- <li><a href=#link-type-alternate><span class=secno>5.12.3.1 </span>Link type "<code>alternate</code>"</a></li>
- <li><a href=#link-type-archives><span class=secno>5.12.3.2 </span>Link type "<code>archives</code>"</a></li>
- <li><a href=#link-type-author><span class=secno>5.12.3.3 </span>Link type "<code>author</code>"</a></li>
- <li><a href=#link-type-bookmark><span class=secno>5.12.3.4 </span>Link type "<code>bookmark</code>"</a></li>
- <li><a href=#link-type-external><span class=secno>5.12.3.5 </span>Link type "<code>external</code>"</a></li>
- <li><a href=#link-type-feed><span class=secno>5.12.3.6 </span>Link type "<code>feed</code>"</a></li>
- <li><a href=#link-type-help><span class=secno>5.12.3.7 </span>Link type "<code>help</code>"</a></li>
- <li><a href=#rel-icon><span class=secno>5.12.3.8 </span>Link type "<code>icon</code>"</a></li>
- <li><a href=#link-type-license><span class=secno>5.12.3.9 </span>Link type "<code>license</code>"</a></li>
- <li><a href=#link-type-nofollow><span class=secno>5.12.3.10 </span>Link type "<code>nofollow</code>"</a></li>
- <li><a href=#link-type-noreferrer><span class=secno>5.12.3.11 </span>Link type "<code>noreferrer</code>"</a></li>
- <li><a href=#link-type-pingback><span class=secno>5.12.3.12 </span>Link type "<code>pingback</code>"</a></li>
- <li><a href=#link-type-prefetch><span class=secno>5.12.3.13 </span>Link type "<code>prefetch</code>"</a></li>
- <li><a href=#link-type-search><span class=secno>5.12.3.14 </span>Link type "<code>search</code>"</a></li>
- <li><a href=#link-type-stylesheet><span class=secno>5.12.3.15 </span>Link type "<code>stylesheet</code>"</a></li>
- <li><a href=#link-type-sidebar><span class=secno>5.12.3.16 </span>Link type "<code>sidebar</code>"</a></li>
- <li><a href=#link-type-tag><span class=secno>5.12.3.17 </span>Link type "<code>tag</code>"</a></li>
- <li><a href=#hierarchical-link-types><span class=secno>5.12.3.18 </span>Hierarchical link types</a>
+ <li><a href=#link-type-alternate><span class=secno>5.11.3.1 </span>Link type "<code>alternate</code>"</a></li>
+ <li><a href=#link-type-archives><span class=secno>5.11.3.2 </span>Link type "<code>archives</code>"</a></li>
+ <li><a href=#link-type-author><span class=secno>5.11.3.3 </span>Link type "<code>author</code>"</a></li>
+ <li><a href=#link-type-bookmark><span class=secno>5.11.3.4 </span>Link type "<code>bookmark</code>"</a></li>
+ <li><a href=#link-type-external><span class=secno>5.11.3.5 </span>Link type "<code>external</code>"</a></li>
+ <li><a href=#link-type-feed><span class=secno>5.11.3.6 </span>Link type "<code>feed</code>"</a></li>
+ <li><a href=#link-type-help><span class=secno>5.11.3.7 </span>Link type "<code>help</code>"</a></li>
+ <li><a href=#rel-icon><span class=secno>5.11.3.8 </span>Link type "<code>icon</code>"</a></li>
+ <li><a href=#link-type-license><span class=secno>5.11.3.9 </span>Link type "<code>license</code>"</a></li>
+ <li><a href=#link-type-nofollow><span class=secno>5.11.3.10 </span>Link type "<code>nofollow</code>"</a></li>
+ <li><a href=#link-type-noreferrer><span class=secno>5.11.3.11 </span>Link type "<code>noreferrer</code>"</a></li>
+ <li><a href=#link-type-pingback><span class=secno>5.11.3.12 </span>Link type "<code>pingback</code>"</a></li>
+ <li><a href=#link-type-prefetch><span class=secno>5.11.3.13 </span>Link type "<code>prefetch</code>"</a></li>
+ <li><a href=#link-type-search><span class=secno>5.11.3.14 </span>Link type "<code>search</code>"</a></li>
+ <li><a href=#link-type-stylesheet><span class=secno>5.11.3.15 </span>Link type "<code>stylesheet</code>"</a></li>
+ <li><a href=#link-type-sidebar><span class=secno>5.11.3.16 </span>Link type "<code>sidebar</code>"</a></li>
+ <li><a href=#link-type-tag><span class=secno>5.11.3.17 </span>Link type "<code>tag</code>"</a></li>
+ <li><a href=#hierarchical-link-types><span class=secno>5.11.3.18 </span>Hierarchical link types</a>
<ol>
- <li><a href=#link-type-index><span class=secno>5.12.3.18.1 </span>Link type "<code>index</code>"</a></li>
- <li><a href=#link-type-up><span class=secno>5.12.3.18.2 </span>Link type "<code>up</code>"</a></ol></li>
- <li><a href=#sequential-link-types><span class=secno>5.12.3.19 </span>Sequential link types</a>
+ <li><a href=#link-type-index><span class=secno>5.11.3.18.1 </span>Link type "<code>index</code>"</a></li>
+ <li><a href=#link-type-up><span class=secno>5.11.3.18.2 </span>Link type "<code>up</code>"</a></ol></li>
+ <li><a href=#sequential-link-types><span class=secno>5.11.3.19 </span>Sequential link types</a>
<ol>
- <li><a href=#link-type-first><span class=secno>5.12.3.19.1 </span>Link type "<code>first</code>"</a></li>
- <li><a href=#link-type-last><span class=secno>5.12.3.19.2 </span>Link type "<code>last</code>"</a></li>
- <li><a href=#link-type-next><span class=secno>5.12.3.19.3 </span>Link type "<code>next</code>"</a></li>
- <li><a href=#link-type-prev><span class=secno>5.12.3.19.4 </span>Link type "<code>prev</code>"</a></ol></li>
- <li><a href=#other-link-types><span class=secno>5.12.3.20 </span>Other link types</a></ol></ol></ol></li>
+ <li><a href=#link-type-first><span class=secno>5.11.3.19.1 </span>Link type "<code>first</code>"</a></li>
+ <li><a href=#link-type-last><span class=secno>5.11.3.19.2 </span>Link type "<code>last</code>"</a></li>
+ <li><a href=#link-type-next><span class=secno>5.11.3.19.3 </span>Link type "<code>next</code>"</a></li>
+ <li><a href=#link-type-prev><span class=secno>5.11.3.19.4 </span>Link type "<code>prev</code>"</a></ol></li>
+ <li><a href=#other-link-types><span class=secno>5.11.3.20 </span>Other link types</a></ol></ol></ol></li>
<li><a href=#editing><span class=secno>6 </span>User Interaction</a>
<ol>
<li><a href=#editing-intro><span class=secno>6.1 </span>Introduction</a></li>
@@ -840,7 +808,7 @@
<li><a href=#spelling-and-grammar-checking><span class=secno>6.8 </span>Spelling and grammar checking</a></li>
<li><a href=#dnd><span class=secno>6.9 </span>Drag and drop</a>
<ol>
- <li><a href=#introduction-5><span class=secno>6.9.1 </span>Introduction</a></li>
+ <li><a href=#introduction-3><span class=secno>6.9.1 </span>Introduction</a></li>
<li><a href=#the-dragevent-and-datatransfer-interfaces><span class=secno>6.9.2 </span>The <code>DragEvent</code> and <code>DataTransfer</code> interfaces</a></li>
<li><a href=#events-fired-during-a-drag-and-drop-action><span class=secno>6.9.3 </span>Events fired during a drag-and-drop action</a></li>
<li><a href=#drag-and-drop-processing-model><span class=secno>6.9.4 </span>Drag-and-drop processing model</a>
@@ -859,7 +827,7 @@
<li><a href=#security-risks-in-the-drag-and-drop-model><span class=secno>6.9.7 </span>Security risks in the drag-and-drop model</a></ol></li>
<li><a href=#undo><span class=secno>6.10 </span>Undo history</a>
<ol>
- <li><a href=#introduction-6><span class=secno>6.10.1 </span>Introduction</a></li>
+ <li><a href=#introduction-4><span class=secno>6.10.1 </span>Introduction</a></li>
<li><a href=#definitions-1><span class=secno>6.10.2 </span>Definitions</a></li>
<li><a href=#the-undomanager-interface><span class=secno>6.10.3 </span>The <code>UndoManager</code> interface</a></li>
<li><a href=#undo:-moving-back-in-the-undo-transaction-history><span class=secno>6.10.4 </span>Undo: moving back in the undo transaction history</a></li>
@@ -870,60 +838,22 @@
<li><a href=#comms><span class=secno>7 </span>Communication</a>
<ol>
<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>
+ <li><a href=#crossDocumentMessages><span class=secno>7.2 </span>Cross-document messaging</a>
<ol>
- <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=#feedback-from-the-protocol><span class=secno>7.3.3 </span>Feedback from the protocol</a>
+ <li><a href=#introduction-5><span class=secno>7.2.1 </span>Introduction</a></li>
+ <li><a href=#security-4><span class=secno>7.2.2 </span>Security</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.4 </span>The Web Socket
- protocol</a>
- <ol>
- <li><a href=#introduction-7><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.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.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>
+ <li><a href=#authors><span class=secno>7.2.2.1 </span>Authors</a></li>
+ <li><a href=#user-agents><span class=secno>7.2.2.2 </span>User agents</a></ol></li>
+ <li><a href=#posting-messages><span class=secno>7.2.3 </span>Posting messages</a></li>
+ <li><a href=#posting-messages-with-message-ports><span class=secno>7.2.4 </span>Posting messages with message ports</a></ol></li>
+ <li><a href=#channel-messaging><span class=secno>7.3 </span>Channel messaging</a>
<ol>
- <li><a href=#introduction-8><span class=secno>7.4.1 </span>Introduction</a></li>
- <li><a href=#security-5><span class=secno>7.4.2 </span>Security</a>
+ <li><a href=#introduction-6><span class=secno>7.3.1 </span>Introduction</a></li>
+ <li><a href=#message-channels><span class=secno>7.3.2 </span>Message channels</a></li>
+ <li><a href=#message-ports><span class=secno>7.3.3 </span>Message ports</a>
<ol>
- <li><a href=#authors><span class=secno>7.4.2.1 </span>Authors</a></li>
- <li><a href=#user-agents><span class=secno>7.4.2.2 </span>User agents</a></ol></li>
- <li><a href=#posting-messages><span class=secno>7.4.3 </span>Posting messages</a></li>
- <li><a href=#posting-messages-with-message-ports><span class=secno>7.4.4 </span>Posting messages with message ports</a></ol></li>
- <li><a href=#channel-messaging><span class=secno>7.5 </span>Channel messaging</a>
- <ol>
- <li><a href=#introduction-9><span class=secno>7.5.1 </span>Introduction</a></li>
- <li><a href=#message-channels><span class=secno>7.5.2 </span>Message channels</a></li>
- <li><a href=#message-ports><span class=secno>7.5.3 </span>Message ports</a>
- <ol>
- <li><a href=#ports-and-garbage-collection><span class=secno>7.5.3.1 </span>Ports and garbage collection</a></ol></ol></ol></li>
+ <li><a href=#ports-and-garbage-collection><span class=secno>7.3.3.1 </span>Ports and garbage collection</a></ol></ol></ol></li>
<li><a href=#syntax><span class=secno>8 </span>The HTML syntax</a>
<ol>
<li><a href=#writing-html-documents><span class=secno>8.1 </span>Writing HTML documents</a>
@@ -1038,10 +968,10 @@
<li><a href=#parsing-xhtml-fragments><span class=secno>9.4 </span>Parsing XHTML fragments</a></ol></li>
<li><a href=#rendering><span class=secno>10 </span>Rendering</a>
<ol>
- <li><a href=#introduction-10><span class=secno>10.1 </span>Introduction</a></li>
+ <li><a href=#introduction-7><span class=secno>10.1 </span>Introduction</a></li>
<li><a href=#the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>10.2 </span>The CSS user agent style sheet and presentational hints</a>
<ol>
- <li><a href=#introduction-11><span class=secno>10.2.1 </span>Introduction</a></li>
+ <li><a href=#introduction-8><span class=secno>10.2.1 </span>Introduction</a></li>
<li><a href=#display-types><span class=secno>10.2.2 </span>Display types</a></li>
<li><a href=#margins-and-padding><span class=secno>10.2.3 </span>Margins and padding</a></li>
<li><a href=#alignment><span class=secno>10.2.4 </span>Alignment</a></li>
@@ -1059,7 +989,7 @@
<li><a href=#tool-bars-0><span class=secno>10.3.5 </span>Tool bars</a></ol></li>
<li><a href=#bindings><span class=secno>10.4 </span>Bindings</a>
<ol>
- <li><a href=#introduction-12><span class=secno>10.4.1 </span>Introduction</a></li>
+ <li><a href=#introduction-9><span class=secno>10.4.1 </span>Introduction</a></li>
<li><a href=#the-bb-element-0><span class=secno>10.4.2 </span>The <code>bb</code> element</a></li>
<li><a href=#the-button-element-0><span class=secno>10.4.3 </span>The <code>button</code> element</a></li>
<li><a href=#the-datagrid-element><span class=secno>10.4.4 </span>The <code>datagrid</code> element</a></li>
@@ -8869,7 +8799,7 @@
<code><a href=#window>Window</a></code>, <code><a href=#location>Location</a></code>, <code><a href=#history-1>History</a></code>,
<code><a href=#applicationcache>ApplicationCache</a></code>, <code><a href=#undomanager>UndoManager</a></code>,
<code><a href=#navigator>Navigator</a></code>, and <code><a href=#selection-0>Selection</a></code> objects, the
- various <code><a href=#barprop>BarProp</a></code> objects, the two <code><a href=#storage-0>Storage</a></code>
+ various <code><a href=#barprop>BarProp</a></code> objects, the two <code>Storage</code>
objects, and the various <code><a href=#htmlcollection-0>HTMLCollection</a></code> objects. It
also includes all the WebIDL prototypes in the ECMAScript binding,
including the <code>Document</code> object's prototype.)</li>
@@ -38771,9 +38701,9 @@
// the user agent
readonly attribute <a href=#navigator>Navigator</a> <a href=#dom-navigator title=dom-navigator>navigator</a>; <!-- XXX IE6 also has window.clientInformation pointing to this same object -->
- readonly attribute <a href=#storage-0>Storage</a> <a href=#dom-localstorage title=dom-localStorage>localStorage</a>;
- readonly attribute <a href=#storage-0>Storage</a> <a href=#dom-sessionstorage title=dom-sessionStorage>sessionStorage</a>;
- <a href=#database>Database</a> <a href=#dom-opendatabase title=dom-opendatabase>openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
+ readonly attribute <span>Storage</span> <span title=dom-localStorage>localStorage</span>; <!-- XXX split into separate interface -->
+ readonly attribute <span>Storage</span> <span title=dom-sessionStorage>sessionStorage</span>;
+ <span>Database</span> <span title=dom-opendatabase>openDatabase</span>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize); <!-- XXX split into separate interface -->
readonly attribute <a href=#applicationcache>ApplicationCache</a> <a href=#dom-applicationcache title=dom-applicationCache>applicationCache</a>;
// user prompts
@@ -40796,7 +40726,7 @@
<dt><dfn id=handler-window-onstorage title=handler-window-onstorage><code>onstorage</code></dfn></dt> <!-- new -->
- <dd><p>Must be invoked whenever a <code title=event-storage><a href=#event-storage>storage</a></code> event is targeted at or bubbles
+ <dd><p>Must be invoked whenever a <code title=event-storage>storage</code> event is targeted at or bubbles
through the object.</dd>
<dt><dfn id=handler-window-onunload title=handler-window-onunload><code>onunload</code></dfn></dt> <!-- widely used -->
@@ -45005,1187 +44935,12 @@
- <h3 id=structured-client-side-storage><span class=secno>5.11 </span>Structured client-side storage</h3>
- <h4 id=storage><span class=secno>5.11.1 </span>Storing name/value pairs</h4>
+ <h3 id=links><span class=secno>5.11 </span>Links</h3>
- <h5 id=introduction-3><span class=secno>5.11.1.1 </span>Introduction</h5>
- <p><em>This section is non-normative.</em></p>
+ <h4 id=hyperlink-elements><span class=secno>5.11.1 </span>Hyperlink elements</h4>
- <p>This specification introduces two related mechanisms, similar to
- HTTP session cookies, for storing structured data on the client
- side. <a href=#refsRFC2109>[RFC2109]</a> <a href=#refsRFC2965>[RFC2965]</a></p>
-
- <p>The first is designed for scenarios where the user is carrying
- out a single transaction, but could be carrying out multiple
- transactions in different windows at the same time.</p>
-
- <p>Cookies don't really handle this case well. For example, a user
- could be buying plane tickets in two different windows, using the
- same site. If the site used cookies to keep track of which ticket
- the user was buying, then as the user clicked from page to page in
- both windows, the ticket currently being purchased would "leak" from
- one window to the other, potentially causing the user to buy two
- tickets for the same flight without really noticing.</p>
-
- <p>To address this, this specification introduces the <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> DOM attribute.
- Sites can add data to the session storage, and it will be accessible
- to any page from the same site opened in that window.</p> <!-- we're
- not using xrefs here because this is just an intro -->
-
- <div class=example>
-
- <p>For example, a page could have a checkbox that the user ticks to
- indicate that he wants insurance:</p>
-
- <pre><label>
- <input type="checkbox" onchange="sessionStorage.insurance = checked">
- I want insurance on this trip.
-</label></pre>
-
- <p>A later page could then check, from script, whether the user had
- checked the checkbox or not:</p>
-
- <pre>if (sessionStorage.insurance) { ... }</pre>
-
- <p>If the user had multiple windows opened on the site, each one
- would have its own individual copy of the session storage object.</p>
-
- </div>
-
- <!--
-
- sessionStorage.flightDeparture = 'OSL';
- sessionStorage.flightArrival = 'NYC';
-
- for (var i in forms[0].elements)
- sessionStorage["data_" + i.name] = i.value;
-
- if (!sessionStorage[documents])
- sessionStorage[documents] = {};
- sessionStorage[documents][filename] = <document/>;
-
- -->
-
- <p>The second storage mechanism is designed for storage that spans
- multiple windows, and lasts beyond the current session. In
- particular, Web applications may wish to store megabytes of user
- data, such as entire user-authored documents or a user's mailbox, on
- the client side for performance reasons.</p>
-
- <p>Again, cookies do not handle this case well, because they are
- transmitted with every request.</p>
-
- <p>The <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> DOM
- attribute is used to access a page's local storage area.</p>
-
- <div class=example>
-
- <p>The site at example.com can display a count of how many times
- the user has loaded its page by putting the following at the bottom
- of its page:</p>
-
- <pre><p>
- You have viewed this page
- <span id="count">an untold number of</span>
- time(s).
-</p>
-<script>
- if (!localStorage.pageLoadCount)
- localStorage.pageLoadCount = 0;
- localStorage.pageLoadCount = parseInt(localStorage.pageLoadCount, 10) + 1;
- document.getElementById('count').textContent = localStorage.pageLoadCount;
-</script></pre>
-
- <p>The use of <code title="">parseInt()</code> is needed when
- dealing with numbers (integers in this case) because the storage
- APIs are all string-based.</p>
-
- </div>
-
- <p>Each site has its own separate storage area.</p>
-
- <p>Storage areas (both session storage and local storage) store
- strings. To store structured data in a storage area, you must first
- convert it to a string.</p>
-
-
-
- <h5 id=the-storage-interface><span class=secno>5.11.1.2 </span>The <code><a href=#storage-0>Storage</a></code> interface</h5>
-
- <pre class=idl>interface <dfn id=storage-0>Storage</dfn> {
- readonly attribute unsigned long <a href=#dom-storage-length title=dom-Storage-length>length</a>;
- [IndexGetter] DOMString <a href=#dom-storage-key title=dom-Storage-key>key</a>(in unsigned long index);
- [NameGetter] DOMString <a href=#dom-storage-getitem title=dom-Storage-getItem>getItem</a>(in DOMString key);
- [NameSetter] void <a href=#dom-storage-setitem title=dom-Storage-setItem>setItem</a>(in DOMString key, in DOMString data);
- [NameDeleter] void <a href=#dom-storage-removeitem title=dom-Storage-removeItem>removeItem</a>(in DOMString key);
- void <a href=#dom-storage-clear title=dom-Storage-clear>clear</a>();
-};</pre>
-
- <!-- v2 ideas:
- a getInfo() method that returns an object that tells you:
- - when the key was added
- - when the key was last modified
- - which page was the last to modify the key
- [-Mihai Sucan]
- -->
-
- <p>Each <code><a href=#storage-0>Storage</a></code> object provides access to a list of
- key/value pairs, which are sometimes called items. Keys and values
- are strings. Any string (including the empty string) is a valid
- key.</p>
-
- <p class=note>To store more structured data, authors may consider
- using the <a href=#sql>SQL interfaces</a> instead.</p>
-
- <p>Each <code><a href=#storage-0>Storage</a></code> object is associated with a list of
- key/value pairs when it is created, as defined in the sections on
- the <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> and <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attributes. Multiple
- separate objects implementing the <code><a href=#storage-0>Storage</a></code> interface can
- all be associated with the same list of key/value pairs
- simultaneously.</p>
-
- <p>The object's <span>indices of the supported indexed
- properties</span> are the numbers in the range zero to one less than
- the number of key/value pairs currently present in the list
- associated with the object. If the list is empty, then there are no
- <span>supported indexed properties</span>.</p>
-
- <p>The <dfn id=dom-storage-length title=dom-Storage-length><code>length</code></dfn>
- attribute must return the number of key/value pairs currently
- present in the list associated with the object.</p>
-
- <p>The <dfn id=dom-storage-key title=dom-Storage-key><code>key(<var title="">n</var>)</code></dfn> method must return the name of the
- <var title="">n</var>th key in the list. The order of keys is
- user-agent defined, but must be consistent within an object between
- changes to the number of keys. (Thus, <a href=#dom-storage-setitem title=dom-Storage-setItem>adding</a> or <a href=#dom-storage-removeitem title=dom-Storage-removeItem>removing</a> a key may change the
- order of the keys, but merely changing the value of an existing key
- must not.) <!--The order of keys may differ between instances of the
- <code>Storage</code> interface accessing the same list. [removed for
- now for clarity, but if people ask, put it back. this is part of the
- spec.]--> If <var title="">n</var> is <!--less than zero or [can't,
- unsigned]--> greater than or equal to the number of key/value pairs
- in the object, then this method must raise an
- <code><a href=#index_size_err>INDEX_SIZE_ERR</a></code> exception.</p>
-
- <p>The <span>names of the supported named properties</span> on a
- <code><a href=#storage-0>Storage</a></code> object are the keys of each key/value pair
- currently present in the list associated with the object.</p>
-
- <p>The <dfn id=dom-storage-getitem title=dom-Storage-getItem><code>getItem(<var title="">key</var>)</code></dfn> method must return the current
- value associated with the given <var title="">key</var>. If the
- given <var title="">key</var> does not exist in the list associated
- with the object then this method must return null.</p>
-
- <p>The <dfn id=dom-storage-setitem title=dom-Storage-setItem><code>setItem(<var title="">key</var>, <var title="">value</var>)</code></dfn> method
- must first check if a key/value pair with the given <var title="">key</var> already exists in the list associated with the
- object.</p>
-
- <p>If it does not, then a new key/value pair must be added to the
- list, with the given <var title="">key</var> and <var title="">value</var>.</p>
-
- <p>If the given <var title="">key</var> <em>does</em> exist in the
- list, then it must have its value updated to the value given in the
- <var title="">value</var> argument.</p>
-
- <p>If it couldn't set the new value, the method must raise an
- <code><a href=#quota_exceeded_err>QUOTA_EXCEEDED_ERR</a></code> exception. (Setting could fail if,
- e.g., the user has disabled storage for the domain, or if the quota
- has been exceeded.)</p>
-
- <p>The <dfn id=dom-storage-removeitem title=dom-Storage-removeItem><code>removeItem(<var title="">key</var>)</code></dfn> method must cause the key/value
- pair with the given <var title="">key</var> to be removed from the
- list associated with the object, if it exists. If no item with that
- key exists, the method must do nothing.</p>
-
- <p>The <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code> and <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code> methods must be
- atomic with respect to failure. In the case of failure, the method
- does nothing. That is, changes to the data storage area must either
- be successful, or the data storage area must not be changed at
- all.</p>
-
- <p>The <dfn id=dom-storage-clear title=dom-Storage-clear><code>clear()</code></dfn>
- method must atomically cause the list associated with the object to
- be emptied of all key/value pairs, if there are any. If there are
- none, then the method must do nothing.</p>
-
- <p class=note>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are invoked, events
- are fired on other <code><a href=#htmldocument>HTMLDocument</a></code> objects that can access
- the newly stored or removed data, as defined in the sections on the
- <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> and <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attributes.</p> <!--
- not normative, see the sections below for the normative statement
- -->
-
- <p class=note>This specification does not require that the above
- methods wait until the data has been physically written to
- disk. Only consistency in what different scripts accessing the same
- underlying list of key/value pairs see is required.</p>
-
-
-
- <h5 id=the-sessionstorage-attribute><span class=secno>5.11.1.3 </span>The <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> attribute</h5>
-
- <p>The <dfn id=dom-sessionstorage title=dom-sessionStorage><code>sessionStorage</code></dfn>
- attribute represents the set of storage areas specific to the
- current <a href=#top-level-browsing-context>top-level browsing context</a>.</p>
-
- <p>Each <a href=#top-level-browsing-context>top-level browsing context</a> has a unique set of
- session storage areas, one for each <a href=#origin-0>origin</a>.</p>
-
- <p>User agents should not expire data from a browsing context's
- session storage areas, but may do so when the user requests that
- such data be deleted, or when the UA detects that it has limited
- storage space, or for security reasons. User agents should always
- avoid deleting data while a script that could access that data is
- running. When a top-level browsing context is destroyed (and
- therefore permanently inaccessible to the user) the data stored in
- its session storage areas can be discarded with it, as the API
- described in this specification provides no way for that data to
- ever be subsequently retrieved.</p>
-
- <p class=note>The lifetime of a browsing context can be unrelated
- to the lifetime of the actual user agent process itself, as the user
- agent may support resuming sessions after a restart.</p>
-
- <p>When a new <code><a href=#htmldocument>HTMLDocument</a></code> is created, the user agent
- must check to see if the document's <a href=#top-level-browsing-context>top-level browsing
- context</a> has allocated a session storage area for that
- document's <a href=#origin-0>origin</a>. If it has not, a new storage area
- for that document's <a href=#origin-0>origin</a> must be created.</p>
-
- <p>The <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code>
- attribute must return the <code><a href=#storage-0>Storage</a></code> object associated
- with that session storage area. Each <code>Document</code> object
- must have a separate object for its <code><a href=#window>Window</a></code>'s <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> attribute.</p>
-
- <p>When a new <a href=#top-level-browsing-context>top-level browsing context</a> is created by
- cloning an existing <a href=#browsing-context>browsing context</a>, the new browsing
- context must start with the same session storage areas as the
- original, but the two sets must from that point on be considered
- separate, not affecting each other in any way.</p>
-
- <p>When a new <a href=#top-level-browsing-context>top-level browsing context</a> is created by
- a <a href=#concept-script title=concept-script>script</a> in an existing
- <a href=#browsing-context>browsing context</a>, or by the user following a link in an
- existing browsing context, or in some other way related to a
- specific <code><a href=#htmldocument>HTMLDocument</a></code>, then the session storage area of
- the <a href=#origin-0>origin</a> of that <code><a href=#htmldocument>HTMLDocument</a></code> must be
- copied into the new browsing context when it is created. From that
- point on, however, the two session storage areas must be considered
- separate, not affecting each other in any way.</p>
-
- <p id=sessionStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a
- <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated
- with a session storage area, if the methods did something, then in
- every <code><a href=#htmldocument>HTMLDocument</a></code> object whose <code><a href=#window>Window</a></code>
- object's <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code>
- attribute's <code><a href=#storage-0>Storage</a></code> object is associated with the same
- storage area, other than <var title="">x</var>, a <code title=event-storage><a href=#event-storage>storage</a></code> event must be fired, as <a href=#event-storage title=event-storage>described below</a>.</p>
-
-
- <h5 id=the-localstorage-attribute><span class=secno>5.11.1.4 </span>The <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attribute</h5>
-
- <p>The <dfn id=dom-localstorage title=dom-localStorage><code>localStorage</code></dfn>
- object provides a <code><a href=#storage-0>Storage</a></code> object for an
- <a href=#origin-0>origin</a>.</p>
-
- <p>User agents must have a set of local storage areas, one for each
- <a href=#origin-0>origin</a>.</p>
-
- <p>User agents should expire data from the local storage areas only
- for security reasons or when requested to do so by the user. User
- agents should always avoid deleting data while a script that could
- access that data is running. Data stored in local storage areas
- should be considered potentially user-critical. It is expected that
- Web applications will use the local storage areas for storing
- user-written documents.</p>
-
- <p>When the <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code>
- attribute is accessed, the user agent must check to see if it has
- allocated a local storage area for the <a href=#origin-0>origin</a> of the
- <code>Document</code> of the <code><a href=#window>Window</a></code> object on which the
- method was invoked. If it has not, a new storage area for that
- <a href=#origin-0>origin</a> must be created.</p>
-
- <p>The user agent must then return the <code><a href=#storage-0>Storage</a></code> object
- associated with that origin's local storage area. Each
- <code>Document</code> object must have a separate object for its
- <code><a href=#window>Window</a></code>'s <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attribute.</p>
-
- <p id=localStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a
- <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated
- with a local storage area, if the methods did something, then in
- every <code><a href=#htmldocument>HTMLDocument</a></code> object whose <code><a href=#window>Window</a></code>
- object's <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code>
- attribute's <code><a href=#storage-0>Storage</a></code> object is associated with the same
- storage area, other than <var title="">x</var>, a <code title=event-storage><a href=#event-storage>storage</a></code> event must be fired, as <a href=#event-storage title=event-storage>described below</a>.</p>
-
-
- <h5 id=the-storage-event><span class=secno>5.11.1.5 </span>The <code title=event-storage><a href=#event-storage>storage</a></code> event</h5>
-
- <!-- XXX fix up for workers: target is wrong, source and storageArea
- definitions are wrong -->
-
- <p>The <dfn id=event-storage title=event-storage><code>storage</code></dfn> event
- is fired when a storage area changes, as described in the previous
- two sections (<a href=#sessionStorageEvent>for session
- storage</a>, <a href=#localStorageEvent>for local
- storage</a>).</p>
-
- <p>When this happens, the user agent must dispatch an event with the
- name <code><a href=#storage-0>storage</a></code>, with no namespace, which does not bubble
- but is cancelable, and which uses the <code><a href=#storageevent>StorageEvent</a></code>
- interface, at each <code><a href=#window>Window</a></code> object whose
- <code>Document</code> object both has a <code><a href=#storage-0>Storage</a></code> object
- that is affected, and is <a href=#fully-active>fully active</a>.</p>
-
- <p>If the event is being fired due to an invocation of the
- <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code> or <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code> methods, the
- event must have its <code title=dom-StorageEvent-key><a href=#dom-storageevent-key>key</a></code>
- attribute set to the name of the key in question, its <code title=dom-StorageEvent-oldValue><a href=#dom-storageevent-oldvalue>oldValue</a></code> attribute set to
- the old value of the key in question, or null if the key is newly
- added, and its <code title=dom-StorageEvent-newValue><a href=#dom-storageevent-newvalue>newValue</a></code>
- attribute set to the new value of the key in question, or null if
- the key was removed.</p>
-
- <p>Otherwise, if the event is being fired due to an invocation of
- the <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> method, the event
- must have its <code title=dom-StorageEvent-key><a href=#dom-storageevent-key>key</a></code>, <code title=dom-StorageEvent-oldValue><a href=#dom-storageevent-oldvalue>oldValue</a></code>, and <code title=dom-StorageEvent-newValue><a href=#dom-storageevent-newvalue>newValue</a></code> attributes set to
- null.</p>
-
- <p>In addition, the event must have its <code title=dom-StorageEvent-url><a href=#dom-storageevent-url>url</a></code> attribute set to <a href="#the-document's-address" title="the document's address">the address of the document</a>
- whose <code><a href=#storage-0>Storage</a></code> object was affected; its <code title=dom-StorageEvent-source><a href=#dom-storageevent-source>source</a></code> attribute set to the
- that document's <a href=#browsing-context>browsing context</a>'s
- <code><a href=#windowproxy>WindowProxy</a></code> object, if the two documents are in the
- same <a href=#unit-of-related-browsing-contexts>unit of related browsing contexts</a>, or null
- otherwise; and its <code title=dom-StorageEvent-storageArea><a href=#dom-storageevent-storagearea>storageArea</a></code> attribute
- set to the <code><a href=#storage-0>Storage</a></code> object from the <code><a href=#window>Window</a></code>
- object of the target <code>Document</code> that represents the same
- kind of <code><a href=#storage-0>Storage</a></code> area as was affected (i.e. session or
- local).</p>
-
-
- <h6 id=event-definition-0><span class=secno>5.11.1.5.1 </span>Event definition</h6>
-
- <pre class=idl>interface <dfn id=storageevent>StorageEvent</dfn> : Event {
- readonly attribute DOMString <a href=#dom-storageevent-key title=dom-StorageEvent-key>key</a>;
- readonly attribute DOMString <a href=#dom-storageevent-oldvalue title=dom-StorageEvent-oldValue>oldValue</a>;
- readonly attribute DOMString <a href=#dom-storageevent-newvalue title=dom-StorageEvent-newValue>newValue</a>;
- readonly attribute DOMString <a href=#dom-storageevent-url title=dom-StorageEvent-url>url</a>;
- readonly attribute <a href=#windowproxy>WindowProxy</a> <a href=#dom-storageevent-source title=dom-StorageEvent-source>source</a>;
- readonly attribute <a href=#storage-0>Storage</a> <a href=#dom-storageevent-storagearea title=dom-StorageEvent-storageArea>storageArea</a>;
- void <a href=#dom-storageevent-initstorageevent title=dom-StorageEvent-initStorageEvent>initStorageEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString urlArg, in <a href=#windowproxy>WindowProxy</a> sourceArg, in <a href=#storage-0>Storage</a> storageAreaArg);
- void <a href=#dom-storageevent-initstorageeventns title=dom-StorageEvent-initStorageEventNS>initStorageEventNS</a>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString keyArg, in DOMString oldValueArg, in DOMString newValueArg, in DOMString urlArg, in <a href=#windowproxy>WindowProxy</a> sourceArg, in <a href=#storage-0>Storage</a> storageAreaArg);
-};</pre>
-
- <p>The <dfn id=dom-storageevent-initstorageevent title=dom-StorageEvent-initStorageEvent><code>initStorageEvent()</code></dfn>
- and <dfn id=dom-storageevent-initstorageeventns title=dom-StorageEvent-initStorageEventNS><code>initStorageEventNS()</code></dfn>
- methods must initialize the event in a manner analogous to the
- similarly-named methods in the DOM3 Events interfaces. <a href=#refsDOM3EVENTS>[DOM3EVENTS]</a></p>
-
- <p>The <dfn id=dom-storageevent-key title=dom-StorageEvent-key><code>key</code></dfn>
- attribute represents the key being changed.</p>
-
- <p>The <dfn id=dom-storageevent-oldvalue title=dom-StorageEvent-oldValue><code>oldValue</code></dfn>
- attribute represents the old value of the key being changed.</p>
-
- <p>The <dfn id=dom-storageevent-newvalue title=dom-StorageEvent-newValue><code>newValue</code></dfn>
- attribute represents the new value of the key being changed.</p>
-
- <p>The <dfn id=dom-storageevent-url title=dom-StorageEvent-url><code>url</code></dfn>
- attribute represents the address of the document whose key
- changed.</p>
-
- <p>The <dfn id=dom-storageevent-source title=dom-StorageEvent-source><code>source</code></dfn> attribute
- represents the <code><a href=#windowproxy>WindowProxy</a></code> object of the <a href=#browsing-context>browsing
- context</a> of the document whose key changed.</p>
-
- <p>The <dfn id=dom-storageevent-storagearea title=dom-StorageEvent-storageArea><code>storageArea</code></dfn>
- attribute represents the <code><a href=#storage-0>Storage</a></code> object that was
- affected.</p>
-
-
-
- <h5 id=threads><span class=secno>5.11.1.6 </span>Threads</h5>
-
- <p>Multiple browsing contexts must be able to access the local
- storage areas simultaneously in such a manner that scripts cannot
- detect any concurrent script execution.</p>
-
- <p>This is required to guarantee that the <code title=dom-Storage-length><a href=#dom-storage-length>length</a></code> attribute of a
- <code><a href=#storage-0>Storage</a></code> object never changes while a script is
- executing, other than in a way that is predictable by the script
- itself.</p>
-
- <p class=note>There are various ways of implementing this
- requirement. One is to just have one <a href=#event-loop>event loop</a> for all
- <a href=#browsing-context title="browsing context">browsing contexts</a>. Another is
- that if a script running in one browsing context accesses a storage
- area, the user agent blocks scripts in other browsing contexts when
- they try to access the same storage area until the <a href=#event-loop>event
- loop</a> running the first script has completed running the task
- that started that script. Another (potentially more efficient but
- certainly more complex) implementation strategy is to use optimistic
- transactional script execution. This specification does not require
- any particular implementation strategy, so long as the requirement
- above is met.</p>
-
-
- <h4 id=sql><span class=secno>5.11.2 </span>Database storage</h4>
-
- <!-- Feature requests for future versions (v2):
- * deleting databases
- * determining how much storage room is left
- * handling the database getting corrupted
- -->
-
- <h5 id=introduction-4><span class=secno>5.11.2.1 </span>Introduction</h5>
-
- <p><em>This section is non-normative.</em></p>
-
- <p class=XXX>...</p>
-
-<!-- include an example that does something like the following to show
-you should never embed strings straight into the statement, even when you
-have a variable and unknowable number of literals coming:
- var q = "";
- for each (var i in array)
- q += (q == "" ? "" : ", ") + "?";
- executeSql('SELECT rowid FROM t WHERE c IN (' + q + ')', array, ...);
--->
-
-
- <h5 id=databases><span class=secno>5.11.2.2 </span>Databases</h5>
-
- <p>Each <i><a href=#origin-0>origin</a></i> has an associated set of databases. Each
- database has a name and a current version. There is no way to
- enumerate or delete the databases available for a domain from this
- API.</p>
-
- <p class=note>Each database has one version at a time; a database
- can't exist in multiple versions at once. Versions are intended to
- allow authors to manage schema changes incrementally and
- non-destructively, and without running the risk of old code (e.g. in
- another browser window) trying to write to a database with incorrect
- assumptions.</p>
-
- <p>The <dfn id=dom-opendatabase title=dom-opendatabase><code>openDatabase()</code></dfn> method
- returns a <code><a href=#database>Database</a></code> object. The method takes four
- arguments: a database name, a database version, a display name, and
- an estimated size, in bytes, of the data that will be stored in the
- database.</p>
-
- <p>The <code title=dom-opendatabase><a href=#dom-opendatabase>openDatabase()</a></code> method
- must use and create databases from the <a href=#origin-0>origin</a> of the
- <code>Document</code> of the <code><a href=#window>Window</a></code> object on which the
- method was invoked.</p>
-
- <p>If the database version provided is not the empty string, and the
- database already exists but has a different version, or no version,
- then the method must raise an <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code>
- exception.</p>
-
- <p>Otherwise, if the database version provided is the empty string,
- or if the database doesn't yet exist, or if the database exists and
- the version provided to the <code title=dom-opendatabase><a href=#dom-opendatabase>openDatabase()</a></code> method is the same as
- the current version associated with the database, then the method
- must return a <code><a href=#database>Database</a></code> object representing the database
- that has the name that was given. If no such database exists, it
- must be created first.</p>
-
- <p>All strings including the empty string are valid database
- names. Database names must be compared in a
- <a href=#case-sensitive>case-sensitive</a> manner.</p>
-
- <p>The user agent may raise a <code><a href=#security_err>SECURITY_ERR</a></code> exception
- instead of returning a <code><a href=#database>Database</a></code> object if the request
- violates a policy decision (e.g. if the user agent is configured to
- not allow the page to open databases).</p>
-
- <p class=note>Implementations can support this even in
- environments that only support a subset of all strings as database
- names by mapping database names (e.g. using a hashing algorithm) to
- the supported set of names.</p>
-
- <p>User agents are expected to use the display name and the
- estimated database size to optimize the user experience. For
- example, a user agent could use the estimated size to suggest an
- initial quota to the user. This allows a site that is aware that it
- will try to use hundreds of megabytes to declare this upfront,
- instead of the user agent prompting the user for permission to
- increase the quota every five megabytes.</p>
-
- <pre class=idl>interface <dfn id=database>Database</dfn> {
- void <a href=#dom-database-transaction title=dom-database-transaction>transaction</a>(in <a href=#sqltransactioncallback>SQLTransactionCallback</a> callback, [Optional] in <a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a> errorCallback, [Optional] in <a href=#sqlvoidcallback>SQLVoidCallback</a> successCallback);
- void <a href=#dom-database-readtransaction title=dom-database-readTransaction>readTransaction</a>(in <a href=#sqltransactioncallback>SQLTransactionCallback</a> callback, [Optional] in <a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a> errorCallback, [Optional] in <a href=#sqlvoidcallback>SQLVoidCallback</a> successCallback);
-
- readonly attribute DOMString <a href=#dom-database-version title=dom-database-version>version</a>;
- void <a href=#dom-database-changeversion title=dom-database-changeVersion>changeVersion</a>(in DOMString oldVersion, in DOMString newVersion, in <a href=#sqltransactioncallback>SQLTransactionCallback</a> callback, in <a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a> errorCallback, in <a href=#sqlvoidcallback>SQLVoidCallback</a> successCallback);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id=sqlvoidcallback>SQLVoidCallback</dfn> {
- void <span title=dom-sqlvoidcallback-handleEvent>handleEvent</span>();
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id=sqltransactioncallback>SQLTransactionCallback</dfn> {
- void <span title=dom-sqltransactioncallback-handleEvent>handleEvent</span>(in <a href=#sqltransaction>SQLTransaction</a> transaction);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id=sqltransactionerrorcallback>SQLTransactionErrorCallback</dfn> {
- void <span title=dom-sqltransactionerrorcallback-handleEvent>handleEvent</span>(in <a href=#sqlerror>SQLError</a> error);
-};</pre>
-
- <p>The <dfn id=dom-database-transaction title=dom-database-transaction><code>transaction()</code></dfn>
- and <dfn id=dom-database-readtransaction title=dom-database-readTransaction><code>readTransaction()</code></dfn>
- methods takes one to three arguments. When called, these method must
- immediately return and then asynchronously run the <a href=#transaction-steps>transaction
- steps</a> with the <i>transaction callback</i> being the first
- argument, the <i>error callback</i> being the second argument, if
- any, the <i>success callback</i> being the third argument, if any,
- and with no <i>preflight operation</i> or <i>postflight
- operation</i>.</p>
-
- <p>For the <code title=dom-database-transaction><a href=#dom-database-transaction>transaction()</a></code> method, the
- <i>mode</i> must be read/write. For the <code title=dom-database-readTransaction><a href=#dom-database-readtransaction>readTransaction()</a></code>
- method, the <i>mode</i> must be read-only.</p>
-
- <p>The version that the database was opened with is the <dfn id=concept-database-expected-version title=concept-database-expected-version>expected version</dfn> of
- this <code><a href=#database>Database</a></code> object. It can be the empty string, in
- which case there is no expected version — any version is
- fine.</p>
-
- <p>On getting, the <dfn id=dom-database-version title=dom-database-version><code>version</code></dfn> attribute
- must return the current version of the database (as opposed to the
- <a href=#concept-database-expected-version title=concept-database-expected-version>expected
- version</a> of the <code><a href=#database>Database</a></code> object).</p>
-
- <p>The <dfn id=dom-database-changeversion title=dom-database-changeVersion><code>changeVersion()</code></dfn>
- method allows scripts to atomically verify the version number and
- change it at the same time as doing a schema update. When the method
- is invoked, it must immediately return, and then asynchronously run
- the <a href=#transaction-steps>transaction steps</a> with the <i>transaction
- callback</i> being the third argument, the <i>error callback</i>
- being the fourth argument, the <i>success callback</i> being the
- fifth argument, the <i>preflight operation</i> being the
- following:</p>
-
- <ol><li><p>Check that the value of the first argument to the <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code> method
- exactly matches the database's actual version. If it does not, then
- the <i>preflight operation</i> fails.</li>
-
- </ol><p>...the <i>postflight operation</i> being the following:</p>
-
- <ol><li>Change the database's actual version to the value of the second
- argument to the <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
- method.</li>
-
- <li>Change the <code><a href=#database>Database</a></code> object's expected version to
- the value of the second argument to the <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
- method.</li>
-
- </ol><p>...and the <i>mode</i> being read/write.</p>
-
-
- <h5 id=executing-sql-statements><span class=secno>5.11.2.3 </span>Executing SQL statements</h5>
-
- <p>The <code title=dom-database-transaction><a href=#dom-database-transaction>transaction()</a></code>
- and <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
- methods invoke callbacks with <code><a href=#sqltransaction>SQLTransaction</a></code>
- objects.</p>
-
- <pre class=idl>typedef sequence<any> <dfn id=objectarray>ObjectArray</dfn>;
-
-interface <dfn id=sqltransaction>SQLTransaction</dfn> {
- void <a href=#dom-sqltransaction-executesql title=dom-sqltransaction-executeSql>executeSql</a>(in DOMString sqlStatement, [Optional] in <a href=#objectarray>ObjectArray</a> arguments, [Optional] in <a href=#sqlstatementcallback>SQLStatementCallback</a> callback, [Optional] in <a href=#sqlstatementerrorcallback>SQLStatementErrorCallback</a> errorCallback);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id=sqlstatementcallback>SQLStatementCallback</dfn> {
- void <span title=dom-sqlstatementcallback-handleEvent>handleEvent</span>(in <a href=#sqltransaction>SQLTransaction</a> transaction, in <a href=#sqlresultset>SQLResultSet</a> resultSet);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id=sqlstatementerrorcallback>SQLStatementErrorCallback</dfn> {
- boolean <span title=dom-sqlstatementerrorcallback-handleEvent>handleEvent</span>(in <a href=#sqltransaction>SQLTransaction</a> transaction, in <a href=#sqlerror>SQLError</a> error);
-};</pre>
-
- <p>When the <dfn id=dom-sqltransaction-executesql title=dom-sqltransaction-executeSql><code>executeSql(<var title="">sqlStatement</var>, <var title="">arguments</var>, <var title="">callback</var>, <var title="">errorCallback</var>)</code></dfn> method is invoked, the
- user agent must run the following algorithm. (This algorithm is
- relatively simple in that it doesn't actually execute any SQL
- — the bulk of the work is actually done as part of the
- <a href=#transaction-steps>transaction steps</a>.)</p>
-
- <ol><li><p>If the method was not invoked during the execution of a
- <code><a href=#sqltransactioncallback>SQLTransactionCallback</a></code>,
- <code><a href=#sqlstatementcallback>SQLStatementCallback</a></code>, or
- <code><a href=#sqlstatementerrorcallback>SQLStatementErrorCallback</a></code> then raise an
- <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception. (Calls from inside a
- <code><a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a></code> thus raise an
- exception. The <code><a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a></code> handler is
- only called once a transaction has failed, and no SQL statements
- can be added to a failed transaction.)</li>
-
- <li><p>Parse the first argument to the method (<var title="">sqlStatement</var>) as a SQL statement, with the exception
- that U+003F QUESTION MARK (?) characters can be used in place of
- SQL literals in the statement. <a href=#refsSQL>[SQL]</a></li>
-
- <li>
-
- <p>Replace each <code title="">?</code> placeholder with the value
- of the argument in the <var title="">arguments</var> array with
- the same position. (So the first <code title="">?</code>
- placeholder gets replaced by the first value in the <var title="">arguments</var> array, and generally the <var title="">n</var>th <code title="">?</code> placeholder gets
- replaced by the <var title="">n</var>th value in the <var title="">arguments</var> array.)</p>
-
- <p class=note>Substitutions for <code title="">?</code>
- placeholders are done at the literal level, not as string
- concatenations, so this provides a way to dynamically insert
- parameters into a statement without risk of a SQL injection
- attack.</p>
-
- <p>If the second argument is omitted or null, then treat the <var title="">arguments</var> array as empty.</p>
-
- <p>The result is <i>the statement</i>.</p>
-
- <p class=XXX>Implementation feedback is requested on what
- to do with arguments that are of types that are not supported by
- the underlying SQL backend. For example, SQLite doesn't support
- booleans, so what should the UA do if passed a boolean? The Gears
- team suggests failing, not silently converting types.</p>
-
- </li>
-
- <li><p>If the syntax of <var title="">sqlStatement</var> is not
- valid (except for the use of <code title="">?</code> characters in
- the place of literals), or the statement uses features that are not
- supported (e.g. due to security reasons), or the number of items in
- the <var title="">arguments</var> array is not equal to the number
- of <code title="">?</code> placeholders in the statement, or the
- statement cannot be parsed for some other reason, then mark <i>the
- statement</i> as bogus.</li>
-
- <li><p>If the <code><a href=#database>Database</a></code> object that the
- <code><a href=#sqltransaction>SQLTransaction</a></code> object was created from has an <a href=#concept-database-expected-version title=concept-database-expected-version>expected version</a>
- that is neither the empty string nor the actual version of the
- database, then mark <i>the statement</i> as bogus. (<a href=#dom-sqlerror-code-2 title=dom-sqlerror-code-2>Error code 2</a>.)</li>
-
- <li><p>Queue up <i>the statement</i> in the transaction, along with
- the third argument (if any) as the statement's result set callback
- and the fourth argument (if any) as the error callback.</li>
-
- </ol><p>The user agent must act as if the database was hosted in an
- otherwise completely empty environment with no resources. For
- example, attempts to read from or write to the file system will
- fail.</p>
-
-
- <p>SQL inherently supports multiple concurrent connections. Authors
- should make appropriate use of the transaction features to handle
- the case of multiple scripts interacting with the same database
- simultaneously (as could happen if the same page was opened in two
- different <a href=#browsing-context title="browsing context">browsing
- contexts</a>).</p>
-
- <p>User agents must consider statements that use the <code title="">BEGIN</code>, <code title="">COMMIT</code>, and <code title="">ROLLBACK</code> SQL features as being unsupported (and thus
- will mark them as bogus), so as to not let these statements
- interfere with the explicit transactions managed by the database API
- itself.</p>
-
- <p class=note>A future version of this specification will probably
- define the exact SQL subset required in more detail.</p>
-
-
- <h5 id=database-query-results><span class=secno>5.11.2.4 </span>Database query results</h5>
-
- <p>The <code title=dom-transaction-executeSql>executeSql()</code>
- method invokes its callback with a <code><a href=#sqlresultset>SQLResultSet</a></code> object
- as an argument.</p>
-
- <pre class=idl>interface <dfn id=sqlresultset>SQLResultSet</dfn> {
- readonly attribute long <a href=#dom-sqlresultset-insertid title=dom-SQLResultSet-insertId>insertId</a>;
- readonly attribute long <a href=#dom-sqlresultset-rowsaffected title=dom-SQLResultSet-rowsAffected>rowsAffected</a>;
- readonly attribute <a href=#sqlresultsetrowlist>SQLResultSetRowList</a> <a href=#dom-sqlresultset-rows title=dom-SQLResultSet-rows>rows</a>;
-};</pre>
-
- <p>The <dfn id=dom-sqlresultset-insertid title=dom-SQLResultSet-insertId><code>insertId</code></dfn>
- attribute must return the row ID of the row that the
- <code><a href=#sqlresultset>SQLResultSet</a></code> object's SQL statement inserted into the
- database, if the statement inserted a row. If the statement inserted
- multiple rows, the ID of the last row must be the one returned. If
- the statement did not insert a row, then the attribute must instead
- raise an <code><a href=#invalid_access_err>INVALID_ACCESS_ERR</a></code> exception.</p>
-
- <p>The <dfn id=dom-sqlresultset-rowsaffected title=dom-SQLResultSet-rowsAffected><code>rowsAffected</code></dfn>
- attribute must return the number of rows that were affected by the
- SQL statement. If the statement did not affected any rows, then the
- attribute must return zero. For "SELECT" statements, this returns
- zero (querying the database doesn't affect any rows).</p>
-
- <p>The <dfn id=dom-sqlresultset-rows title=dom-SQLResultSet-rows><code>rows</code></dfn>
- attribute must return a <code><a href=#sqlresultsetrowlist>SQLResultSetRowList</a></code>
- representing the rows returned, in the order returned by the
- database. If no rows were returned, then the object will be empty
- (its <code title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></code> will
- be zero).</p>
-
- <pre class=idl>interface <dfn id=sqlresultsetrowlist>SQLResultSetRowList</dfn> {
- readonly attribute unsigned long <a href=#dom-sqlresultsetrowlist-length title=dom-SQLResultSetRowList-length>length</a>;
- [IndexGetter] <span>any</span> <a href=#dom-sqlresultsetrowlist-item title=dom-SQLResultSetRowList-item>item</a>(in unsigned long index);
-};</pre>
-
- <p><code><a href=#sqlresultsetrowlist>SQLResultSetRowList</a></code> objects have a <dfn id=dom-sqlresultsetrowlist-length title=dom-SQLResultSetRowList-length><code>length</code></dfn>
- attribute that must return the number of rows it represents (the
- number of rows returned by the database). This is the <var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var>.</p>
-
- <p>The object's <span>indices of the supported indexed
- properties</span> are the numbers in the range zero to <span><var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var>-1</span>, unless
- the <var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var> is
- zero, in which case there are no <span>supported indexed
- properties</span>.</p>
-
- <p>The <dfn id=dom-sqlresultsetrowlist-item title=dom-SQLResultSetRowList-item><code>item(<var title="">index</var>)</code></dfn> attribute must return the row
- with the given index <var title="">index</var>. If there is no such
- row, then the method must raise an <code><a href=#index_size_err>INDEX_SIZE_ERR</a></code>
- exception.</p>
-
- <p>Each row must be represented by a native ordered dictionary data
- type. In the ECMAScript binding, this must be <code><a href=#the-object-element>Object</a></code>.
- Each row object must have one property (or dictionary entry) per
- column, with those properties enumerating in the order that these
- columns were returned by the database. Each property must have the
- name of the column and the value of the cell, as they were returned
- by the database.</p>
-
-
- <h5 id=errors><span class=secno>5.11.2.5 </span>Errors</h5>
-
- <p>Errors in the database API are reported using callbacks that have
- a <code><a href=#sqlerror>SQLError</a></code> object as one of their arguments.</p>
-
- <pre class=idl>interface <dfn id=sqlerror>SQLError</dfn> {
- readonly attribute unsigned long <a href=#dom-sqlerror-code title=dom-SQLError-code>code</a>;
- readonly attribute DOMString <a href=#dom-sqlerror-message title=dom-SQLError-message>message</a>;
-};</pre>
-
- <p>The <dfn id=dom-sqlerror-code title=dom-SQLError-code><code>code</code></dfn> DOM
- attribute must return the most appropriate code from the following
- table:</p>
-
- <table><thead><tr><th>Code
- <th>Situation
- <tbody><tr><td><dfn id=dom-sqlerror-code-0 title=dom-sqlerror-code-0>0</dfn>
- <td>The transaction failed for reasons unrelated to the database
- itself and not covered by any other error code.
-
- <tr><td><dfn id=dom-sqlerror-code-1 title=dom-sqlerror-code-1>1</dfn>
- <td>The statement failed for database reasons not covered by any
- other error code.
-
- <tr><td><dfn id=dom-sqlerror-code-2 title=dom-sqlerror-code-2>2</dfn>
- <td>The statement failed because the <a href=#concept-database-expected-version title=concept-database-expected-version>expected version</a>
- of the database didn't match the actual database version.
-
- <tr><td><dfn id=dom-sqlerror-code-3 title=dom-sqlerror-code-3>3</dfn>
- <td>The statement failed because the data returned from the
- database was too large. The SQL "LIMIT" modifier might be useful
- to reduce the size of the result set.
-
- <tr><td><dfn id=dom-sqlerror-code-4 title=dom-sqlerror-code-4>4</dfn>
- <td>The statement failed because there was not enough remaining
- storage space, or the storage quota was reached and the user
- declined to give more space to the database.
-
- <tr><td><dfn id=dom-sqlerror-code-5 title=dom-sqlerror-code-5>5</dfn>
- <td>The statement failed because the transaction's first
- statement was a read-only statement, and a subsequent statement
- in the same transaction tried to modify the database, but the
- transaction failed to obtain a write lock before another
- transaction obtained a write lock and changed a part of the
- database that the former transaction was depending upon.
-
- <tr><td><dfn id=dom-sqlerror-code-6 title=dom-sqlerror-code-6>6</dfn>
- <td>An <code title="">INSERT</code>, <code title="">UPDATE</code>, or <code title="">REPLACE</code>
- statement failed due to a constraint failure. For example,
- because a row was being inserted and the value given for the
- primary key column duplicated the value of an existing row.
-
- </table><p class=XXX>We should define a more thorough list of
- codes. Implementation feedback is requested to determine what codes
- are needed.</p>
-
- <p>The <dfn id=dom-sqlerror-message title=dom-SQLError-message><code>message</code></dfn>
- DOM attribute must return an error message describing the error
- encountered. The message should be localized to the user's
- language.</p>
-
-
-
- <h5 id=processing-model-2><span class=secno>5.11.2.6 </span>Processing model</h5>
-
- <p>The <dfn id=transaction-steps>transaction steps</dfn> are as follows. These steps must
- be run asynchronously. These steps are invoked with a <i>transaction
- callback</i>, optionally an <i>error callback</i>, optionally a
- <i>success callback</i>, optionally a <i>preflight operation</i>,
- optionally a <i>postflight operation</i>, and with a <i>mode</i>
- that is either read/write or read-only.</p>
-
- <ol><li><p>Open a new SQL transaction to the database, and create a
- <code><a href=#sqltransaction>SQLTransaction</a></code> object that represents that
- transaction. If the <i>mode</i> is read/write, the transaction must
- have an exclusive write lock over the entire database. If the
- <i>mode</i> is read-only, the transaction must have a shared read
- lock over the entire database. The user agent should wait for an
- appropriate lock to be available.</li>
-
- <li><p>If an error occurred in the opening of the transaction
- (e.g. if the user agent failed to obtain an appropriate lock after
- an appropriate delay), jump to the last step.</li>
-
- <li><p>If a <i>preflight operation</i> was defined for this
- instance of the transaction steps, run that. If it fails, then jump
- to the last step. (This is basically a hook for the <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
- method.)</li>
-
- <li><p><a href=#queue-a-task>Queue a task</a> to invoke the <i>transaction
- callback</i> with the aforementioned <code><a href=#sqltransaction>SQLTransaction</a></code>
- object as its only argument, and wait for that task to be
- run.</li>
-
- <li><p>If the callback couldn't be called (e.g. it was null), or if
- the callback was invoked and raised an exception, jump to the last
- step.</li>
-<!--
- <li><p>If the callback could be called and returned false, let
- <i>callback-canceled</i> be true. Otherwise, let it be
- false.</p></li>
--->
- <li><p>While there are any statements queued up in the transaction,
- perform the following steps for each queued up statement in the
- transaction, oldest first. Each statement has a statement,
- optionally a result set callback, and optionally an error
- callback.</p>
-
- <ol><li><p>If the statement is marked as bogus, jump to the "in case
- of error" steps below.</li>
-
- <li id=modifications-fail-if-read-only>
-
- <p>If the <i>mode</i> is read-only but the statement's main verb
- can modify the database, jump to the "in case of error" steps
- below.</p>
-
- <p class=note>Only the statement's main verb (e.g. <code title="">UPDATE</code>, <code title="">SELECT</code>, <code title="">DROP</code>) is considered here. Thus, a statement like
- "<code title="">UPDATE test SET id=0 WHERE 0=1</code>" would be
- treated as potentially modifying the database for the purposes
- of this step, even though it could never in fact have any
- side-effects.</p>
-
- </li>
-
- <li><p>Execute the statement in the context of the transaction.
- <a href=#refsSQL>[SQL]</a></p>
-
- <li><p>If the statement failed, jump to the "in case of error"
- steps below.</li>
-
- <li><p>Create a <code><a href=#sqlresultset>SQLResultSet</a></code> object that represents
- the result of the statement.</li>
-
- <li><p>If the statement has a result set callback, <a href=#queue-a-task>queue a
- task</a> to invoke it with the <code><a href=#sqltransaction>SQLTransaction</a></code>
- object as its first argument and the new
- <code><a href=#sqlresultset>SQLResultSet</a></code> object as its second argument, and wait
- for that task to be run.</li>
-
- <li><p>If the callback was invoked and raised an exception, jump
- to the last step in the overall steps.</li>
-
- <li><p>Move on to the next statement, if any, or onto the next
- overall step otherwise.</li>
-
- </ol><p>In case of error (or more specifically, if the above substeps
- say to jump to the "in case of error" steps), run the following
- substeps:</p>
-
- <ol><li><p>If the statement had an associated error callback, then
- <a href=#queue-a-task>queue a task</a> to invoke that error callback with the
- <code><a href=#sqltransaction>SQLTransaction</a></code> object and a newly constructed
- <code><a href=#sqlerror>SQLError</a></code> object that represents the error that
- caused these substeps to be run as the two arguments,
- respectively, and wait for the task to be run.</li>
-
- <li><p>If the error callback returns false, then move on to the
- next statement, if any, or onto the next overall step
- otherwise.</li>
-
- <li><p>Otherwise, the error callback did not return false, or
- there was no error callback. Jump to the last step in the overall
- steps.</li>
-
- </ol></li>
-
- <li><p>If a <i>postflight operation</i> was defined for this
- instance of the transaction steps, run that. If it fails, then jump
- to the last step. <!--The operation, if any, might depend
- <i>callback-canceled</i>.--> (This is basically a hook for the
- <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
- method.)</li>
-
- <li><p>Commit the transaction.</li>
-
- <li><p>If an error occurred in the committing of the transaction,
- jump to the last step.</li>
-
- <li><p><a href=#queue-a-task>Queue a task</a> to invoke the <i>success
- callback</i>.</li>
-
- <li><p>End these steps. The next step is only used when something
- goes wrong.</li>
-
- <li><p><a href=#queue-a-task>Queue a task</a> to invoke the <i>error
- callback</i> with a newly constructed <code><a href=#sqlerror>SQLError</a></code> object
- that represents the last error to have occurred in this
- transaction. Rollback the transaction. Any still-pending statements
- in the transaction are discarded.</li>
-
- </ol><h4 id=disk-space><span class=secno>5.11.3 </span>Disk space</h4>
-
- <p>User agents should limit the total amount of space allowed for
- storage areas and databases.</p>
-
- <p>User agents should guard against sites storing data in the
- storage areas or databases of subdomains, e.g. storing up to the
- limit in a1.example.com, a2.example.com, a3.example.com, etc,
- circumventing the main example.com storage limit.</p>
-
- <p>User agents may prompt the user when quotas are reached, allowing
- the user to grant a site more space. This enables sites to store
- many user-created documents on the user's computer, for
- instance.</p>
-
- <p>User agents should allow users to see how much space each domain
- is using.</p>
-
- <!--<p>If the storage area space limit is reached during a <code
- title="dom-Storage-setItem">setItem()</code> call, the method will
- raise an exception.</p>-->
-
- <p>A mostly arbitrary limit of five megabytes per domain is
- recommended. Implementation feedback is welcome and will be used to
- update this suggestion in future.</p>
-
-
- <h4 id=privacy><span class=secno>5.11.4 </span>Privacy</h4>
-
- <h5 id=user-tracking><span class=secno>5.11.4.1 </span>User tracking</h5>
-
- <p>A third-party advertiser (or any entity capable of getting
- content distributed to multiple sites) could use a unique identifier
- stored in its local storage area or in its client-side database to
- track a user across multiple sessions, building a profile of the
- user's interests to allow for highly targeted advertising. In
- conjunction with a site that is aware of the user's real identity
- (for example an e-commerce site that requires authenticated
- credentials), this could allow oppressive groups to target
- individuals with greater accuracy than in a world with purely
- anonymous Web usage.</p>
-
- <p>There are a number of techniques that can be used to mitigate the
- risk of user tracking:</p>
-
- <ul><li>
-
- <p>Blocking third-party storage: user agents may restrict access
- to the <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> and
- database objects to scripts originating at the domain of the
- top-level document of the <a href=#browsing-context>browsing context</a>, for
- instance denying access to the API for pages from other domains
- running in <code><a href=#the-iframe-element>iframe</a></code>s.</p>
-
- </li>
-
- <li>
-
- <p>Expiring stored data: user agents may automatically delete
- stored data after a period of time.</p>
-
- <p>For example, a user agent could treat third-party local
- storage areas as session-only storage, deleting the data once the
- user had closed all the <span>browsing contexts</span> that could
- access it.</p>
-
- <p>This can restrict the ability of a site to track a user, as the
- site would then only be able to track the user across multiple
- sessions when he authenticates with the site itself (e.g. by
- making a purchase or logging in to a service).</p>
-
- <p>However, this also puts the user's data at risk.</p>
-
- <!-- XXX should there be an explicit way for sites to state when
- data should expire? as in
- localStorage.expireData(365); ? -->
-
- </li>
-
- <li>
-
- <p>Treating persistent storage as cookies: user agents should
- present the persistent storage and database features to the user
- in a way that does not distinguish them from HTTP session
- cookies. <a href=#refsRFC2109>[RFC2109]</a> <a href=#refsRFC2965>[RFC2965]</a></p>
-
- <p>This might encourage users to view persistent storage with
- healthy suspicion.</p>
-
- </li>
-
- <li>
-
- <p>Site-specific white-listing of access to local storage areas
- and databases: user agents may allow sites to access session
- storage areas in an unrestricted manner, but require the user to
- authorize access to local storage areas and databases.</p>
-
- </li>
-
- <li>
-
- <p><a href=#origin-0>Origin</a>-tracking of persistent storage data: user
- agents may record the origins of sites that contained content from
- third-party origins that caused data to be stored.</p>
-
- <p>If this information is then used to present the view of data
- currently in persistent storage, it would allow the user to make
- informed decisions about which parts of the persistent storage to
- prune. Combined with a blacklist ("delete this data and prevent
- this domain from ever storing data again"), the user can restrict
- the use of persistent storage to sites that he trusts.</p>
-
- </li>
-
- <li>
-
- <p>Shared blacklists: user agents may allow users to share their
- persistent storage domain blacklists.</p>
-
- <p>This would allow communities to act together to protect their
- privacy.</p>
-
- </li>
-
- </ul><p>While these suggestions prevent trivial use of these APIs for
- user tracking, they do not block it altogether. Within a single
- domain, a site can continue to track the user during a session, and
- can then pass all this information to the third party along with any
- identifying information (names, credit card numbers, addresses)
- obtained by the site. If a third party cooperates with multiple
- sites to obtain such information, a profile can still be
- created.</p>
-
- <p>However, user tracking is to some extent possible even with no
- cooperation from the user agent whatsoever, for instance by using
- session identifiers in URLs, a technique already commonly used for
- innocuous purposes but easily repurposed for user tracking (even
- retroactively). This information can then be shared with other
- sites, using using visitors' IP addresses and other user-specific
- data (e.g. user-agent headers and configuration settings) to combine
- separate sessions into coherent user profiles.</p>
-
-
- <h5 id=cookie-resurrection><span class=secno>5.11.4.2 </span>Cookie resurrection</h5>
-
- <p>If the user interface for persistent storage presents data in the
- persistent storage features separately from data in HTTP session
- cookies, then users are likely to delete data in one and not the
- other. This would allow sites to use the two features as redundant
- backup for each other, defeating a user's attempts to protect his
- privacy.</p>
-
-
- <h4 id=security-4><span class=secno>5.11.5 </span>Security</h4>
-
- <h5 id=dns-spoofing-attacks><span class=secno>5.11.5.1 </span>DNS spoofing attacks</h5>
-
- <p>Because of the potential for DNS spoofing attacks, one cannot
- guarantee that a host claiming to be in a certain domain really is
- from that domain. To mitigate this, pages can use SSL. Pages using
- SSL can be sure that only pages using SSL that have certificates
- identifying them as being from the same domain can access their
- local storage areas and databases.</p>
-
-
- <h5 id=cross-directory-attacks><span class=secno>5.11.5.2 </span>Cross-directory attacks</h5>
-
- <p>Different authors sharing one host name, for example users
- hosting content on <code>geocities.com</code>, all share one
- persistent storage object and one set of databases. There is no
- feature to restrict the access by pathname. Authors on shared hosts
- are therefore recommended to avoid using the persistent storage
- features, as it would be trivial for other authors to read from and
- write to the same storage area or database.</p>
-
- <p class=note>Even if a path-restriction feature was made
- available, the usual DOM scripting security model would make it
- trivial to bypass this protection and access the data from any
- path.</p>
-
-
- <h5 id=implementation-risks><span class=secno>5.11.5.3 </span>Implementation risks</h5>
-
- <p>The two primary risks when implementing these persistent storage
- features are letting hostile sites read information from other
- domains, and letting hostile sites write information that is then
- read from other domains.</p>
-
- <p>Letting third-party sites read data that is not supposed to be
- read from their domain causes <em>information leakage</em>, For
- example, a user's shopping wishlist on one domain could be used by
- another domain for targeted advertising; or a user's
- work-in-progress confidential documents stored by a word-processing
- site could be examined by the site of a competing company.</p>
-
- <p>Letting third-party sites write data to the storage areas of
- other domains can result in <em>information spoofing</em>, which is
- equally dangerous. For example, a hostile site could add items to a
- user's wishlist; or a hostile site could set a user's session
- identifier to a known ID that the hostile site can then use to track
- the user's actions on the victim site.</p>
-
- <p>Thus, strictly following the <a href=#origin-0>origin</a> model described
- in this specification is important for user security.</p>
-
-
- <h5 id=sql-and-user-agents><span class=secno>5.11.5.4 </span>SQL and user agents</h5>
-
- <p>User agent implementors are strongly encouraged to audit all
- their supported SQL statements for security implications. For
- example, <code title="">LOAD DATA INFILE</code> is likely to pose
- security risks and there is little reason to support it.</p>
-
- <p>In general, it is recommended that user agents not support
- features that control how databases are stored on disk. For example,
- there is little reason to allow Web authors to control the character
- encoding used in the disk representation of the data, as all data in
- ECMAScript is implicitly UTF-16.</p>
-
-
- <h5 id=sql-injection><span class=secno>5.11.5.5 </span>SQL injection</h5>
-
- <p>Authors are strongly recommended to make use of the <code title="">?</code> placeholder feature of the <code title=dom-sqltransaction-executeSql><a href=#dom-sqltransaction-executesql>executeSql()</a></code> method,
- and to never construct SQL statements on the fly.</p>
-
-
-
-
- <h3 id=links><span class=secno>5.12 </span>Links</h3>
-
-
- <h4 id=hyperlink-elements><span class=secno>5.12.1 </span>Hyperlink elements</h4>
-
<p>The <code><a href=#the-a-element>a</a></code>, <code><a href=#the-area-element>area</a></code>, and <code><a href=#the-link-element>link</a></code>
elements can, in certain situations described in the definitions of
those elements, represent <dfn id=hyperlink title=hyperlink>hyperlinks</dfn>.</p>
@@ -46261,7 +45016,7 @@
<div class=impl>
- <h4 id=following-hyperlinks><span class=secno>5.12.2 </span><dfn>Following hyperlinks</dfn></h4>
+ <h4 id=following-hyperlinks><span class=secno>5.11.2 </span><dfn>Following hyperlinks</dfn></h4>
<p>When a user <em>follows a hyperlink</em>, the user agent must
<a href=#resolve-a-url title="resolve a url">resolve</a> the <a href=#url>URL</a>
@@ -46319,7 +45074,7 @@
<a href=#source-browsing-context>source browsing context</a>.</p>
- <h5 id=hyperlink-auditing><span class=secno>5.12.2.1 </span><dfn>Hyperlink auditing</dfn></h5>
+ <h5 id=hyperlink-auditing><span class=secno>5.11.2.1 </span><dfn>Hyperlink auditing</dfn></h5>
<p>If an <code><a href=#the-a-element>a</a></code> or <code><a href=#the-area-element>area</a></code> hyperlink element has a
<code title=attr-hyperlink-ping><a href=#ping>ping</a></code> attribute, and the
@@ -46449,7 +45204,7 @@
- <h4 id=linkTypes><span class=secno>5.12.3 </span>Link types</h4>
+ <h4 id=linkTypes><span class=secno>5.11.3 </span>Link types</h4>
<p>The following table summarizes the link types that are defined by
this specification. This table is non-normative; the actual
@@ -46627,7 +45382,7 @@
-->
- <h5 id=link-type-alternate><span class=secno>5.12.3.1 </span>Link type "<dfn title=rel-alternate><code>alternate</code></dfn>"</h5>
+ <h5 id=link-type-alternate><span class=secno>5.11.3.1 </span>Link type "<dfn title=rel-alternate><code>alternate</code></dfn>"</h5>
<p>The <code title=rel-alternate><a href=#link-type-alternate>alternate</a></code> keyword may be
used with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -46692,7 +45447,7 @@
alternative representations of each other.</p>
- <h5 id=link-type-archives><span class=secno>5.12.3.2 </span>Link type "<dfn title=rel-archives><code>archives</code></dfn>"</h5>
+ <h5 id=link-type-archives><span class=secno>5.11.3.2 </span>Link type "<dfn title=rel-archives><code>archives</code></dfn>"</h5>
<p>The <code title=rel-archives><a href=#link-type-archives>archives</a></code> keyword may be
used with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -46714,7 +45469,7 @@
</div>
- <h5 id=link-type-author><span class=secno>5.12.3.3 </span>Link type "<dfn title=rel-author><code>author</code></dfn>"</h5>
+ <h5 id=link-type-author><span class=secno>5.11.3.3 </span>Link type "<dfn title=rel-author><code>author</code></dfn>"</h5>
<p>The <code title=rel-author><a href=#link-type-author>author</a></code> keyword may be
used with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -46743,7 +45498,7 @@
</div>
- <h5 id=link-type-bookmark><span class=secno>5.12.3.4 </span>Link type "<dfn title=rel-bookmark><code>bookmark</code></dfn>"</h5>
+ <h5 id=link-type-bookmark><span class=secno>5.11.3.4 </span>Link type "<dfn title=rel-bookmark><code>bookmark</code></dfn>"</h5>
<p>The <code title=rel-bookmark><a href=#link-type-bookmark>bookmark</a></code> keyword may be
used with <code><a href=#the-a-element>a</a></code> and <code><a href=#the-area-element>area</a></code> elements.</p>
@@ -46809,7 +45564,7 @@
-->
- <h5 id=link-type-external><span class=secno>5.12.3.5 </span>Link type "<dfn title=rel-external><code>external</code></dfn>"</h5>
+ <h5 id=link-type-external><span class=secno>5.11.3.5 </span>Link type "<dfn title=rel-external><code>external</code></dfn>"</h5>
<p>The <code title=rel-external><a href=#link-type-external>external</a></code> keyword may be
used with <code><a href=#the-a-element>a</a></code> and <code><a href=#the-area-element>area</a></code> elements.</p>
@@ -46819,7 +45574,7 @@
that the current document forms a part of.</p>
- <h5 id=link-type-feed><span class=secno>5.12.3.6 </span>Link type "<dfn title=rel-feed><code>feed</code></dfn>"</h5>
+ <h5 id=link-type-feed><span class=secno>5.11.3.6 </span>Link type "<dfn title=rel-feed><code>feed</code></dfn>"</h5>
<p>The <code title=rel-feed><a href=#link-type-feed>feed</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -46861,7 +45616,7 @@
</div>
- <h5 id=link-type-help><span class=secno>5.12.3.7 </span>Link type "<dfn title=rel-help><code>help</code></dfn>"</h5>
+ <h5 id=link-type-help><span class=secno>5.11.3.7 </span>Link type "<dfn title=rel-help><code>help</code></dfn>"</h5>
<p>The <code title=rel-help><a href=#link-type-help>help</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -46886,7 +45641,7 @@
document provides help for the page as a whole.</p>
- <h5 id=rel-icon><span class=secno>5.12.3.8 </span>Link type "<dfn title=rel-icon><code>icon</code></dfn>"</h5>
+ <h5 id=rel-icon><span class=secno>5.11.3.8 </span>Link type "<dfn title=rel-icon><code>icon</code></dfn>"</h5>
<p>The <code title=rel-icon><a href=#rel-icon>icon</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code> elements, for which it creates an <a href=#external-resource-link title="external resource link">external resource link</a>.</p>
@@ -47012,7 +45767,7 @@
</div>
- <h5 id=link-type-license><span class=secno>5.12.3.9 </span>Link type "<dfn title=rel-license><code>license</code></dfn>"</h5>
+ <h5 id=link-type-license><span class=secno>5.11.3.9 </span>Link type "<dfn title=rel-license><code>license</code></dfn>"</h5>
<p>The <code title=rel-license><a href=#link-type-license>license</a></code> keyword may be used
with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47031,7 +45786,7 @@
</div>
- <h5 id=link-type-nofollow><span class=secno>5.12.3.10 </span>Link type "<dfn title=rel-nofollow><code>nofollow</code></dfn>"</h5>
+ <h5 id=link-type-nofollow><span class=secno>5.11.3.10 </span>Link type "<dfn title=rel-nofollow><code>nofollow</code></dfn>"</h5>
<p>The <code title=rel-nofollow><a href=#link-type-nofollow>nofollow</a></code> keyword may be
used with <code><a href=#the-a-element>a</a></code> and <code><a href=#the-area-element>area</a></code> elements.</p>
@@ -47043,7 +45798,7 @@
affiliated with the two pages.</p>
- <h5 id=link-type-noreferrer><span class=secno>5.12.3.11 </span>Link type "<dfn title=rel-noreferrer><code>noreferrer</code></dfn>"</h5>
+ <h5 id=link-type-noreferrer><span class=secno>5.11.3.11 </span>Link type "<dfn title=rel-noreferrer><code>noreferrer</code></dfn>"</h5>
<p>The <code title=rel-noreferrer><a href=#link-type-noreferrer>noreferrer</a></code> keyword may be
used with <code><a href=#the-a-element>a</a></code> and <code><a href=#the-area-element>area</a></code> elements.</p>
@@ -47064,7 +45819,7 @@
</div>
- <h5 id=link-type-pingback><span class=secno>5.12.3.12 </span>Link type "<dfn title=rel-pingback><code>pingback</code></dfn>"</h5>
+ <h5 id=link-type-pingback><span class=secno>5.11.3.12 </span>Link type "<dfn title=rel-pingback><code>pingback</code></dfn>"</h5>
<p>The <code title=rel-pingback><a href=#link-type-pingback>pingback</a></code> keyword may be
used with <code><a href=#the-link-element>link</a></code> elements, for which it creates an <a href=#external-resource-link title="external resource link">external resource link</a>.</p>
@@ -47073,7 +45828,7 @@
specification. <a href=#refsPINGBACK>[PINGBACK]</a></p>
- <h5 id=link-type-prefetch><span class=secno>5.12.3.13 </span>Link type "<dfn title=rel-prefetch><code>prefetch</code></dfn>"</h5>
+ <h5 id=link-type-prefetch><span class=secno>5.11.3.13 </span>Link type "<dfn title=rel-prefetch><code>prefetch</code></dfn>"</h5>
<p>The <code title=rel-prefetch><a href=#link-type-prefetch>prefetch</a></code> keyword may be
used with <code><a href=#the-link-element>link</a></code> elements, for which it creates an <a href=#external-resource-link title="external resource link">external resource link</a>.</p>
@@ -47086,7 +45841,7 @@
<p>There is no default type for resources given by the <code title=rel-prefetch><a href=#link-type-prefetch>prefetch</a></code> keyword.</p>
- <h5 id=link-type-search><span class=secno>5.12.3.14 </span>Link type "<dfn title=rel-search><code>search</code></dfn>"</h5>
+ <h5 id=link-type-search><span class=secno>5.11.3.14 </span>Link type "<dfn title=rel-search><code>search</code></dfn>"</h5>
<p>The <code title=rel-search><a href=#link-type-search>search</a></code> keyword may be used
with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47103,7 +45858,7 @@
-->
- <h5 id=link-type-stylesheet><span class=secno>5.12.3.15 </span>Link type "<dfn title=rel-stylesheet><code>stylesheet</code></dfn>"</h5>
+ <h5 id=link-type-stylesheet><span class=secno>5.11.3.15 </span>Link type "<dfn title=rel-stylesheet><code>stylesheet</code></dfn>"</h5>
<p>The <code title=rel-stylesheet><a href=#link-type-stylesheet>stylesheet</a></code> keyword may be
used with <code><a href=#the-link-element>link</a></code> elements, for which it creates an <a href=#external-resource-link title="external resource link">external resource link</a> that
@@ -47130,7 +45885,7 @@
</div>
- <h5 id=link-type-sidebar><span class=secno>5.12.3.16 </span>Link type "<dfn title=rel-sidebar><code>sidebar</code></dfn>"</h5>
+ <h5 id=link-type-sidebar><span class=secno>5.11.3.16 </span>Link type "<dfn title=rel-sidebar><code>sidebar</code></dfn>"</h5>
<p>The <code title=rel-sidebar><a href=#link-type-sidebar>sidebar</a></code> keyword may be used
with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47145,7 +45900,7 @@
<code title=rel-sidebar><a href=#link-type-sidebar>sidebar</a></code> keyword specified is a <dfn id=rel-sidebar-hyperlink title=rel-sidebar-hyperlink>sidebar hyperlink</dfn>.</p>
- <h5 id=link-type-tag><span class=secno>5.12.3.17 </span>Link type "<dfn title=rel-tag><code>tag</code></dfn>"</h5>
+ <h5 id=link-type-tag><span class=secno>5.11.3.17 </span>Link type "<dfn title=rel-tag><code>tag</code></dfn>"</h5>
<p>The <code title=rel-tag><a href=#link-type-tag>tag</a></code> keyword may be used
with <code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47161,7 +45916,7 @@
the popular tag across a set of pages.</p>
- <h5 id=hierarchical-link-types><span class=secno>5.12.3.18 </span>Hierarchical link types</h5>
+ <h5 id=hierarchical-link-types><span class=secno>5.11.3.18 </span>Hierarchical link types</h5>
<p>Some documents form part of a hierarchical structure of
documents.</p>
@@ -47174,7 +45929,7 @@
<p>A document may be part of multiple hierarchies.</p>
- <h6 id=link-type-index><span class=secno>5.12.3.18.1 </span>Link type "<dfn title=rel-index><code>index</code></dfn>"</h6>
+ <h6 id=link-type-index><span class=secno>5.11.3.18.1 </span>Link type "<dfn title=rel-index><code>index</code></dfn>"</h6>
<p>The <code title=rel-index><a href=#link-type-index>index</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47194,7 +45949,7 @@
</div>
- <h6 id=link-type-up><span class=secno>5.12.3.18.2 </span>Link type "<dfn title=rel-up><code>up</code></dfn>"</h6>
+ <h6 id=link-type-up><span class=secno>5.11.3.18.2 </span>Link type "<dfn title=rel-up><code>up</code></dfn>"</h6>
<p>The <code title=rel-up><a href=#link-type-up>up</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47261,7 +46016,7 @@
interface hides duplicates).</p>
- <h5 id=sequential-link-types><span class=secno>5.12.3.19 </span>Sequential link types</h5>
+ <h5 id=sequential-link-types><span class=secno>5.11.3.19 </span>Sequential link types</h5>
<p>Some documents form part of a sequence of documents.</p>
@@ -47273,7 +46028,7 @@
<p>A document may be part of multiple sequences.</p>
- <h6 id=link-type-first><span class=secno>5.12.3.19.1 </span>Link type "<dfn title=rel-first><code>first</code></dfn>"</h6>
+ <h6 id=link-type-first><span class=secno>5.11.3.19.1 </span>Link type "<dfn title=rel-first><code>first</code></dfn>"</h6>
<p>The <code title=rel-first><a href=#link-type-first>first</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47292,7 +46047,7 @@
</div>
- <h6 id=link-type-last><span class=secno>5.12.3.19.2 </span>Link type "<dfn title=rel-last><code>last</code></dfn>"</h6>
+ <h6 id=link-type-last><span class=secno>5.11.3.19.2 </span>Link type "<dfn title=rel-last><code>last</code></dfn>"</h6>
<p>The <code title=rel-last><a href=#link-type-last>last</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47311,7 +46066,7 @@
</div>
- <h6 id=link-type-next><span class=secno>5.12.3.19.3 </span>Link type "<dfn title=rel-next><code>next</code></dfn>"</h6>
+ <h6 id=link-type-next><span class=secno>5.11.3.19.3 </span>Link type "<dfn title=rel-next><code>next</code></dfn>"</h6>
<p>The <code title=rel-next><a href=#link-type-next>next</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47322,7 +46077,7 @@
document that is the next logical document in the sequence.</p>
- <h6 id=link-type-prev><span class=secno>5.12.3.19.4 </span>Link type "<dfn title=rel-prev><code>prev</code></dfn>"</h6>
+ <h6 id=link-type-prev><span class=secno>5.11.3.19.4 </span>Link type "<dfn title=rel-prev><code>prev</code></dfn>"</h6>
<p>The <code title=rel-prev><a href=#link-type-prev>prev</a></code> keyword may be used with
<code><a href=#the-link-element>link</a></code>, <code><a href=#the-a-element>a</a></code>, and <code><a href=#the-area-element>area</a></code>
@@ -47341,7 +46096,7 @@
</div>
- <h5 id=other-link-types><span class=secno>5.12.3.20 </span>Other link types</h5>
+ <h5 id=other-link-types><span class=secno>5.11.3.20 </span>Other link types</h5>
<p>Other than the types defined above, only types defined as
extensions in the <a href=http://wiki.whatwg.org/wiki/RelExtensions>WHATWG Wiki
@@ -49102,7 +47857,7 @@
</div>
- <h4 id=introduction-5><span class=secno>6.9.1 </span>Introduction</h4>
+ <h4 id=introduction-3><span class=secno>6.9.1 </span>Introduction</h4>
<p><em>This section is non-normative.</em></p>
@@ -50033,7 +48788,7 @@
<p class=XXX>There has got to be a better way of doing this, surely.</p>
- <h4 id=introduction-6><span class=secno>6.10.1 </span>Introduction</h4>
+ <h4 id=introduction-4><span class=secno>6.10.1 </span>Introduction</h4>
<p class=XXX>...</p>
@@ -50879,8 +49634,9 @@
<h3 id=event-definitions><span class=secno>7.1 </span>Event definitions</h3>
- <p>Messages in <a href=#server-sent-events>server-sent events</a>, <a href=#network>Web
- sockets</a>, <a href=#crossDocumentMessages>cross-document messaging</a>, and
+ <!-- XXX cross-references for SSE and WS need fixing now that this is cross-spec -->
+ <p>Messages in <span>server-sent events</span>, <span>Web
+ sockets</span>, <a href=#crossDocumentMessages>cross-document messaging</a>, and
<a href=#channel-messaging>channel messaging</a> use the <dfn id=event-message title=event-message><code>message</code></dfn> event.</p>
<p>The following interface is defined for this event:</p>
@@ -50907,8 +49663,8 @@
<dd>
- <p>Returns the origin of the message, for <a href=#server-sent-events>server-sent
- events</a> and <a href=#crossDocumentMessages>cross-document messaging</a>.</p>
+ <p>Returns the origin of the message, for <span>server-sent
+ events</span> and <a href=#crossDocumentMessages>cross-document messaging</a>.</p>
</dd>
@@ -50916,8 +49672,8 @@
<dd>
- <p>Returns the last event ID, for <a href=#server-sent-events>server-sent
- events</a>.</p>
+ <p>Returns the last event ID, for <span>server-sent
+ events</span>.</p>
</dd>
@@ -50951,14 +49707,14 @@
attribute represents the message being sent.</p>
<p>The <dfn id=dom-messageevent-origin title=dom-MessageEvent-origin><code>origin</code></dfn> attribute
- represents, in <a href=#server-sent-events>server-sent events</a> and
+ represents, in <span>server-sent events</span> and
<a href=#crossDocumentMessages>cross-document messaging</a>, the <a href=#origin-0>origin</a> of
the document that sent the message (typically the scheme, hostname,
and port of the document, but not its path or fragment
identifier).</p>
<p>The <dfn id=dom-messageevent-lasteventid title=dom-MessageEvent-lastEventId><code>lastEventId</code></dfn>
- attribute represents, in <a href=#server-sent-events>server-sent events</a>, the
+ attribute represents, in <span>server-sent events</span>, the
<span>last event ID string</span> of the event source.</p>
<p>The <dfn id=dom-messageevent-source title=dom-MessageEvent-source><code>source</code></dfn> attribute
@@ -50983,1485 +49739,13 @@
- <h3 id=server-sent-events><span class=secno>7.2 </span><dfn>Server-sent events</dfn></h3>
- <!-- eventsource -->
- <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>
- <p class=XXX>An introduction to the client-side and
- server-side of using the direct connection APIs.</p>
- <!--BOILERPLATE-->
+ <h3 id=crossDocumentMessages><span class=secno>7.2 </span><dfn>Cross-document messaging</dfn></h3>
- <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><code><a href=#eventsource>EventSource</a></code> objects must also implement the
- <code>EventTarget</code> interface. <a href=#refsDOM3EVENTS>[DOM3EVENTS]</a></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>
-
- <li><p>If the previous step failed, then throw a
- <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception.</li>
-
- <li><p>Return a new <code><a href=#eventsource>EventSource</a></code> object, and continue
- these steps in the background (without blocking scripts).</li>
-
- <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><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>
-
- <p>The <dfn id=dom-eventsource-readystate title=dom-EventSource-readyState><code>readyState</code></dfn>
- attribute represents the state of the connection. It can have the
- following values:</p>
-
- <dl><dt><dfn id=dom-eventsource-connecting title=dom-EventSource-CONNECTING><code>CONNECTING</code></dfn> (numeric value 0)</dt>
-
- <dd>The connection has not yet been established, or it was closed
- and the user agent is reconnecting.</dd>
-
- <dt><dfn id=dom-eventsource-open title=dom-EventSource-OPEN><code>OPEN</code></dfn> (numeric value 1)</dt>
-
- <dd>The user agent has an open connection and is dispatching events
- as it receives them.</dd>
-
- <dt><dfn id=dom-eventsource-closed title=dom-EventSource-CLOSED><code>CLOSED</code></dfn> (numeric value 2)</dt>
-
- <dd>The connection is not open, and the user agent is not trying to
- reconnect. Either there was a fatal error or the <code title=dom-EventSource-disconnect><a href=#dom-eventsource-disconnect>disconnect()</a></code> method was
- invoked.</dd>
-
- </dl><p>When the object is created its <code title=dom-EventSource-readyState><a href=#dom-eventsource-readystate>readyState</a></code> must be set to
- <code title=dom-EventSource-CONNECTING><a href=#dom-eventsource-connecting>CONNECTING</a></code> (0). The
- rules given below for handling the connection define when the value
- changes.</p>
-
- <p>The <dfn id=dom-eventsource-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>A <dfn id=concept-event-stream-last-event-id title=concept-event-stream-last-event-id>last event
- ID string</dfn>. This must initially be the empty string.</li>
-
- </ul><p>These values are not currently exposed on the interface.</p>
-
-
- <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>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>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 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 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 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 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 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 <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
- server-specified URL, but if the user agent needs to again request
- the resource at a later point, it must return to the previously
- specified URL for this 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 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>
-
- <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. <strong>Only if the user agent <a href=#reset-the-connection title="reset the connection">resets the connection</a> does the
- connection get opened anew!</strong></p>
-
- <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. <strong>Once the user agent has <a href=#fail-the-connection title="fail the
- connection">failed the connection</a>, it does <em>not</em>
- attempt to reconnect!</strong></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>
-
- <p>The event stream format is as described by the <code title="">stream</code> production of the following ABNF, the
- character set for which is Unicode. <a href=#refsABNF>[ABNF]</a></p> <!-- XXX
- ftp://ftp.rfc-editor.org/in-notes/std/std68.txt -->
-
- <pre>stream = [ bom ] *event
-event = *( comment / field ) end-of-line
-comment = colon *any-char end-of-line
-field = 1*name-char [ colon [ space ] *any-char ] end-of-line
-end-of-line = ( cr lf / cr / lf / eof )
-eof = < matches repeatedly at the end of the stream >
-
-; characters
-lf = %x000A ; U+000A LINE FEED
-cr = %x000D ; U+000D CARRIAGE RETURN
-space = %x0020 ; U+0020 SPACE
-colon = %x003A ; U+003A COLON
-bom = %xFEFF ; U+FEFF BYTE ORDER MARK
-name-char = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
- ; a Unicode character other than U+000A LINE FEED, U+000D CARRIAGE RETURN, or U+003A COLON
-any-char = %x0000-0009 / %x000B-000C / %x000E-10FFFF
- ; a Unicode character other than U+000D CARRIAGE RETURN or U+003A COLON</pre>
-
- <p>Event streams in this format must always be encoded as
- UTF-8.</p>
-
- <p>Lines must be separated by either a U+000D CARRIAGE RETURN U+000A
- 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.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>
-
- <p>One leading U+FEFF BYTE ORDER MARK character must be ignored if
- any are present.</p>
-
- <p>The stream must then be parsed by reading everything line by
- line, with a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF)
- character pair, a single U+000A LINE FEED (LF) character, a single
- U+000D CARRIAGE RETURN (CR) character, and the end of the file being
- the four ways in which a line can end.</p>
-
- <p>When a stream is parsed, a <var title="">data</var> buffer and an
- <var title="">event name</var> buffer must be associated with
- it. They must be initialized to the empty string</p>
-
- <p>Lines must be processed, in the order they are received, as
- follows:</p>
-
- <dl class=switch><dt>If the line is empty (a blank line)</dt>
-
- <dd><p><a href=#dispatchMessage>Dispatch the event</a>, as
- defined below.</dd>
-
-
- <dt>If the line starts with a U+003A COLON character (':')</dt>
-
- <dd><p>Ignore the line.</dd>
-
-
- <dt>If the line contains a U+003A COLON character (':') character</dt>
-
- <dd>
-
- <p>Collect the characters on the line before the first U+003A
- COLON character (':'), and let <var title="">field</var> be that
- string.</p>
-
- <p>Collect the characters on the line after the first U+003A COLON
- character (':'), and let <var title="">value</var> be that
- string. If <var title="">value</var> starts with a single U+0020
- SPACE character, remove it from <var title="">value</var>.</p>
-
- <p><a href=#processField>Process the field</a> using the steps
- described below, using <var title="">field</var> as the field name
- and <var title="">value</var> as the field value.</p>
-
- </dd>
-
-
- <dt>Otherwise, the string is not empty but does not contain a U+003A COLON character (':') character</dt>
-
- <dd>
-
- <p><a href=#processField>Process the field</a> using the steps
- described below, using the whole line as the field name, and
- the empty string as the field value.</p>
-
- </dd>
-
- </dl><p>Once the end of the file is reached, the user agent must <a href=#dispatchMessage>dispatch the event</a> one final time, as
- defined below.</p>
-
-
- <p id=processField>The steps to <dfn title="">process the
- field</dfn> given a field name and a field value depend on the field
- name, as given in the following list. Field names must be compared
- literally, with no case folding performed.</p>
-
- <dl class=switch><dt>If the field name is "event"</dt>
-
- <dd><p>Set the <var title="">event name</var> buffer the to field
- value.</dd>
-
-
- <dt>If the field name is "data"</dt>
-
- <dd><p>If the <var title="">data</var> buffer is not the empty
- string, then append a single U+000A LINE FEED character to the <var title="">data</var> buffer. Append the field value to the <var title="">data</var> buffer.</dd>
-
-
- <dt>If the field name is "id"</dt>
-
- <dd><p>Set the event stream's <a href=#concept-event-stream-last-event-id title=concept-event-stream-last-event-id>last event ID</a> to
- the field value.</dd>
-
-
- <dt>If the field name is "retry"</dt>
-
- <dd><p>If the field value consists of only characters in the range
- U+0030 DIGIT ZERO ('0') U+0039 DIGIT NINE ('9'), then interpret the
- field value as an integer in base ten, and set the event stream's
- <a href=#concept-event-stream-reconnection-time title=concept-event-stream-reconnection-time>reconnection
- time</a> to that integer. Otherwise, ignore the field.</dd>
-
-<!-- v2 feature request from John Fallows - http://www.w3.org/mid/c5b3a7130810271238h11e40a4fybfcd5983ed5dc08d@mail.gmail.com
-
- <dt>If the field name is "reconnect"</dt>
-
- <dd><p>If the field value is the empty string, then: <a
- href="#dispatchMessage">dispatch the event</a> as defined below,
- and then drop the connection and immediately reconnect as if the
- <span title="concept-event-stream-reconnection-time">reconnection
- time</span> was zero for this one time.</p></dd>
-
- -->
-
- <dt>Otherwise</dt>
-
- <dd><p>The field is ignored.</dd>
-
- </dl><p id=dispatchMessage>When the user agent is required to <dfn title="">dispatch the event</dfn>, then the user agent must act as
- follows:
-
- <ol><li><p>If the <var title="">data</var> buffer is an empty string,
- set the <var title="">data</var> buffer and the <var title="">event
- name</var> buffer to the empty string and abort these
- steps.</li>
-
- <li><p>If the <var title="">event name</var> buffer is not the
- empty string but is also not a valid <a href=http://www.w3.org/TR/REC-xml-names/#NT-NCName>NCName</a>,
- set the <var title="">data</var> buffer and the <var title="">event
- name</var> buffer to the empty string and abort these
- steps.</li>
-
- <li><p>Otherwise, create an event that uses the
- <code><a href=#messageevent>MessageEvent</a></code> interface, with the event name <code title=event-message><a href=#event-message>message</a></code>, which does not bubble, is
- cancelable, and has no default action. The <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute must be set to
- the value of the <var title="">data</var> buffer, the <code title=dom-MessageEvent-origin><a href=#dom-messageevent-origin>origin</a></code> attribute must be set
- to the <a href=#unicode-serialization-of-an-origin title="Unicode serialization of an origin">Unicode
- serialization</a> of the <a href=#origin-0>origin</a> of the event
- stream's URL, and the <code title=dom-MessageEvent-lastEventId><a href=#dom-messageevent-lasteventid>lastEventId</a></code> attribute
- must be set to the <span>last event ID string</span> of the event
- source.</li>
-
- <li><p>If the <var title="">event name</var> buffer has a value
- other than the empty string, change the type of the newly created
- event to equal the value of the <var title="">event name</var>
- buffer.</li>
-
- <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=#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
- string</span>, then the event's <code title=dom-MessageEvent-lastEventId><a href=#dom-messageevent-lasteventid>lastEventId</a></code> field will
- be set to the value of whatever the last seen "id" field was.</p>
-
-
- <div class=example>
-
- <p>The following event stream, once followed by a blank line:</p>
- <pre>data: YHOO
-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=#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>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>
-
- <div class=example>
-
- <p>The following stream contains four blocks. The first block has
- just a comment, and will fire nothing. The second block has two
- fields with names "data" and "id" respectively; an event will be
- fired for this block, with the data "first event", and will then
- set the last event ID to "1" so that if the connection died between
- this block and the next, the server would be sent a <code title="">Last-Event-ID</code> header with the value "1". The third
- block fires an event with data "second event", and also has an "id"
- field, this time with no value, which resets the last event ID to
- the empty string (meaning no <code title="">Last-Event-ID</code>
- header will now be sent in the event of a reconnection being
- attempted). Finally the last block just fires an event with the
- data "third event". Note that the last block doesn't have to end
- with a blank line, the end of the stream is enough to trigger the
- dispatch of the last event.</p>
-
- <pre>: test stream
-
-data: first event
-id: 1
-
-data: second event
-id
-
-data: third event</pre>
- </div>
-
- <div class=example>
-
- <p>The following stream fires just one event:</p>
-
- <pre>data
-
-data
-data
-
-data:</pre>
-
- <p>The first and last blocks do nothing, since they do not contain
- any actual data (the <var title="">data</var> buffer remains at the
- empty string, and so nothing gets dispatched). The middle block
- fires an event with the data set to a single newline character.</p>
- </div>
-
- <div class=example>
-
- <p>The following stream fires two identical events:</p>
-
- <pre>data:test
-
-data: test</pre>
-
- <p>This is because the space after the colon is ignored if
- present.</p>
-
- </div>
-
-
- <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
- servers, authors can include a comment line (one starting with a ':'
- character) every 15 seconds or so.</p>
-
- <p>Authors wishing to relate event source connections to each other
- or to specific documents previously served might find that relying
- on IP addresses doesn't work, as individual clients can have
- multiple IP addresses (due to having multiple proxy servers) and
- 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>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=#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=#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>
-
- <p><em>This section is non-normative.</em></p>
-
- <p>To enable Web applications to maintain bidirectional
- communications with server-side processes, this specification
- introduces the <code><a href=#websocket>WebSocket</a></code> interface.</p>
-
- <p class=note>This interface does not allow for raw access to the
- underlying network. For example, this interface could not be used to
- implement an IRC client without proxying messages through a custom
- server.</p>
-
- <p class=XXX>An introduction to the client-side and
- server-side of using the direct connection APIs.</p>
-
- <!--BOILERPLATE-->
-
- <h4 id=the-websocket-interface><span class=secno>7.3.2 </span>The <code><a href=#websocket>WebSocket</a></code> interface</h4>
-
- <pre class=idl>[<a href=#dom-websocket title=dom-WebSocket>Constructor</a>(in DOMString url)]
-interface <dfn id=websocket>WebSocket</dfn> {
- readonly attribute DOMString <a href=#dom-websocket-url title=dom-WebSocket-URL>URL</a>;
-
- // ready state
- const unsigned short <a href=#dom-websocket-connecting title=dom-WebSocket-CONNECTING>CONNECTING</a> = 0;
- const unsigned short <a href=#dom-websocket-open title=dom-WebSocket-OPEN>OPEN</a> = 1;
- const unsigned short <a href=#dom-websocket-closed title=dom-WebSocket-CLOSED>CLOSED</a> = 2;
- readonly attribute long <a href=#dom-websocket-readystate title=dom-WebSocket-readyState>readyState</a>;
-
- // 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-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>
-
- <p><code><a href=#websocket>WebSocket</a></code> objects must also implement the
- <code>EventTarget</code> interface. <a href=#refsDOM3EVENTS>[DOM3EVENTS]</a>
-
- <p>The <dfn id=dom-websocket title=dom-WebSocket><code>WebSocket(<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>WebSocket()</code> constructor is
- invoked, the UA must run these steps:</p>
-
- <ol><li><p><a href=#parse-a-url title="parse a url">Parse</a> the <var title="">url</var> argument.</li>
-
- <li><p>If the previous step failed, or if <var title="">url</var>
- does not have a <a href=#url-scheme title=url-scheme><scheme></a>
- component whose value is either "<code title="">ws</code>" or
- "<code title="">wss</code>", when compared in an <a href=#ascii-case-insensitive>ASCII
- case-insensitive</a> manner, then throw a
- <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception.</li>
-
- <li><p>Return a new <code><a href=#websocket>WebSocket</a></code> object, and continue
- these steps in the background (without blocking scripts).</li>
-
- <li><p>Let <var title="">origin</var> be the <a href=#ascii-serialization-of-an-origin title="ASCII
- serialization of an origin">ASCII serialization</a> of the
- <a href=#origin-0>origin</a> of the script that invoked the <code title=dom-WebSocket><a href=#dom-websocket>WebSocket()</a></code> constructor,
- <a href=#converted-to-lowercase>converted to lowercase</a>.</li>
-
- <li><p>If the <a href=#url-scheme title=url-scheme><scheme></a>
- component of <var title="">url</var> is "<code title="">ws</code>",
- set <var title="">secure</var> to false; otherwise, the <a href=#url-scheme title=url-scheme><scheme></a> component is "<code title="">wss</code>", set <var title="">secure</var> to
- true.</li>
-
- <li><p>Let <var title="">host</var> be the value of the <a href=#url-host title=url-host><host></a> component of <var title="">url</var>, <a href=#converted-to-lowercase>converted to lowercase</a>.</li>
-
- <li><p>If <var title="">url</var> has a <a href=#url-port title=url-port><port></a> component, then let <var title="">port</var> be that component's value; otherwise, there is
- no explicit <var title="">port</var>.</li>
-
- <li><p>Let <var title="">resource name</var> be the value of the
- <a href=#url-path title=url-path><path></a> component (which might
- be empty) of <var title="">url</var>.</li>
-
- <li><p>If <var title="">resource name</var> is the empty string,
- set it to a single character U+002F SOLIDUS (/).</li>
-
- <li><p>If <var title="">url</var> has a <a href=#url-query title=url-query><query></a> component, then append a
- single U+003F QUESTION MARK (?) character to <var title="">resource
- name</var>, followed by the value of the <a href=#url-query title=url-query><query></a> component.</li>
-
- <li><p><a href=#establish-a-web-socket-connection>Establish a Web Socket connection</a> to a host
- <var title="">host</var>, on port <var title="">port</var> (if one
- was specified), from <var title="">origin</var>, with the flag <var title="">secure</var>, and with <var title="">resource name</var>
- as the resource name.</li>
-
- </ol><hr><p>The <dfn id=dom-websocket-url title=dom-WebSocket-URL><code>URL</code></dfn>
- attribute must return the value that was passed to the
- constructor.</p>
-
- <p>The <dfn id=dom-websocket-readystate title=dom-WebSocket-readyState><code>readyState</code></dfn>
- attribute represents the state of the connection. It can have the
- following values:</p>
-
- <dl><dt><dfn id=dom-websocket-connecting title=dom-WebSocket-CONNECTING><code>CONNECTING</code></dfn> (numeric value 0)</dt>
-
- <dd>The connection has not yet been established.</dd>
-
- <dt><dfn id=dom-websocket-open title=dom-WebSocket-OPEN><code>OPEN</code></dfn> (numeric value 1)</dt>
-
- <dd>The <a href=#web-socket-connection-is-established>Web Socket connection is established</a> and communication is possible.</dd>
-
- <dt><dfn id=dom-websocket-closed title=dom-WebSocket-CLOSED><code>CLOSED</code></dfn> (numeric value 2)</dt>
-
- <dd>The connection has been closed or could not be opened.</dd>
-
- </dl><p>When the object is created its <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> must be set to
- <code title=dom-WebSocket-CONNECTING><a href=#dom-websocket-connecting>CONNECTING</a></code> (0). The
- steps executed when the constructor is invoked change this
- attribute's value.</p>
-
- <p>The <dfn id=dom-websocket-postmessage title=dom-WebSocket-postMessage><code>postMessage(<var title="">data</var>)</code></dfn> method transmits data using the
- connection. If the connection is not established (<code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> is not <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code>), it must raise an
- <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception. If the connection
- <em>is</em> established, then the user agent must <a href=#send-data-using-the-web-socket>send <var title="">data</var> using the Web Socket</a>.</p>
-
- <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-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>
-
- <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-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>
-
- <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-onclose title=handler-WebSocket-onclose><code>onclose</code></dfn></dt>
-
- <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.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>
-
- <ol><li>
-
- <p>Change the <code title=dom-WebSocket-readyState><a href=#dom-websocket-readystate>readyState</a></code> attribute's value
- to <code title=dom-WebSocket-OPEN><a href=#dom-websocket-open>OPEN</a></code> (1).</p>
-
- </li>
-
- <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-open>open</code> at the
- <code><a href=#websocket>WebSocket</a></code> object.</p>
-
- </li>
-
- </ol><hr><p>When <i>a Web Socket message has been received</i> with text <var title="">data</var>, the user agent must create an event that uses
- the <code><a href=#messageevent>MessageEvent</a></code> interface, with the event name <code title=event-message><a href=#event-message>message</a></code>, which does not bubble, is
- cancelable, has no default action, and whose <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute is set to <var title="">data</var>, and <a href=#queue-a-task>queue a task</a> to dispatch it at
- the <code><a href=#websocket>WebSocket</a></code> object.</p>
-
- <hr><p id=closeWebSocket>When the <i><a href=#web-socket-connection-is-closed>Web Socket connection is
- 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-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
- task">queued</a> in this section is the <dfn id=web-socket-task-source>Web Socket task
- 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.4 </span>The Web Socket
- protocol</h4>
-
- <div class=no-rfc>
- <p class=note>This section will be extracted into an RFC in due
- course.</p>
- </div>
-
- <h5 id=introduction-7><span class=secno>7.3.4.1 </span>Introduction</h5>
-
- <p class=XXX>...</p>
-
- <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>
-
- <p class=note>This specification doesn't currently define a limit
- to the number of simultaneous connections that a client can
- establish to a server.</p>
-
-
- <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
- port <var title="">port</var>, from an origin <var title="">origin</var>, with a flag <var title="">secure</var>, and
- with a particular <var title="">resource name</var>, it must run the
- following steps.</p>
-
- <p class=note>The <var title="">host</var> and <var title="">origin</var> strings will be all-lowercase when this
- algorithm is invoked.</p>
-
- <ol><li>
-
- <p>If there is no explicit <var title="">port</var>, then: if <var title="">secure</var> is false, let <var title="">port</var> be 81,
- otherwise let <var title="">port</var> be 815.</p>
-
- </li>
-
- <li>
-
- <p>If the user agent is configured to use a proxy to connect to
- host <var title="">host</var> and/or port <var title="">port</var>, then connect to that proxy and ask it to open
- a TCP/IP connection to the host given by <var title="">host</var>
- and the port given by <var title="">port</var>.</p>
-
- <div class=example>
-
- <p>For example, if the user agent uses an HTTP proxy for all
- traffic, then if it was to try to connect to port 80 on server
- example.com, it might send the following lines to the proxy
- server:</p>
-
- <pre>CONNECT example.com HTTP/1.1</pre>
-
- <p>If there was a password, the connection might look like:</p>
-
- <pre>CONNECT example.com HTTP/1.1
-Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=</pre>
-
- </div>
-
- <p>Otherwise, if the user agent is not configured to use a proxy,
- then open a TCP/IP connection to the host given by <var title="">host</var> and the port given by <var title="">port</var>.</p>
-
- </li>
-
- <li><p>If the connection could not be opened, then <a href=#fail-the-web-socket-connection>fail the
- Web Socket connection</a> and abort these steps.</li>
-
- <li><p>If <var title="">secure</var> is true, perform a TLS
- handshake over the connection. If this fails (e.g. the server's
- certificate could not be verified), then <a href=#fail-the-web-socket-connection>fail the Web Socket
- connection</a> and abort these steps. Otherwise, all further
- communication on this channel must run through the encrypted
- tunnel. <a href=#refsRFC2246>[RFC2246]</a></li>
-
- <li>
-
- <p>Send the following bytes to the remote side (the server):</p>
-
- <pre>47 45 54 20</pre>
-
- <p>Send the <var title="">resource name</var> value, encoded as
- US-ASCII.</p>
-
- <p>Send the following bytes:</p>
-
- <pre>20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61
-64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43
-6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61
-64 65 0d 0a</pre>
-
- <p class=note>The string "GET ", the path,
- " HTTP/1.1", CRLF, the string "Upgrade: WebSocket",
- CRLF, and the string "Connection: Upgrade", CRLF.</p>
-
- </li>
-
- <li>
-
- <p>Send the following bytes:</p>
-
- <pre>48 6f 73 74 3a 20</pre>
-
- <p>Send the <var title="">host</var> value, encoded as
- US-ASCII.</p>
-
- <p>Send the following bytes:</p>
-
- <pre>0d 0a</pre>
-
- <p class=note>The string "Host: ", the host, and CRLF.</p>
-
- </li>
-
- <li>
-
- <p>Send the following bytes:</p>
-
- <pre>4f 72 69 67 69 6e 3a 20</pre>
-
- <p>Send the <var title="">origin</var> value, encoded as US-ASCII.</p>
-
- <p class=note>The <var title="">origin</var> value is a string
- that was passed to this algorithm.</p>
-
- <p>Send the following bytes:</p>
-
- <pre>0d 0a</pre>
-
- <p class=note>The string "Origin: ", the origin, and CRLF.</p>
-
- </li>
-
- <li>
-
- <p>If the client has any authentication information or cookies
- that would be relevant to a resource accessed over HTTP, if <var title="">secure</var> is false, or HTTPS, if it is true, on host
- <var title="">host</var>, port <var title="">port</var>, with <var title="">resource name</var> as the path (and possibly query
- parameters), then HTTP headers that would be appropriate for that
- information should be sent at this point. <a href=#refsRFC2616>[RFC2616]</a> <a href=#refsRFC2109>[RFC2109]</a> <a href=#refsRFC2965>[RFC2965]</a></p>
-
- <p>Each header must be on a line of its own (each ending with a CR
- LF sequence). For the purposes of this step, each header must not
- be split into multiple lines (despite HTTP otherwise allowing this
- with continuation lines).</p>
-
- <div class=example>
-
- <p>For example, if the server had a username and password that
- applied to <code title="">http://example.com/socket</code>, and
- the Web Socket was being opened to <code title="">ws://example.com:80/socket</code>, it could send
- them:</p>
-
- <pre>Authorization: Basic d2FsbGU6ZXZl</pre>
-
- <p>However, it would not send them if the Web Socket was being
- opened to <code title="">ws://example.com/socket</code>, as that
- uses a different port (81, not 80).</p>
-
- </div>
-
- </li>
-
- <li>
-
- <p>Send the following bytes:</p>
-
- <pre>0d 0a</pre>
-
- <p class=note>Just a CRLF (a blank line).</p>
-
- </li>
-
- <li>
-
- <p>Read the first 85 bytes from the server. If the connection
- closes before 85 bytes are received, or if the first 85 bytes
- aren't exactly equal to the following bytes, then <a href=#fail-the-web-socket-connection>fail the
- Web Socket connection</a> and abort these steps.</p>
-
- <pre>48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62
-20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c
-20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72
-61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a
-43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72
-61 64 65 0d 0a</pre>
-
- <p class=note>The string
- "HTTP/1.1 101 Web Socket Protocol Handshake", CRLF, the
- string "Upgrade: WebSocket", CRLF, the string
- "Connection: Upgrade", CRLF.</p>
-
- <!-- v2 if we ever support the server requiring credentials, this
- is where it goes -->
-
- </li>
-
- <li><p>Let <var title="">headers</var> be a list of name-value
- pairs, initially empty.</li>
-
- <li id=ws-ua-header-loop><p><em>Header</em>: Let <var title="">name</var> and <var title="">value</var> be empty byte
- arrays.</li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, then
- <a href=#fail-the-web-socket-connection>fail the Web Socket connection</a> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class=switch><dt>If the byte is 0x0d (ASCII CR)</dt>
-
- <dd>If the <var title="">name</var> byte array is empty, then
- jump to the <a href=#ws-ua-headers-processing>headers
- processing</a> step. Otherwise, <a href=#fail-the-web-socket-connection>fail the Web Socket
- connection</a> and abort these steps.</dd>
-
-
- <dt>If the byte is 0x0a (ASCII LF)</dt>
-
- <dd><a href=#fail-the-web-socket-connection>Fail the Web Socket connection</a> and abort these
- steps.</dd>
-
-
- <dt>If the byte is 0x3a (ASCII ":")</dt>
-
- <dd>Move on to the next step.</dd>
-
-
- <dt>If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z")</dt>
-
- <dd>Append a byte whose value is the byte's value plus 0x20 to
- the <var title="">name</var> byte array and redo this step for
- the next byte.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Append the byte to the <var title="">name</var> byte
- array and redo this step for the next byte.</dd>
-
- </dl><p class=note>This reads a header name, terminated by a colon,
- converting upper-case ASCII letters to lowercase, and aborting if
- a stray CR or LF is found.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, then
- <a href=#fail-the-web-socket-connection>fail the Web Socket connection</a> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class=switch><dt>If the byte is 0x20 (ASCII space)</dt>
-
- <dd>Ignore the byte and move on to the next step.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Treat the byte as described by the list in the next step,
- then move on to that next step for real.</dd>
-
- </dl><p class=note>This skips past a space character after the colon,
- if necessary.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, then
- <a href=#fail-the-web-socket-connection>fail the Web Socket connection</a> and abort these
- steps.</p>
-
- <p>Otherwise, handle the byte as described in the appropriate
- entry below:</p>
-
- <dl class=switch><dt>If the byte is 0x0d (ASCII CR)</dt>
-
- <dd>Move on to the next step.</dd>
-
-
- <dt>If the byte is 0x0a (ASCII LF)</dt>
-
- <dd><a href=#fail-the-web-socket-connection>Fail the Web Socket connection</a> and abort these
- steps.</dd>
-
-
- <dt>Otherwise</dt>
-
- <dd>Append the byte to the <var title="">name</var> byte array
- and redo this step for the next byte.</dd>
-
- </dl><p class=note>This reads a header value, terminated by a
- CRLF.</p>
-
- </li>
-
- <li>
-
- <p>Read a byte from the server.</p>
-
- <p>If the connection closes before this byte is received, or if
- the byte is not a 0x0a byte (ASCII LF), then <a href=#fail-the-web-socket-connection>fail the Web
- Socket connection</a> and abort these steps.</p>
-
- <p class=note>This skips past the LF byte of the CRLF after the
- header.</p>
-
- </li>
-
- <li>
-
- <p>Append an entry to the <var title="">headers</var> list that
- has the name given by the string obtained by interpreting the <var title="">name</var> byte array as a UTF-8 byte stream and the
- value given by the string obtained by interpreting the <var title="">value</var> byte array as a UTF-8 byte stream.</p>
-
- </li>
-
- <li>
-
- <p>Return to the <a href=#ws-ua-header-loop>header</a> step
- above.</p>
-
- </li>
-
- <li id=ws-ua-headers-processing>
-
- <p><em>Headers processing</em>: If there is not exactly one entry
- in the <var title="">headers</var> list whose name is "<code title="">websocket-origin</code>", or if there is not exactly one
- entry in the <var title="">headers</var> list whose name is "<code title="">websocket-location</code>", or if there are any entries
- in the <var title="">headers</var> list whose names are the empty
- string, then <a href=#fail-the-web-socket-connection>fail the Web Socket connection</a> and abort
- these steps.</p>
-
- </li>
-
- <li>
-
- <p>Handle each entry in the <var title="">headers</var> list as
- follows:</p>
-
- <dl class=switch><dt>If the entry's name is "<code title="">websocket-origin</code>"</dt>
-
- <dd><p>If the value is not exactly equal to <var title="">origin</var>, <a href=#converted-to-lowercase>converted to lowercase</a>, then
- <a href=#fail-the-web-socket-connection>fail the Web Socket connection</a> and abort these
- steps.</dd>
-
-
- <dt>If the entry's name is "<code title="">websocket-location</code>"</dt>
-
- <dd>
-
- <p>If the value is not exactly equal to a string consisting of
- the following components in the same order, then <a href=#fail-the-web-socket-connection>fail the
- Web Socket connection</a> and abort these steps:</p>
-
- <ol><li>The string "<code title="">ws</code>" if <var title="">secure</var> is false and "<code title="">wss</code>" if <var title="">secure</var> is
- true</li>
-
- <li>The three characters "<code title="">://</code>".</li>
-
- <li>The value of <var title="">host</var>.</li>
-
- <li>If <var title="">secure</var> is false and <var title="">port</var> is not 81, or if <var title="">secure</var>
- is true and <var title="">port</var> is not 815: a "<code title="">:</code>" character followed by the value of <var title="">port</var>.</li>
-
- <li>The value of <var title="">resource name</var>.</li>
-
- </ol></dd>
-
-
- <dt>If the entry's name is "<code title="">set-cookie</code>" or
- "<code title="">set-cookie2</code>" or another cookie-related
- header name</dt>
-
- <dd><p>Handle the cookie as defined by the appropriate spec, with
- the resource being the one with the host <var title="">host</var>, the port <var title="">port</var>, the path
- (and possibly query parameters) <var title="">resource
- name</var>, and the scheme <code title="">http</code> if <var title="">secure</var> is false and <code title="">https</code> if
- <var title="">secure</var> is true. <a href=#refsRFC2109>[RFC2109]</a> <a href=#refsRFC2965>[RFC2965]</a></dd>
-
-
- <dt>Any other name</dt>
-
- <dd>Ignore it.</dd>
-
- </dl></li>
-
- <li>
-
- <p>The <dfn id=web-socket-connection-is-established>Web Socket connection is established</dfn>. Now the
- user agent must send and receive to and from the connection as
- described in the next section.</p>
-
- </li>
-
- </ol><p>To <dfn id=fail-the-web-socket-connection>fail the Web Socket connection</dfn>, the user agent must
- <a href=#close-the-web-socket-connection>close the Web Socket connection</a>, and may report the
- problem to the user (which would be especially useful for
- developers). However, user agents must not convey the failure
- information to the script that attempted the connection in a way
- distinguishable from the Web Socket being closed normally.</p>
-
-
- <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
- bytes sent by the server.</p>
-
- <ol><li>
-
- <p>Try to read a byte from the server. Let <var title="">frame
- type</var> be that byte.</p>
-
- <p>If no byte could be read because the <a href=#web-socket-connection-is-closed>Web Socket
- connection is closed</a>, then abort.</p>
-
- </li>
-
- <li>
-
- <p>Handle the <var title="">frame type</var> byte as follows:</p>
-
- <dl><dt>If the high-order bit of the <var title="">frame type</var>
- byte is set (i.e. if <var title="">frame type</var> <i title="">and</i>ed with 0x80 returns 0x80)</dt>
-
- <dd>
-
- <p>Run these steps. If at any point during these steps a read is
- attempted but fails because the <a href=#web-socket-connection-is-closed>Web Socket connection is
- closed</a>, then abort.</p>
-
- <ol><li><p>Let <var title="">length</var> be zero.</li>
-
- <li id=ws-cd-length><p><em>Length</em>: Read a byte, let <var title="">b</var> be that byte.</li>
-
- <li><p>Let <var title="">b<sub title="">v</sub></var> be
- integer corresponding to the low 7 bits of <var title="">b</var>
- (the value you would get by <i>and</i>ing <var title="">b</var>
- with 0x7f).</li>
-
- <li><p>Multiply <var title="">length</var> by 128, add <var title="">b<sub title="">v</sub></var> to that result, and store
- the final result in <var title="">length</var>.</li>
-
- <li><p>If the high-order bit of <var title="">b</var> is set
- (i.e. if <var title="">b</var> <i title="">and</i>ed with 0x80
- returns 0x80), then return to the step above labeled <a href=#ws-cd-length><i>length</i></a>.</li>
-
- <li><p>Read <var title="">length</var> bytes.</li>
-
- <li><p>Discard the read bytes.</li>
-
- </ol></dd>
-
- <dt>If the high-order bit of the <var title="">frame type</var>
- byte is <em>not</em> set (i.e. if <var title="">frame type</var>
- <i title="">and</i>ed with 0x80 returns 0x00)</dt>
-
- <dd>
-
- <p>Run these steps. If at any point during these steps a read is
- attempted but fails because the <a href=#web-socket-connection-is-closed>Web Socket connection is
- closed</a>, then abort.</p>
-
- <ol><li><p>Let <var title="">raw data</var> be an empty byte array.</li>
-
- <li id=ws-cd-data><p><em>Data</em>: Read a byte, let <var title="">b</var> be that byte.</li>
-
- <li><p>If <var title="">b</var> is not 0xff, then append <var title="">b</var> to <var title="">raw data</var> and return to
- the previous step (labeled <a href=#ws-cd-data><i>data</i></a>).</li>
-
- <li><p>Interpret <var title="">raw data</var> as a UTF-8
- string, and store that string in <var title="">data</var>.</p>
-
- <li><p>If <var title="">frame type</var> is 0x00, then <dfn id=a-message-has-been-received>a
- message has been received</dfn> with text <var title="">data</var>. Otherwise, discard the data.</li>
-
- </ol></dd>
-
- </dl></li>
-
- <li><p>Return to the first step to read the next byte.</li>
-
- </ol><p>If the user agent is faced with content that is too large to be
- handled appropriately, then it must <a href=#fail-the-web-socket-connection>fail the Web Socket
- connection</a>.</p>
-
- <hr><p>Once a <a href=#web-socket-connection-is-established>Web Socket connection is established</a>, the
- user agent must use the following steps to <dfn id=send-data-using-the-web-socket>send <var title="">data</var> using the Web Socket</dfn>:</p>
-
- <ol><li><p>Send a 0x00 byte to the server.</li>
-
- <li><p>Encode <var title="">data</var> using UTF-8 and send the
- resulting byte stream to the server.</li>
-
- <li><p>Send a 0xff byte to the server.</li>
-
- </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.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.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>
-
- <p>Listen on a port for TCP/IP. Upon receiving a connection request,
- open a connection and send the following bytes back to the
- client:</p>
-
- <pre>48 54 54 50 2f 31 2e 31 20 31 30 31 20 57 65 62
-20 53 6f 63 6b 65 74 20 50 72 6f 74 6f 63 6f 6c
-20 48 61 6e 64 73 68 61 6b 65 0d 0a 55 70 67 72
-61 64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a
-43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72
-61 64 65 0d 0a</pre>
-
- <p>Send the string "<code title="">WebSocket-Origin</code>" followed
- by a U+003A COLON (":") followed by the <a href=#ascii-serialization-of-an-origin title="ASCII
- serialization of an origin">ASCII serialization</a> of the origin
- from which the server is willing to accept connections, followed by
- a CRLF pair (0x0d 0x0a).</p>
-
- <div class=example>
-
- <p>For instance:</p>
-
- <pre>WebSocket-Origin: http://example.com</pre>
-
- </div>
-
- <p>Send the string "<code title="">WebSocket-Location</code>"
- followed by a U+003A COLON (":") followed by the <a href=#url>URL</a> of
- the Web Socket script, followed by a CRLF pair (0x0d 0x0a).</p>
-
- <div class=example>
-
- <p>For instance:</p>
-
- <pre>WebSocket-Location: ws://example.com:80/demo</pre>
-
- </div>
-
- <p>Send another CRLF pair (0x0d 0x0a).</p>
-
- <p>Read (and discard) data from the client until four bytes 0x0d
- 0x0a 0x0d 0x0a are read.</p>
-
- <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.4.3.2 </span>Handshake details</h6>
-
- <p>The previous section ignores the data that is transmitted by the
- client during the handshake.</p>
-
- <p>The data sent by the client consists of a number of fields
- separated by CR LF pairs (bytes 0x0d 0x0a).</p>
-
- <p>The first field consists of three tokens separated by space
- characters (byte 0x20). The middle token is the path being
- opened. If the server supports multiple paths, then the server
- should echo the value of this field in the initial handshake, as
- part of the <a href=#url>URL</a> given on the <code title="">WebSocket-Location</code> line (after the appropriate
- scheme and host).</p>
-
- <p>The remaining fields consist of name-value pairs, with the name
- part separated from the value part by a colon and a space (bytes
- 0x3a 0x20). Of these, several are interesting:</p>
-
- <dl><dt>Host (bytes 48 6f 73 74)</dt>
-
- <dd>
-
- <p>The value gives the hostname that the client intended to use
- when opening the Web Socket. It would be of interest in particular
- to virtual hosting environments, where one server might serve
- multiple hosts, and might therefore want to return different
- data.</p>
-
- <p>The right host has to be output as part of the <a href=#url>URL</a>
- given on the <code title="">WebSocket-Location</code> line of the
- handshake described above, to verify that the server knows that it
- is really representing that host.</p>
-
- </dd>
-
- <dt>Origin (bytes 4f 72 69 67 69 6e)</dt>
-
- <dd>
-
- <p>The value gives the scheme, hostname, and port (if it's not the
- default port for the given scheme) of the page that asked the
- client to open the Web Socket. It would be interesting if the
- server's operator had deals with operators of other sites, since
- the server could then decide how to respond (or indeed,
- <em>whether</em> to respond) based on which site was requesting a
- connection.</p>
-
- <p>If the server supports connections from more than one origin,
- then the server should echo the value of this field in the initial
- handshake, on the <code title="">WebSocket-Origin</code> line.</p>
-
- </dd>
-
- <dt>Other fields</dt>
-
- <dd>
-
- <p>Other fields can be used, such as "<code title="">Cookie</code>" or "<code>Authorization</code>", for
- authentication purposes.</p>
-
- </dd>
-
- </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
- doesn't handle any arbitrary content in the same way that the
- requirements on user agents defined earlier handle any content
- including possible future extensions to the protocols.</p>
-
- <p>The server should run through the following steps to process the
- bytes sent by the client:</p>
-
- <ol><li><p>Read a byte from the client. Assuming everything is going
- according to plan, it will be a 0x00 byte. Behaviour for the server
- is undefined if the byte is not 0x00.</li>
-
- <li><p>Let <var title="">raw data</var> be an empty byte
- array.</li>
-
- <li id=ws-sd-data><p><i>Data</i>: Read a byte, let <var title="">b</var> be that byte.</li>
-
- <li><p>If <var title="">b</var> is not 0xff, then append <var title="">b</var> to <var title="">raw data</var> and return to the
- previous step (labeled <a href=#ws-sd-data><i>data</i></a>).</li>
-
- <li><p>Interpret <var title="">raw data</var> as a UTF-8 string,
- and apply whatever server-specific processing should occur for the
- resulting string.</p>
-
- <li><p>Return to the first step to read the next byte.</li>
-
- </ol><hr><p>The server should run through the following steps to send strings
- to the client:</p>
-
- <ol><li><p>Send a 0x00 byte to the client to indicate the start of a
- string.</li>
-
- <li><p>Encode <var title="">data</var> using UTF-8 and send the
- resulting byte stream to the client.</li>
-
- <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.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
- closing handshake. Whether the user agent or the server closes the
- connection, it is said that the <dfn id=web-socket-connection-is-closed>Web Socket connection is
- closed</dfn>.</p>
-
- <p>Servers may <a href=#close-the-web-socket-connection>close the Web Socket connection</a> whenever
- desired.</p>
-
- <p>User agents should not <a href=#close-the-web-socket-connection>close the Web Socket
- connection</a> arbitrarily.</p>
-
-
- <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.4.6 </span>IANA considerations</h5>
-
- <p class=XXX>...(two URI schemes, two ports, HTTP Upgrade keyword)</p>
-
-
- <h3 id=crossDocumentMessages><span class=secno>7.4 </span><dfn>Cross-document messaging</dfn></h3>
-
<p>Web browsers, for security and privacy reasons, prevent documents
in different domains from affecting each other; that is, cross-site
scripting is disallowed.</p>
@@ -52481,7 +49765,7 @@
</div>
- <h4 id=introduction-8><span class=secno>7.4.1 </span>Introduction</h4>
+ <h4 id=introduction-5><span class=secno>7.2.1 </span>Introduction</h4>
<p><em>This section is non-normative.</em></p>
@@ -52522,11 +49806,11 @@
</div>
- <h4 id=security-5><span class=secno>7.4.2 </span>Security</h4>
+ <h4 id=security-4><span class=secno>7.2.2 </span>Security</h4>
<div class=impl>
- <h5 id=authors><span class=secno>7.4.2.1 </span>Authors</h5>
+ <h5 id=authors><span class=secno>7.2.2.1 </span>Authors</h5>
</div>
@@ -52547,7 +49831,7 @@
<div class=impl>
- <h5 id=user-agents><span class=secno>7.4.2.2 </span>User agents</h5>
+ <h5 id=user-agents><span class=secno>7.2.2.2 </span>User agents</h5>
<p>The integrity of this API is based on the inability for scripts
of one <a href=#origin-0>origin</a> to post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in other
@@ -52563,7 +49847,7 @@
</div>
- <h4 id=posting-messages><span class=secno>7.4.3 </span>Posting messages</h4>
+ <h4 id=posting-messages><span class=secno>7.2.3 </span>Posting messages</h4>
<dl class=domintro><dt><var title="">window</var> . <code title=dom-window-postMessage-2><a href=#dom-window-postmessage-2>postMessage</a></code>(<var title="">message</var>, [ <var title="">port</var>, ] <var title="">targetOrigin</var>)</dt>
@@ -52652,7 +49936,7 @@
<div class=impl>
- <h4 id=posting-messages-with-message-ports><span class=secno>7.4.4 </span>Posting messages with message ports</h4>
+ <h4 id=posting-messages-with-message-ports><span class=secno>7.2.4 </span>Posting messages with message ports</h4>
<p>When a script invokes the <dfn id=dom-window-postmessage-3 title=dom-window-postMessage-3><code>postMessage(<var title="">message</var>, <var title="">messagePort</var>, <var title="">targetOrigin</var>)</code></dfn> method (with three
arguments) on a <code><a href=#window>Window</a></code> object, the user agent must
@@ -52758,9 +50042,9 @@
- <h3 id=channel-messaging><span class=secno>7.5 </span><dfn>Channel messaging</dfn></h3>
+ <h3 id=channel-messaging><span class=secno>7.3 </span><dfn>Channel messaging</dfn></h3>
- <h4 id=introduction-9><span class=secno>7.5.1 </span>Introduction</h4>
+ <h4 id=introduction-6><span class=secno>7.3.1 </span>Introduction</h4>
<p><em>This section is non-normative.</em></p>
@@ -52769,7 +50053,7 @@
- <h4 id=message-channels><span class=secno>7.5.2 </span>Message channels</h4>
+ <h4 id=message-channels><span class=secno>7.3.2 </span>Message channels</h4>
<pre class=idl>[<a href=#dom-messagechannel title=dom-MessageChannel>Constructor</a>]
interface <dfn id=messagechannel>MessageChannel</dfn> {
@@ -52834,7 +50118,7 @@
- <h4 id=message-ports><span class=secno>7.5.3 </span>Message ports</h4>
+ <h4 id=message-ports><span class=secno>7.3.3 </span>Message ports</h4>
<p>Each channel has two message ports. Data sent through one port is
received by the other port, and vice versa.</p>
@@ -53109,7 +50393,7 @@
<div class=impl>
- <h5 id=ports-and-garbage-collection><span class=secno>7.5.3.1 </span>Ports and garbage collection</h5>
+ <h5 id=ports-and-garbage-collection><span class=secno>7.3.3.1 </span>Ports and garbage collection</h5>
<p>User agents must act as if <code><a href=#messageport>MessagePort</a></code> objects have
a strong reference to their entangled <code><a href=#messageport>MessagePort</a></code>
@@ -62653,7 +59937,7 @@
lead to this experience.</em></p>
- <h3 id=introduction-10><span class=secno>10.1 </span>Introduction</h3>
+ <h3 id=introduction-7><span class=secno>10.1 </span>Introduction</h3>
<p>In general, user agents are expected to support CSS, and many of
the suggestions in this section are expressed in CSS terms. User
@@ -62675,7 +59959,7 @@
<h3 id=the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>10.2 </span>The CSS user agent style sheet and presentational hints</h3>
- <h4 id=introduction-11><span class=secno>10.2.1 </span>Introduction</h4>
+ <h4 id=introduction-8><span class=secno>10.2.1 </span>Introduction</h4>
<p>The CSS rules given in these subsections are, unless otherwise
specified, expected to be used as part of the user-agent level style
@@ -63846,7 +61130,7 @@
<h3 id=bindings><span class=secno>10.4 </span>Bindings</h3>
- <h4 id=introduction-12><span class=secno>10.4.1 </span>Introduction</h4>
+ <h4 id=introduction-9><span class=secno>10.4.1 </span>Introduction</h4>
<p>A number of elements have their rendering defined in terms of the
'binding' property. <a href=#refsBECSS>[BECSS]</a></p>
Modified: source
===================================================================
--- source 2009-03-18 06:49:56 UTC (rev 2876)
+++ source 2009-03-18 19:31:53 UTC (rev 2877)
@@ -1,3 +1,4 @@
+<!--START html5-->
<h3 class="no-num no-toc">Stability</h3>
@@ -43868,9 +43869,9 @@
// the user agent
readonly attribute <span>Navigator</span> <span title="dom-navigator">navigator</span>; <!-- XXX IE6 also has window.clientInformation pointing to this same object -->
- readonly attribute <span>Storage</span> <span title="dom-localStorage">localStorage</span>;
+ readonly attribute <span>Storage</span> <span title="dom-localStorage">localStorage</span>; <!-- XXX split into separate interface -->
readonly attribute <span>Storage</span> <span title="dom-sessionStorage">sessionStorage</span>;
- <span>Database</span> <span title="dom-opendatabase">openDatabase</span>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
+ <span>Database</span> <span title="dom-opendatabase">openDatabase</span>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize); <!-- XXX split into separate interface -->
readonly attribute <span>ApplicationCache</span> <span title="dom-applicationCache">applicationCache</span>;
// user prompts
@@ -51081,10 +51082,10 @@
</div>
+ <h3>Structured client-side storage</h3> <!--START storage-->
+ <!--BOILERPLATE middle-w3c-api-intro-->
- <h3>Structured client-side storage</h3>
-
<h4 id="storage">Storing name/value pairs</h4>
<h5>Introduction</h5>
@@ -52387,8 +52388,10 @@
and to never construct SQL statements on the fly.</p>
+ <!--END storage-->
+
<h3 id="links">Links</h3>
@@ -57853,6 +57856,7 @@
<h3>Event definitions</h3>
+ <!-- XXX cross-references for SSE and WS need fixing now that this is cross-spec -->
<p>Messages in <span>server-sent events</span>, <span>Web
sockets</span>, <span>cross-document messaging</span>, and
<span>channel messaging</span> use the <dfn
@@ -57973,8 +57977,7 @@
- <h3 id="server-sent-events"><dfn>Server-sent events</dfn></h3>
- <!-- eventsource -->
+ <h3 id="server-sent-events"><dfn>Server-sent events</dfn></h3> <!--START eventsource-->
<h4 id="server-sent-events-intro">Introduction</h4>
@@ -57987,7 +57990,7 @@
<p class="XXX">An introduction to the client-side and
server-side of using the direct connection APIs.</p>
- <!--BOILERPLATE-->
+ <!--BOILERPLATE middle-w3c-api-intro-->
<h4>The <code>EventSource</code> interface</h4>
@@ -58622,10 +58625,12 @@
<p>If an <code>EventSource</code> object is garbage collected while
its connection is still open, the connection must be closed.</p>
+ <!--END eventsource-->
- <h3 id="network"><dfn>Web sockets</dfn></h3>
+ <h3 id="network"><dfn>Web sockets</dfn></h3> <!--START websocket--><!--START websocket-api-->
+
<h4 id="network-intro">Introduction</h4>
<p><em>This section is non-normative.</em></p>
@@ -58642,7 +58647,7 @@
<p class="XXX">An introduction to the client-side and
server-side of using the direct connection APIs.</p>
- <!--BOILERPLATE-->
+ <!--BOILERPLATE middle-w3c-api-intro-->
<h4>The <code>WebSocket</code> interface</h4>
@@ -58880,6 +58885,7 @@
Socket connection</span>.</p>
+ <!--END websocket-api-->
<h4 id="websocket-protocol" title="This protocol enables two-way
communication between a user agent running untrusted code running in
@@ -59694,7 +59700,9 @@
<p class="XXX">...(two URI schemes, two ports, HTTP Upgrade keyword)</p>
+ <!--END websocket-->
+
<h3 id="crossDocumentMessages"><dfn>Cross-document messaging</dfn></h3>
<p>Web browsers, for security and privacy reasons, prevent documents
@@ -71852,3 +71860,4 @@
</body>
</html>
+<!--END html5-->
More information about the Commit-Watchers
mailing list