- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 15 Jul 2008 10:36:36 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv24996
Modified Files:
Overview.html
Log Message:
Define the three-argument form of postMessage(). (whatwg r1874)
Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.1062
retrieving revision 1.1063
diff -u -d -r1.1062 -r1.1063
--- Overview.html 15 Jul 2008 10:06:52 -0000 1.1062
+++ Overview.html 15 Jul 2008 10:36:34 -0000 1.1063
@@ -1676,14 +1676,29 @@
<li><a href="#crossDocumentMessages"><span class=secno>7.4
</span>Cross-document messaging</a>
<ul class=toc>
- <li><a href="#processing4"><span class=secno>7.4.1 </span>Processing
- model</a>
+ <li><a href="#introduction5"><span class=secno>7.4.1
+ </span>Introduction</a>
+
+ <li><a href="#security9"><span class=secno>7.4.2 </span>Security</a>
+ <ul class=toc>
+ <li><a href="#authors"><span class=secno>7.4.2.1. </span>Authors</a>
+
+
+ <li><a href="#user-agents"><span class=secno>7.4.2.2. </span>User
+ agents</a>
+ </ul>
+
+ <li><a href="#posting"><span class=secno>7.4.3 </span>Posting text</a>
+
+
+ <li><a href="#posting0"><span class=secno>7.4.4 </span>Posting message
+ ports</a>
</ul>
<li><a href="#channel"><span class=secno>7.5 </span>Channel
messaging</a>
<ul class=toc>
- <li><a href="#introduction5"><span class=secno>7.5.1
+ <li><a href="#introduction6"><span class=secno>7.5.1
</span>Introduction</a>
<li><a href="#message"><span class=secno>7.5.2 </span>Message
@@ -6672,7 +6687,7 @@
<h4 id=security><span class=secno>3.2.2 </span>Security</h4>
- <p>User agents must raise a <a href="#security9">security exception</a>
+ <p>User agents must raise a <a href="#security10">security exception</a>
whenever any of the members of an <code><a
href="#htmldocument">HTMLDocument</a></code> object are accessed by
scripts whose <a href="#effective3">effective script origin</a> is not the
@@ -6721,7 +6736,7 @@
<p id=sandboxCookies>On getting, if the <a href="#sandboxed2">sandboxed
origin browsing context flag</a> is set on the <a
href="#browsing1">browsing context</a> of the document, the user agent
- must raise a <a href="#security9">security exception</a>. Otherwise, it
+ must raise a <a href="#security10">security exception</a>. Otherwise, it
must return the same string as the value of the <code
title="">Cookie</code> HTTP header it would include if fetching the
resource indicated by <span>the document's
@@ -6731,13 +6746,14 @@
<p>On setting, if the <a href="#sandboxed2">sandboxed origin browsing
context flag</a> is set on the <a href="#browsing1">browsing context</a>
- of the document, the user agent must raise a <a href="#security9">security
- exception</a>. Otherwise, the user agent must act as it would when
- processing cookies if it had just attempted to fetch <span>the document's
- address</span><!-- XXXDOCURL --> over HTTP, and had received a response
- with a <code>Set-Cookie</code> header whose value was the specified value,
- as per RFC 2109 sections 4.3.1, 4.3.2, and 4.3.3 or later specifications.
- <a href="#references">[RFC2109]</a> <a href="#references">[RFC2965]</a>
+ of the document, the user agent must raise a <a
+ href="#security10">security exception</a>. Otherwise, the user agent must
+ act as it would when processing cookies if it had just attempted to fetch
+ <span>the document's address</span><!-- XXXDOCURL --> over HTTP, and had
+ received a response with a <code>Set-Cookie</code> header whose value was
+ the specified value, as per RFC 2109 sections 4.3.1, 4.3.2, and 4.3.3 or
+ later specifications. <a href="#references">[RFC2109]</a> <a
+ href="#references">[RFC2965]</a>
<p class=note>Since the <code title=dom-document-cookie><a
href="#cookie0">cookie</a></code> attribute is accessible across frames,
@@ -22302,13 +22318,13 @@
href="#todataurl">toDataURL()</a></code> method of a <code><a
href="#canvas">canvas</a></code> element whose <i>origin-clean</i> flag is
set to false is called, the method must raise a <a
- href="#security9">security exception</a>.
+ href="#security10">security exception</a>.
<p>Whenever the <code title=dom-context-2d-getImageData><a
href="#getimagedata">getImageData()</a></code> method of the 2D context of
a <code><a href="#canvas">canvas</a></code> element whose
<i>origin-clean</i> flag is set to false is called with otherwise correct
- arguments, the method must raise a <a href="#security9">security
+ arguments, the method must raise a <a href="#security10">security
exception</a>.
<p class=note>Even resetting the canvas state by changing its <code
@@ -30334,8 +30350,8 @@
<a href="#window">Window</a> <a href="#open2" title=dom-open>open</a>(in DOMString url, in DOMString target, in DOMString features, in DOMString replace);
// <a href="#cross-document">cross-document messaging</a>
- void <a href="#postmessage" title=dom-window-postMessage>postMessage</a>(in DOMString message, in DOMString targetOrigin);
- void <a href="#postmessage" title=dom-window-postMessage>postMessage</a>(in DOMString message, in <a href="#messageport0">MessagePort</a> messagePort, in DOMString targetOrigin);
+ void <a href="#postmessage" title=dom-window-postMessage-2>postMessage</a>(in DOMString message, in DOMString targetOrigin);
+ void <a href="#postmessage0" title=dom-window-postMessage-3>postMessage</a>(in DOMString message, in <a href="#messageport0">MessagePort</a> messagePort, in DOMString targetOrigin);
// <a href="#event4">event handler DOM attributes</a>
attribute <span>EventListener</span> <a href="#onabort" title=handler-onabort>onabort</a>;
@@ -30410,7 +30426,7 @@
<h4 id=security3><span class=secno>5.2.1 </span>Security</h4>
- <p>User agents must raise a <a href="#security9">security exception</a>
+ <p>User agents must raise a <a href="#security10">security exception</a>
whenever any of the members of a <code><a href="#window">Window</a></code>
object are accessed by scripts whose <a href="#effective3">effective
script origin</a> is not the same as the <code><a
@@ -30423,8 +30439,12 @@
<li>The <code title=dom-location><a href="#location1">location</a></code>
object
- <li>The <code title=dom-window-postMessage><a
- href="#postmessage">postMessage()</a></code> methods
+ <li>The <code title=dom-window-postMessage-2><a
+ href="#postmessage">postMessage()</a></code> method with two arguments
+
+ <li>The <code title=dom-window-postMessage-3><a
+ href="#postmessage0">postMessage()</a></code> method with three arguments
+
<li>The <code title=dom-window-frames>frames</code> attribute
@@ -30971,7 +30991,7 @@
<p>If ToASCII fails to convert one of the components of the string, e.g.
because it is too long or because it contains invalid characters, then
- throw a <a href="#security9">security exception</a> and abort these
+ throw a <a href="#security10">security exception</a> and abort these
steps. <a href="#references">[RFC3490]</a></p>
<li>
@@ -30983,12 +31003,12 @@
<ol>
<li>
<p>If the current value is an IP address, throw a <a
- href="#security9">security exception</a> and abort these steps.</p>
+ href="#security10">security exception</a> and abort these steps.</p>
<li>
<p>If <var title="">new value</var>, prefixed by a U+002E FULL STOP
("."), does not exactly match the end of the current value, throw a <a
- href="#security9">security exception</a> and abort these steps.</p>
+ href="#security10">security exception</a> and abort these steps.</p>
</ol>
<li>
@@ -31121,7 +31141,7 @@
<h4 id=security4><span class=secno>5.4.2 </span>Security exceptions</h4>
- <p class=big-issue>Define <dfn id=security9>security exception</dfn>.</p>
+ <p class=big-issue>Define <dfn id=security10>security exception</dfn>.</p>
<!-- SCRIPT EXEC -->
<h4 id=javascript-protocol><span class=secno>5.4.3 </span><dfn
@@ -32319,7 +32339,7 @@
the user what the site in question is.</p>
</dl>
- <p>User agents should raise <a href="#security9" title="security
+ <p>User agents should raise <a href="#security10" title="security
exception">security exceptions</a> if the methods are called with <var
title="">protocol</var> or <var title="">mimeType</var> values that the UA
deems to be "privileged". For example, a site attempting to register a
@@ -33754,7 +33774,7 @@
<li>
<p>If <var title="">url</var> has a different <a href="#ltschemegt"
title=url-scheme><scheme></a> component than the manifest's URL,
- then raise a <a href="#security9">security exception</a>.
+ then raise a <a href="#security10">security exception</a>.
<li>
<p>Return, but do not abort these steps.
@@ -34156,7 +34176,7 @@
<li><a href="#resolve" title="resolve a url">Resolve</a> the value of
the third argument.
- <li>If that fails, raise a <a href="#security9">security exception</a>
+ <li>If that fails, raise a <a href="#security10">security exception</a>
and abort the <code title=dom-history-pushState><a
href="#pushstate">pushState()</a></code> steps.
@@ -34166,7 +34186,7 @@
href="#ltpathgt" title=url-path><path></a>, <a href="#ltquerygt"
title=url-query><query></a>, and <a href="#ltfragmentgt"
title=url-fragment><fragment></a> components, then raise a <a
- href="#security9">security exception</a> and abort the <code
+ href="#security10">security exception</a> and abort the <code
title=dom-history-pushState><a href="#pushstate">pushState()</a></code>
steps.
</ol>
@@ -34395,7 +34415,7 @@
<h5 id=security6><span class=secno>5.8.4.1. </span>Security</h5>
- <p>User agents must raise a <a href="#security9">security exception</a>
+ <p>User agents must raise a <a href="#security10">security exception</a>
whenever any of the members of a <code><a
href="#location2">Location</a></code> object are accessed by scripts whose
<a href="#effective3">effective script origin</a> is not the <a
@@ -35758,7 +35778,7 @@
database already exists but has a different version, then the method must
raise an <code>INVALID_STATE_ERR</code> exception.
- <p>The user agent may also raise a <a href="#security9">security
+ <p>The user agent may also raise a <a href="#security10">security
exception</a> in case the request violates a policy decision (e.g. if the
user agent is configured to not allow the page to open databases).
@@ -42264,13 +42284,82 @@
to communicate with each other regardless of their source domain, in a way
designed to not enable cross-site scripting attacks.
- <h4 id=processing4><span class=secno>7.4.1 </span>Processing model</h4>
+ <h4 id=introduction5><span class=secno>7.4.1 </span>Introduction</h4>
+
+ <p><em>This section is non-normative.</em>
+
+ <div class=example>
+ <p>For example, if document A contains an <code><a
+ href="#object">object</a></code> element that contains document B, and
+ script in document A calls <code title=dom-window-postMessage-2><a
+ href="#postmessage">postMessage()</a></code> on document B, then a
+ message event will be fired on that element, marked as originating from
+ document A. The script in document A might look like:</p>
+
+ <pre>var o = document.getElementsByTagName('object')[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>
+
+ <pre>document.addEventListener('message', receiver, false);
+function receiver(e) {
+ if (e.origin == 'http://example.com') {
+ if (e.data == 'Hello world') {
+ e.source.postMessage('Hello', e.origin);
+ } else {
+ alert(e.data);
+ }
+ }
+}</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>
+ </div>
+
+ <h4 id=security9><span class=secno>7.4.2 </span>Security</h4>
+
+ <h5 id=authors><span class=secno>7.4.2.1. </span>Authors</h5>
+
+ <p class=warning>Use of this API requires extra care to protect users from
+ hostile entities abusing a site for their own purposes.
+
+ <p>Authors should check the <code title=dom-MessageEvent-origin><a
+ href="#origin1">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>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.
+
+ <h5 id=user-agents><span class=secno>7.4.2.2. </span>User agents</h5>
+
+ <p>The integrity of this API is based on the inability for scripts of one
+ <a href="#origin0">origin</a> to post arbitrary events (using <code
+ title="">dispatchEvent()</code> or otherwise) to objects in other origins
+ (those that are not the <a href="#same-origin" title="same
+ origin">same</a>).
+
+ <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.
+
+ <h4 id=posting><span class=secno>7.4.3 </span>Posting text</h4>
<p>When a script invokes the <dfn id=postmessage
- title=dom-window-postMessage><code>postMessage(<var
+ title=dom-window-postMessage-2><code>postMessage(<var
title="">message</var>, <var title="">targetOrigin</var>)</code></dfn>
- method on a <code><a href="#window">Window</a></code> object, the user
- agent must follow these steps:
+ method (with only two arguments) on a <code><a
+ href="#window">Window</a></code> object, the user agent must follow these
+ steps:
<ol>
<li>
@@ -42281,7 +42370,7 @@
of steps.</p>
<li>
- <p>Return from the <code title=dom-window-postMessage><a
+ <p>Return from the <code title=dom-window-postMessage-2><a
href="#postmessage">postMessage()</a></code> method, but asynchronously
continue running these steps.</p>
@@ -42310,7 +42399,7 @@
<code title=dom-MessageEvent-data><a href="#data4">data</a></code>
attribute must be set to the value passed as the <var
title="">message</var> argument to the <code
- title=dom-window-postMessage><a
+ title=dom-window-postMessage-2><a
href="#postmessage">postMessage()</a></code> method, the <code
title=dom-MessageEvent-origin><a href="#origin1">origin</a></code>
attribute must be set to the <a href="#unicode" title="Unicode
@@ -42335,67 +42424,103 @@
<!-- XXX apply any body/window dispatch decisions here -->
</ol>
- <p class=warning>Authors should check the <code
- title=dom-MessageEvent-origin><a href="#origin1">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.
+ <h4 id=posting0><span class=secno>7.4.4 </span>Posting message ports</h4>
- <p class=warning>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>When a script invokes the <dfn id=postmessage0
+ 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
+ follow these steps:
- <div class=example>
- <p>For example, if document A contains an <code><a
- href="#object">object</a></code> element that contains document B, and
- script in document A calls <code title=dom-window-postMessage><a
- href="#postmessage">postMessage()</a></code> on document B, then a
- message event will be fired on that element, marked as originating from
- document A. The script in document A might look like:</p>
+ <ol><!-- EXCEPT WHERE NOTED, THESE STEPS ARE IDENTICAL TO THE PREVIOUS SECTION -->
+ <!-- one exception is the use of -3 instead of -2 in the xrefs -->
- <pre>var o = document.getElementsByTagName('object')[0];
-o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
+ <li>
+ <p>If the value of the <var title="">targetOrigin</var> argument is not a
+ single U+002A ASTERISK character ("*"), and <a href="#parse0"
+ title="parse a url">parsing</a> it as a <a href="#url">URL</a> fails,
+ then throw a <code>SYNTAX_ERR</code> exception and abort the overall set
+ of steps.</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>
+ <li> <!-- NEW STEP -->
+ <p>Try to obtain a <var title="">new port</var> by <a href="#clone"
+ title="clone a port">cloning</a> the <var title="">messagePort</var>
+ argument with the <code><a href="#window">Window</a></code> object on
+ which the method was invoked as the owner of the clone. If this returns
+ an exception, then throw that exception and abort these steps.</p>
- <pre>document.addEventListener('message', receiver, false);
-function receiver(e) {
- if (e.origin == 'http://example.com') {
- if (e.data == 'Hello world') {
- e.source.postMessage('Hello', e.origin);
- } else {
- alert(e.data);
- }
- }
-}</pre>
+ <li>
+ <p>Return from the <code title=dom-window-postMessage-3><a
+ href="#postmessage0">postMessage()</a></code> method, but asynchronously
+ continue running these steps.</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>
+ <li>
+ <p>Wait for all scripts in the <a href="#unit-of">unit of related
+ browsing contexts</a> to which the the <code><a
+ href="#window">Window</a></code> object on which the method was invoked
+ belongs to have finished executing any pending scripts.</p>
+ <!-- XXX define this in terms of the
+ event queue -->
- <p class=warning>The integrity of this API is based on the inability for
- scripts of one <a href="#origin0">origin</a> to post arbitrary events
- (using <code title="">dispatchEvent()</code> or otherwise) to objects in
- other origins (those that are not the <a href="#same-origin" title="same
- origin">same</a>).
+ <li>
+ <p>If the <var title="">targetOrigin</var> argument has a value other
+ than a single literal U+002A ASTERISK character ("*"), and the <a
+ href="#active">active document</a> of the <a href="#browsing1">browsing
+ context</a> of the <code><a href="#window">Window</a></code> object on
+ which the method was invoked does not have the <a
+ href="#same-origin">same origin</a> as <var title="">targetOrigin</var>,
+ then abort these steps silently.</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.
+ <li>
+ <p>Create an event that uses the <code><a
+ href="#messageevent">MessageEvent</a></code> interface, with the event
+ name <code title=event-message><a href="#message2">message</a></code>,
+ which does not bubble, is cancelable, and has no default action. The
+ <code title=dom-MessageEvent-data><a href="#data4">data</a></code>
+ attribute must be set to the value passed as the <var
+ title="">message</var> argument to the <code
+ title=dom-window-postMessage-3><a
+ href="#postmessage0">postMessage()</a></code> method, the <code
+ title=dom-MessageEvent-origin><a href="#origin1">origin</a></code>
+ attribute must be set to the <a href="#unicode" title="Unicode
+ serialization of an origin">Unicode serialization</a> of the <a
+ href="#origin0">origin</a> of the script that invoked the method, and
+ the <code title=dom-MessageEvent-source><a
+ href="#source3">source</a></code> attribute must be set to the <code><a
+ href="#window">Window</a></code> object of the <a
+ href="#default3">default view</a> of the <a href="#browsing1">browsing
+ context</a> for which the <code>Document</code> object with which the
+ script is associated is the <a href="#active">active
+ document</a><!--, if there is one, or null
+ otherwise-->.</p>
+ <!-- I think there always is one, because scripts
+ can't run and see a Window without that being the case. -->
+
- <p class=big-issue>postMessage() with a message port isn't yet defined
+ <li> <!-- NEW STEP -->
+ <p>Let the <code title=dom-MessageEvent-messagePort><a
+ href="#messageport">messagePort</a></code> attribute of the event be the
+ <var title="">new port</var>.</p>
+
+ <li>
+ <p>Dispatch the event created in the previous step at the <code><a
+ href="#window">Window</a></code> object on which the method was invoked.</p>
+ <!-- XXX define this in terms of the event queue -->
+ <!-- XXX apply any body/window dispatch decisions here -->
+ </ol>
+
+ <p class=note>These steps, with the exception of the second step and the
+ penultimate step, are identical to those in the previous section.</p>
+ <!-- XXX merge this section and the previous section when
+ implementations have shipped postMessage(). Anne asked that these
+ sections be kept separate so that implementors can avoid getting
+ confused with the 'port' step. -->
<h3 id=channel><span class=secno>7.5 </span><dfn id=channel0>Channel
messaging</dfn></h3>
- <h4 id=introduction5><span class=secno>7.5.1 </span>Introduction</h4>
+ <h4 id=introduction6><span class=secno>7.5.1 </span>Introduction</h4>
<p><em>This section is non-normative.</em>
@@ -42464,8 +42589,8 @@
<pre class=idl>interface <dfn id=messageport0>MessagePort</dfn> {
readonly attribute <a href="#window">Window</a> <a href="#ownerwindow" title=dom-MessagePort-ownerWindow>ownerWindow</a>;
readonly attribute boolean <a href="#active0" title=dom-MessagePort-active>active</a>;
- boolean <a href="#postmessage0" title=dom-MessagePort-postMessage>postMessage</a>(in DOMString message);
- boolean <a href="#postmessage0" title=dom-MessagePort-postMessage>postMessage</a>(in DOMString message, in <a href="#messageport0">MessagePort</a> messagePort);
+ boolean <a href="#postmessage1" title=dom-MessagePort-postMessage>postMessage</a>(in DOMString message);
+ boolean <a href="#postmessage1" title=dom-MessagePort-postMessage>postMessage</a>(in DOMString message, in <a href="#messageport0">MessagePort</a> messagePort);
void <a href="#close2" title=dom-MessagePort-close>close</a>();
// event handler attributes
@@ -42603,7 +42728,7 @@
<hr>
- <p>The <dfn id=postmessage0
+ <p>The <dfn id=postmessage1
title=dom-MessagePort-postMessage><code>postMessage()</code></dfn> method,
when called on a port <var title="">source port</var>, must cause the user
agent to run the following steps:
Received on Tuesday, 15 July 2008 10:37:14 UTC