- From: CVS User ihickson <cvsmail@w3.org>
- Date: Fri, 18 Oct 2013 06:28:11 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/postmsg
In directory roscoe:/tmp/cvs-serv26571
Modified Files:
Overview.html
Log Message:
The giant clean-up of 2013. Improved internal consistency, adjusted section order to make more sense, started a move away from abusing title='' for cross-references, fixed minor typos, cleaned up some dangling TODOs, very minor typo fixes, dropped some obsolete comments, un-commented-out minor things that had previously been commented out for reasons that no longer apply, etc. No normative changes. (whatwg r8229)
--- /sources/public/html5/postmsg/Overview.html 2013/10/09 22:05:26 1.152
+++ /sources/public/html5/postmsg/Overview.html 2013/10/18 06:28:11 1.153
@@ -216,7 +216,7 @@
<h1>HTML5 Web Messaging</h1>
- <h2 class="no-num no-toc" id="editor-s-draft-9-october-2013">Editor's Draft 9 October 2013</h2>
+ <h2 class="no-num no-toc" id="editor-s-draft-18-october-2013">Editor's Draft 18 October 2013</h2>
<dl><dt>Latest Published Version:</dt>
<dd><a href="http://www.w3.org/TR/webmessaging/">http://www.w3.org/TR/webmessaging/</a></dd>
<dt>Latest Editor's Draft:</dt>
@@ -348,7 +348,7 @@
</dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
Working Group</a> is the W3C working group responsible for this
specification's progress along the W3C Recommendation track.
- This specification is the 9 October 2013 Editor's Draft.
+ This specification is the 18 October 2013 Editor's Draft.
</p>
@@ -552,62 +552,50 @@
</dl><div class="impl">
- <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn>
- attribute must return the value it was initialized to. When the
- object is created, this attribute must be initialized to null. It
+ <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn> attribute must return the value
+ it was initialized to. When the object is created, this attribute must be initialized to null. It
represents the message being sent.</p>
- <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute
- must return the value it was initialized to. When the object is
- created, this attribute must be initialized to the empty string. It
- represents, in <span>server-sent events</span> and
- <a href="#web-messaging">cross-document messaging</a>, the <span>origin</span> 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 must return the value it was initialized to. When the
- object is created, this attribute must be initialized to the empty
- string. It represents, in <span>server-sent events</span>, the <span title="concept-event-stream-last-event-id">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
- must return the value it was initialized to. When the object is
- created, this attribute must be initialized to null. It represents,
- in <a href="#web-messaging">cross-document messaging</a>, the
- <code>WindowProxy</code> of the <span>browsing context</span> of the
- <code>Window</code> object from which the message came; and in the
- <code title="event-connect">connect</code> events used by <span title="SharedWorkerGlobalScope">shared workers</span>, the newly
- connecting <code><a href="#messageport">MessagePort</a></code>.</p>
-
- <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn>
- attribute must return the value it was initialized to. When the
- object is created, this attribute must be initialized to null.
- It represents, in <a href="#web-messaging">cross-document messaging</a> and
- <a href="#channel-messaging">channel messaging</a> the <code><a href="#messageport">MessagePort</a></code> array
- being sent, if any.</p>
+ <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute must return the
+ value it was initialized to. When the object is created, this attribute must be initialized to the
+ empty string. It represents, in <span>server-sent events</span> and <a href="#web-messaging">cross-document
+ messaging</a>, the <span>origin</span> 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 must
+ return the value it was initialized to. When the object is created, this attribute must be
+ initialized to the empty string. It represents, in <span>server-sent events</span>, the <span title="concept-event-stream-last-event-id">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 must return the
+ value it was initialized to. When the object is created, this attribute must be initialized to
+ null. It represents, in <a href="#web-messaging">cross-document messaging</a>, the <code>WindowProxy</code> of the
+ <span>browsing context</span> of the <code>Window</code> object from which the message came; and
+ in the <code title="event-connect">connect</code> events used by <span title="SharedWorkerGlobalScope">shared workers</span>, the newly connecting
+ <code><a href="#messageport">MessagePort</a></code>.</p>
+
+ <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn> attribute must return the
+ value it was initialized to. When the object is created, this attribute must be initialized to
+ null. It represents, in
+ <a href="#web-messaging">cross-document messaging</a> and <a href="#channel-messaging">channel messaging</a> the
+ <code><a href="#messageport">MessagePort</a></code> array being sent, if any.</p>
</div>
<h2 id="web-messaging"><span class="secno">4 </span><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h2>
- <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>
-
- <p>While this is an important security feature, it prevents pages
- from different domains from communicating even when those pages are
- not hostile. This section introduces a messaging system that allows
- documents to communicate with each other regardless of their source
- domain, in a way designed to not enable cross-site scripting
- attacks.</p>
+ <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>
+
+ <p>While this is an important security feature, it prevents pages from different domains from
+ communicating even when those pages are not hostile. This section introduces a messaging system
+ that allows documents to communicate with each other regardless of their source domain, in a way
+ designed to not enable cross-site scripting attacks.</p>
<div class="impl">
- <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in <a href="#web-messaging">cross-document
- messaging</a> is the <dfn id="posted-message-task-source">posted message task source</dfn>.</p>
+ <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in
+ <a href="#web-messaging">cross-document messaging</a> is the <dfn id="posted-message-task-source">posted message task source</dfn>.</p>
</div>
@@ -618,21 +606,17 @@
<div class="example">
- <p>For example, if document A contains an <code>iframe</code>
- element that contains document B, and script in document A calls
- <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
- <code>Window</code> object of document B, then a message event will
- be fired on that object, marked as originating from the
- <code>Window</code> of document A. The script in document A might
+ <p>For example, if document A contains an <code>iframe</code> element that contains document B,
+ and script in document A calls <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
+ <code>Window</code> object of document B, then a message event will be fired on that object,
+ marked as originating from the <code>Window</code> of document A. The script in document A might
look like:</p>
<pre>var o = document.getElementsByTagName('iframe')[0];
o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
- <p>To register an event handler for incoming events, the script
- would use <code title="">addEventListener()</code> (or similar
- mechanisms). For example, the script in document B might look
- like:</p>
+ <p>To register an event handler for incoming events, the script would use <code title="">addEventListener()</code> (or similar mechanisms). For example, the script in document B
+ might look like:</p>
<pre>window.addEventListener('message', receiver, false);
function receiver(e) {
@@ -645,10 +629,9 @@
}
}</pre>
- <p>This script first checks the domain is the expected domain, and
- then looks at the message, which it either displays to the user, or
- responds to by sending a message back to the document which sent
- the message in the first place.</p>
+ <p>This script first checks the domain is the expected domain, and then looks at the message,
+ which it either displays to the user, or responds to by sending a message back to the document
+ which sent the message in the first place.</p>
</div>
@@ -662,55 +645,47 @@
</div>
- <p id="security-4" class="warning">Use of this API requires extra
- care to protect users from hostile entities abusing a site for their
- own purposes.</p>
-
- <p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to ensure
- that messages are only accepted from domains that they expect to
- receive messages from. Otherwise, bugs in the author's message
- handling code could be exploited by hostile sites.</p>
-
- <p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute, authors
- should also check that the data in question is of the expected
- format. Otherwise, if the source of the event has been attacked
- using a cross-site scripting flaw, further unchecked processing of
- information sent using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method could
- result in the attack being propagated into the receiver.</p>
-
- <p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var> argument in messages that contain any
- confidential information, as otherwise there is no way to guarantee
- that the message is only delivered to the recipient to which it was
- intended.</p>
-
- <hr><p>Authors who accept messages from any origin are encouraged to
- consider the risks of a denial-of-service attack. An attacker could
- send a high volume of messages; if the receiving page performs
- expensive computation or causes network traffic to be sent for each
- such message, the attacker's message could be multplied into a
- denial-of-service attack. Authors are encouraged to employ rate
- limiting (only accepting a certain number of messages per minute) to
- make such attacks impractical.</p>
+ <p id="security-4" class="warning">Use of this API requires extra care to protect users from
+ hostile entities abusing a site for their own purposes.</p>
+
+ <p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to
+ ensure that messages are only accepted from domains that they expect to receive messages from.
+ Otherwise, bugs in the author's message handling code could be exploited by hostile sites.</p>
+
+ <p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code>
+ attribute, authors should also check that the data in question is of the expected format.
+ Otherwise, if the source of the event has been attacked using a cross-site scripting flaw, further
+ unchecked processing of information sent using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method could result in the attack being
+ propagated into the receiver.</p>
+
+ <p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var>
+ argument in messages that contain any confidential information, as otherwise there is no way to
+ guarantee that the message is only delivered to the recipient to which it was intended.</p>
+
+ <hr><p>Authors who accept messages from any origin are encouraged to consider the risks of a
+ denial-of-service attack. An attacker could send a high volume of messages; if the receiving page
+ performs expensive computation or causes network traffic to be sent for each such message, the
+ attacker's message could be multplied into a denial-of-service attack. Authors are encouraged to
+ employ rate limiting (only accepting a certain number of messages per minute) to make such attacks
+ impractical.</p>
<div class="impl">
<h4 id="user-agents"><span class="secno">4.2.2 </span>User agents</h4>
- <p>The integrity of this API is based on the inability for scripts
- of one <span>origin</span> to post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in other
- origins (those that are not the <span title="same
- origin">same</span>).</p>
-
- <p class="note">Implementors are urged to take extra care in the
- implementation of this feature. It allows authors to transmit
- information from one domain to another domain, which is normally
- disallowed for security reasons. It also requires that UAs be
- careful to allow access to certain properties but not others.</p>
-
- <hr><p>User agents are also encouraged to consider rate-limiting message
- traffic between different <span title="origin">origins</span>, to
- protect naïve sites from denial-of-service attacks.</p>
+ <p>The integrity of this API is based on the inability for scripts of one <span>origin</span> to
+ post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in
+ other origins (those that are not the <span title="same origin">same</span>).</p>
+
+ <p class="note">Implementors are urged to take extra care in the implementation of this feature.
+ It allows authors to transmit information from one domain to another domain, which is normally
+ disallowed for security reasons. It also requires that UAs be careful to allow access to certain
+ properties but not others.</p>
+
+ <hr><p>User agents are also encouraged to consider rate-limiting message traffic between different
+ <span title="origin">origins</span>, to protect naïve sites from denial-of-service
+ attacks.</p>
</div>
@@ -722,54 +697,43 @@
<dd>
- <p>Posts a message to the given window. Messages can be structured
- objects, e.g. nested objects and arrays, can contain JavaScript
- values (strings, numbers, <code>Date</code>s, etc), and can
- contain certain data objects such as <code>File</code>
- <code>Blob</code>, <code>FileList</code>, and
- <code>ArrayBuffer</code> objects.</p>
-
- <p>Objects listed in <var title="">transfer</var> are transferred,
- not just cloned, meaning that they are no longer usable on the
- sending side.</p>
-
- <p>If the origin of the target window doesn't match the given
- origin, the message is discarded, to avoid information leakage. To
- send the message to the target regardless of origin, set the
- target origin to "<code title="">*</code>". To restrict the
- message to same-origin targets only, without needing to explicitly
- state the origin, set the target origin to "<code title="">/</code>".</p>
+ <p>Posts a message to the given window. Messages can be structured objects, e.g. nested objects
+ and arrays, can contain JavaScript values (strings, numbers, <code>Date</code>s, etc), and can
+ contain certain data objects such as <code>File</code> <code>Blob</code>, <code>FileList</code>,
+ and <code>ArrayBuffer</code> objects.</p>
+
+ <p>Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning that
+ they are no longer usable on the sending side.</p>
+
+ <p>If the origin of the target window doesn't match the given origin, the message is discarded,
+ to avoid information leakage. To send the message to the target regardless of origin, set the
+ target origin to "<code title="">*</code>". To restrict the message to same-origin targets only,
+ without needing to explicitly state the origin, set the target origin to "<code title="">/</code>".</p>
<p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
duplicate objects or if <var title="">message</var> could not be cloned.</p>
</dd>
- </dl><p class="note">When posting a message to a <code>Window</code> of a
- <span>browsing context</span> that has just been navigated to a new
- <code>Document</code> is likely to result in the message not
- receiving its intended recipient: the scripts in the target
- <span>browsing context</span> have to have had time to set up
- listeners for the messages. Thus, for instance, in situations where
- a message is to be sent to the <code>Window</code> of newly created
- child <code>iframe</code>, authors are advised to have the child
- <code>Document</code> post a message to their parent announcing
- their readiness to receive messages, and for the parent to wait for
- this message before beginning posting messages.</p>
+ </dl><p class="note">When posting a message to a <code>Window</code> of a <span>browsing context</span>
+ that has just been navigated to a new <code>Document</code> is likely to result in the message not
+ receiving its intended recipient: the scripts in the target <span>browsing context</span> have to
+ have had time to set up listeners for the messages. Thus, for instance, in situations where a
+ message is to be sent to the <code>Window</code> of newly created child <code>iframe</code>,
+ authors are advised to have the child <code>Document</code> post a message to their parent
+ announcing their readiness to receive messages, and for the parent to wait for this message before
+ beginning posting messages.</p>
<div class="impl">
- <p>When a script invokes the <dfn id="dom-window-postmessage" title="dom-window-postMessage"><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">transfer</var>)</code></dfn> method (with two or three
- arguments) on a <code>Window</code> object, the user agent must
- follow these steps:</p>
+ <p>When a script invokes the <dfn id="dom-window-postmessage" title="dom-window-postMessage"><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">transfer</var>)</code></dfn> method (with two or three arguments) on a
+ <code>Window</code> object, the user agent must follow these steps:</p>
<ol><li>
- <p>If the value of the <var title="">targetOrigin</var> argument
- is neither a single U+002A ASTERISK character (*), a single U+002F
- SOLIDUS character (/), nor an <span>absolute URL</span>, then
- throw a <code>SyntaxError</code> exception and abort the overall
- set of steps.</p>
+ <p>If the value of the <var title="">targetOrigin</var> argument is neither a single U+002A
+ ASTERISK character (*), a single U+002F SOLIDUS character (/), nor an <span>absolute URL</span>,
+ then throw a <code>SyntaxError</code> exception and abort the overall set of steps.</p>
</li>
@@ -781,32 +745,29 @@
<li>
- <p>Let <var title="">transfer map</var> be an empty association
- list of <code>Transferable</code> objects to placeholder
- objects.</p>
+ <p>Let <var title="">transfer map</var> be an empty association list of
+ <code>Transferable</code> objects to placeholder objects.</p>
</li>
<li>
- <p>If the method was invoked with a third argument <var title="">transfer</var>, run these substeps:</p>
+ <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
+ substeps:</p>
<ol><li>
- <p>If any object is listed in <var title="">transfer</var> more
- than once, or any of the <code>Transferable</code> objects
- listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then
- throw a <code>DataCloneError</code> exception and abort these
- steps.</p>
+ <p>If any object is listed in <var title="">transfer</var> more than once, or any of the
+ <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
+ <code>DataCloneError</code> exception and abort these steps.</p>
</li>
<li>
- <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a mapping from <var title="">x</var> to a new unique placeholder object created for
- <var title="">x</var> to <var title="">transfer map</var>, and
- if <var title="">x</var> is a <code><a href="#messageport">MessagePort</a></code> object,
- also append the placeholder object to the <var title="">new
+ <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
+ mapping from <var title="">x</var> to a new unique placeholder object created for <var title="">x</var> to <var title="">transfer map</var>, and if <var title="">x</var> is a
+ <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
ports</var> array.</p>
</li>
@@ -815,32 +776,32 @@
<li>
- <p>Let <var title="">message clone</var> be the result of
- obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
- map</var> as the <i>transfer map</i>. If this throws an exception,
- then throw that exception and abort these steps.</p>
+ <p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
+ clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
+ as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
+ these steps.</p>
</li>
<li>
- <p>If the method was invoked with a third argument <var title="">transfer</var>, run these substeps:</p>
+ <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
+ substeps:</p>
<ol><li>
- <p>Let <var title="">new owner</var> be the <code>Window</code>
- object on which the method was invoked.</p>
+ <p>Let <var title="">new owner</var> be the <code>Window</code> object on which the method was
+ invoked.</p>
[692 lines skipped]
Received on Friday, 18 October 2013 06:28:22 UTC