- From: poot <cvsmail@w3.org>
- Date: Tue, 15 Jul 2008 19:40:33 +0900 (JST)
- To: public-html-diffs@w3.org
Define the three-argument form of postMessage(). (whatwg r1874) (changed
by: Ian Hickson)
Diffs for this change per section:
postMessage(message, targetOrigin)
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#postmessage
domain
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#domain
5.4.2 Security exceptions
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security4
7.5.1 Introduction
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#introduction6
7.4.2.2. User agents
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#user-agents
5.4.3 The javascript: protocol
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#javascript-protocol
script document context
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#script4
On getting, if the sandboxed origin browsing context flag is set on the browsing context of the document, the user agent must raise a security exception. Otherwise, it must return the same string as the value of the Cookie HTTP header it would include if fetching the resource indicated by the document's address over HTTP, as per RFC 2109 section 4.3.4 or later specifications. [RFC2109] [RFC2965]
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#sandboxCookies
HTMLDocument
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#htmldocument
active
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#active0
postMessage(message, messagePort, targetOrigin)
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#postmessage0
Window
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#window
list of message ports
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#list-of3
7.5 Channel messaging
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#channel
7.4.3 Posting text
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#posting
registerContentHandler()
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#registercontenthandler
security exception
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security10
Cross-document messaging
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#cross-document
7.4.1 Introduction
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#introduction5
7.4.2.1. Authors
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#authors
postMessage()
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#postmessage1
pushState(data, title, url)
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#pushstate
7.4.2 Security
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security9
5.8.4.1. Security
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security6
add(url)
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#addurl
openDatabase()
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#opendatabase
5.2.1 Security
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security3
4.7.11.3. Security with canvas elements
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security1
hash
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#hash0
3.2.2 Security
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#security
MessagePort
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#messageport0
7.4.4 Posting message ports
http://people.w3.org/mike/diffs/html5/spec/Overview.1.1063.html#posting0
Current content per affected section:
http://dev.w3.org/html5/spec/Overview.html#postmessage
http://dev.w3.org/html5/spec/Overview.html#domain
http://dev.w3.org/html5/spec/Overview.html#security4
http://dev.w3.org/html5/spec/Overview.html#introduction6
http://dev.w3.org/html5/spec/Overview.html#user-agents
http://dev.w3.org/html5/spec/Overview.html#javascript-protocol
http://dev.w3.org/html5/spec/Overview.html#script4
http://dev.w3.org/html5/spec/Overview.html#sandboxCookies
http://dev.w3.org/html5/spec/Overview.html#htmldocument
http://dev.w3.org/html5/spec/Overview.html#active0
http://dev.w3.org/html5/spec/Overview.html#postmessage0
http://dev.w3.org/html5/spec/Overview.html#window
http://dev.w3.org/html5/spec/Overview.html#list-of3
http://dev.w3.org/html5/spec/Overview.html#processing4
http://dev.w3.org/html5/spec/Overview.html#channel
http://dev.w3.org/html5/spec/Overview.html#posting
http://dev.w3.org/html5/spec/Overview.html#registercontenthandler
http://dev.w3.org/html5/spec/Overview.html#security10
http://dev.w3.org/html5/spec/Overview.html#cross-document
http://dev.w3.org/html5/spec/Overview.html#introduction5
http://dev.w3.org/html5/spec/Overview.html#authors
http://dev.w3.org/html5/spec/Overview.html#postmessage1
http://dev.w3.org/html5/spec/Overview.html#pushstate
http://dev.w3.org/html5/spec/Overview.html#security9
http://dev.w3.org/html5/spec/Overview.html#security6
http://dev.w3.org/html5/spec/Overview.html#addurl
http://dev.w3.org/html5/spec/Overview.html#opendatabase
http://dev.w3.org/html5/spec/Overview.html#security3
http://dev.w3.org/html5/spec/Overview.html#security1
http://dev.w3.org/html5/spec/Overview.html#hash0
http://dev.w3.org/html5/spec/Overview.html#security
http://dev.w3.org/html5/spec/Overview.html#messageport0
http://dev.w3.org/html5/spec/Overview.html#posting0
Previously published WD content per affected section:
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#postmessage
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#domain
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security4
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#introduction6
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#user-agents
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#javascript-protocol
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#script4
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#sandboxCookies
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#htmldocument
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#active0
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#postmessage0
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#window
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#list-of3
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#processing4
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#channel
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#posting
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#registercontenthandler
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security10
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#cross-document
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#introduction5
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#authors
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#postmessage1
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#pushstate
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security9
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security6
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#addurl
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#opendatabase
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security3
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security1
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#hash0
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#security
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#messageport0
http://www.w3.org/TR/2008/WD-html5-20080610/single-page/#posting0
Cumulative diff: http://people.w3.org/mike/diffs/html5/spec/Overview.diff.html
http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.1062&r2=1.1063&f=h
http://html5.org/tools/web-apps-tracker?from=1873&to=1874
===================================================================
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:56:35 UTC