[html5] r1874 - [] (0) Define the three-argument form of postMessage().
whatwg at whatwg.org
whatwg at whatwg.org
Tue Jul 15 03:36:29 PDT 2008
Author: ianh
Date: 2008-07-15 03:36:28 -0700 (Tue, 15 Jul 2008)
New Revision: 1874
Modified:
index
source
Log:
[] (0) Define the three-argument form of postMessage().
Modified: index
===================================================================
--- index 2008-07-15 10:06:47 UTC (rev 1873)
+++ index 2008-07-15 10:36:28 UTC (rev 1874)
@@ -1614,14 +1614,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
@@ -6610,7 +6625,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
@@ -6659,7 +6674,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
@@ -6669,13 +6684,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="#refsRFC2109">[RFC2109]</a> <a href="#refsRFC2965">[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="#refsRFC2109">[RFC2109]</a> <a
+ href="#refsRFC2965">[RFC2965]</a>
<p class=note>Since the <code title=dom-document-cookie><a
href="#cookie0">cookie</a></code> attribute is accessible across frames,
@@ -22240,13 +22256,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
@@ -30272,8 +30288,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>;
@@ -30348,7 +30364,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
@@ -30361,9 +30377,13 @@
<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
<li>The <code title=dom-XXX4><a href="#xxx4index">XXX4</a></code> method
@@ -30909,7 +30929,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="#refsRFC3490">[RFC3490]</a></p>
<li>
@@ -30921,12 +30941,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>
@@ -31059,7 +31079,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
@@ -32257,7 +32277,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
@@ -33692,7 +33712,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.
@@ -34094,7 +34114,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.
@@ -34104,7 +34124,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>
@@ -34333,7 +34353,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
@@ -35696,7 +35716,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).
@@ -42202,13 +42222,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>
@@ -42219,7 +42308,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>
@@ -42248,7 +42337,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
@@ -42273,67 +42362,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>
@@ -42402,8 +42527,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
@@ -42541,7 +42666,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:
Modified: source
===================================================================
--- source 2008-07-15 10:06:47 UTC (rev 1873)
+++ source 2008-07-15 10:36:28 UTC (rev 1874)
@@ -27778,8 +27778,8 @@
<span>Window</span> <span title="dom-open">open</span>(in DOMString url, in DOMString target, in DOMString features, in DOMString replace);
// <span>cross-document messaging</span>
- void <span title="dom-window-postMessage">postMessage</span>(in DOMString message, in DOMString targetOrigin);
- void <span title="dom-window-postMessage">postMessage</span>(in DOMString message, in <span>MessagePort</span> messagePort, in DOMString targetOrigin);
+ void <span title="dom-window-postMessage-2">postMessage</span>(in DOMString message, in DOMString targetOrigin);
+ void <span title="dom-window-postMessage-3">postMessage</span>(in DOMString message, in <span>MessagePort</span> messagePort, in DOMString targetOrigin);
// <span>event handler DOM attributes</span>
attribute <span>EventListener</span> <span title="handler-onabort">onabort</span>;
@@ -27866,9 +27866,12 @@
<li>The <code title="dom-location">location</code> object
- <li>The <code title="dom-window-postMessage">postMessage()</code>
- methods
+ <li>The <code title="dom-window-postMessage-2">postMessage()</code>
+ method with two arguments
+ <li>The <code title="dom-window-postMessage-3">postMessage()</code>
+ method with three arguments
+
<li>The <code title="dom-window-frames">frames</code> attribute
<li>The <code title="dom-XXX4">XXX4</code> method
@@ -39859,13 +39862,90 @@
attacks.</p>
- <h4>Processing model</h4>
+ <h4>Introduction</h4>
+ <p><em>This section is non-normative.</em></p>
+
+ <div class="example">
+
+ <p>For example, if document A contains an <code>object</code>
+ element that contains document B, and script in document A calls
+ <code title="dom-window-postMessage-2">postMessage()</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>Security</h4>
+
+ <h5>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>
+
+ <p>Authors should check the <code
+ title="dom-MessageEvent-origin">origin</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>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>
+
+
+ <h5>User agents</h5>
+
+ <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>
+
+
+ <h4>Posting text</h4>
+
<p>When a script invokes the <dfn
- 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>Window</code> object, the user agent must follow these steps:
+ title="">targetOrigin</var>)</code></dfn> method (with only two
+ arguments) on a <code>Window</code> object, the user agent must
+ follow these steps:
<ol>
@@ -39882,7 +39962,7 @@
<li>
<p>Return from the <code
- title="dom-window-postMessage">postMessage()</code> method, but
+ title="dom-window-postMessage-2">postMessage()</code> method, but
asynchronously continue running these steps.</p>
</li>
@@ -39917,7 +39997,7 @@
cancelable, and has no default action. The <code
title="dom-MessageEvent-data">data</code> attribute must be set to
the value passed as the <var title="">message</var> argument to
- the <code title="dom-window-postMessage">postMessage()</code>
+ the <code title="dom-window-postMessage-2">postMessage()</code>
method, the <code title="dom-MessageEvent-origin">origin</code>
attribute must be set to the <span title="Unicode serialization of
an origin">Unicode serialization</span> of the <span>origin</span>
@@ -39943,70 +40023,127 @@
</ol>
- <p class="warning">Authors should check the <code
- title="dom-MessageEvent-origin">origin</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 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>
+ <h4>Posting message ports</h4>
- <div class="example">
+ <p>When a script invokes the <dfn
+ 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>Window</code> object, the user agent must
+ follow these steps:
- <p>For example, if document A contains an <code>object</code>
- element that contains document B, and script in document A calls
- <code title="dom-window-postMessage">postMessage()</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>
- <pre>var o = document.getElementsByTagName('object')[0];
-o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
+ <!-- EXCEPT WHERE NOTED, THESE STEPS ARE IDENTICAL TO THE PREVIOUS SECTION -->
+ <!-- one exception is the use of -3 instead of -2 in the xrefs -->
- <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>
- <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>If the value of the <var title="">targetOrigin</var> argument
+ is not a single U+002A ASTERISK character ("*"), and <span
+ title="parse a url">parsing</span> it as a <span>URL</span> fails,
+ then throw a <code>SYNTAX_ERR</code> exception and abort the
+ overall set of 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>
+ </li>
- </div>
+ <li> <!-- NEW STEP -->
- <p class="warning">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>Try to obtain a <var title="">new port</var> by <span
+ title="clone a port">cloning</span> the <var
+ title="">messagePort</var> argument with the <code>Window</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>
- <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>
+ </li>
- <p class="big-issue">postMessage() with a message port isn't yet
- defined</p>
+ <li>
+ <p>Return from the <code
+ title="dom-window-postMessage-3">postMessage()</code> method, but
+ asynchronously continue running these steps.</p>
+ </li>
+ <li>
+
+ <p>Wait for all scripts in the <span>unit of related browsing
+ contexts</span> to which the the <code>Window</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 -->
+
+ </li>
+
+ <li>
+
+ <p>If the <var title="">targetOrigin</var> argument has a value
+ other than a single literal U+002A ASTERISK character ("*"), and
+ the <span>active document</span> of the <span>browsing
+ context</span> of the <code>Window</code> object on which the
+ method was invoked does not have the <span>same origin</span> as
+ <var title="">targetOrigin</var>, then abort these steps
+ silently.</p>
+
+ </li>
+
+ <li>
+
+ <p>Create an event that uses the <code>MessageEvent</code>
+ interface, with the event name <code
+ title="event-message">message</code>, which does not bubble, is
+ cancelable, and has no default action. The <code
+ title="dom-MessageEvent-data">data</code> attribute must be set to
+ the value passed as the <var title="">message</var> argument to
+ the <code title="dom-window-postMessage-3">postMessage()</code>
+ method, the <code title="dom-MessageEvent-origin">origin</code>
+ attribute must be set to the <span title="Unicode serialization of
+ an origin">Unicode serialization</span> of the <span>origin</span>
+ of the script that invoked the method, and the <code
+ title="dom-MessageEvent-source">source</code> attribute must be
+ set to the <code>Window</code> object of the <span>default
+ view</span> of the <span>browsing context</span> for which the
+ <code>Document</code> object with which the script is associated
+ is the <span>active document</span><!--, 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. -->
+
+ </li>
+
+ <li> <!-- NEW STEP -->
+
+ <p>Let the <code
+ title="dom-MessageEvent-messagePort">messagePort</code> attribute
+ of the event be the <var title="">new port</var>.</p>
+
+ </li>
+
+ <li>
+
+ <p>Dispatch the event created in the previous step at the
+ <code>Window</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 -->
+
+ </li>
+
+ </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><dfn>Channel messaging</dfn></h3>
<h4>Introduction</h4>
More information about the Commit-Watchers
mailing list