[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