W3C home > Mailing lists > Public > public-html-commits@w3.org > July 2008

html5/spec Overview.html,1.1062,1.1063

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Tue, 15 Jul 2008 10:36:36 +0000
To: public-html-commits@w3.org
Message-Id: <E1KIhtc-0006Vz-W9@lionel-hutz.w3.org>

Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv24996

Modified Files:
	Overview.html 
Log Message:
Define the three-argument form of postMessage(). (whatwg r1874)

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

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 9 October 2008 20:32:58 GMT