HTML Standard Tracker

Diff (omit for latest revision)
Filter

Short URL: http://html5.org/r/2533

File a bug

SVNBugCommentTime (UTC)
2533Add structured data support to postMessage().2008-12-16 04:46
Index: source
===================================================================
--- source	(revision 2532)
+++ source	(revision 2533)
@@ -5517,6 +5517,107 @@
   underlying string representation.</p>
 
 
+  <h4>Safe passing of structured data</h4>
+
+  <p>When a user agent is required to obtain a <dfn>structured
+  clone</dfn> of an object, it must run the following algorithm, which
+  either returns a separate object, or returns an exception.</p>
+
+  <ol>
+
+   <li><p>Let <var title="">input</var> be the object being
+   cloned.</p></li>
+
+   <li><p>Let <var title="">memory</var> be a list of objects,
+   initially empty. (This is used to catch cycles.)</p></li>
+
+   <li><p>Let <var title="">output</var> be the object resulting from
+   calling the <span>internal structured cloning algorithm</span> with
+   <var title="">input</var> and <var title="">memory</var>.</p></li>
+
+   <li><p>Return <var title="">output</var>.</p></li>
+
+  </ol>
+
+  <p>The <dfn>internal structured cloning algorithm</dfn> is always
+  called with two arguments, <var title="">input</var> and <var
+  title="">memory</var>, and its behavior depends on the type of <var
+  title="">input</var>, as follows:</p>
+
+  <dl class="switch">
+
+   <dt>If <var title="">input</var> is the undefined value</dt>
+
+   <dd><p>Return the undefined value.</p></dd>
+
+   <dt>If <var title="">input</var> is the null value</dt>
+
+   <dd><p>Return the null value.</p></dd>
+
+   <dt>If <var title="">input</var> is the false value</dt>
+
+   <dd><p>Return the false value.</p></dd>
+
+   <dt>If <var title="">input</var> is the true value</dt>
+
+   <dd><p>Return the true value.</p></dd>
+
+   <dt>If <var title="">input</var> is a Number object</dt>
+
+   <dd><p>Return a newly constructed Number object with the same value as <var title="">input</var>.</p></dd>
+
+   <dt>If <var title="">input</var> is a String object</dt>
+
+   <dd><p>Return a newly constructed String object with the same value as <var title="">input</var>.</p></dd>
+
+   <dt>If <var title="">input</var> is a Date object</dt>
+
+   <dd><p>Return a newly constructed Date object with the same value as <var title="">input</var>.</p></dd>
+
+   <dt>If <var title="">input</var> is a host object</dt>
+
+   <dd><p>Return the null value.</p></dd>
+
+   <dt>If <var title="">input</var> is an Array object</dt>
+   <dt>If <var title="">input</var> is an Object object</dt>
+
+   <dd>
+
+    <ol>
+
+     <li><p>If <var title="">input</var> is in <var
+     title="">memory</var>, then return a
+     <code>NOT_SUPPORTED_ERR</code> exception and abort the overall
+     <span>structured clone</span> algorithm.</p></li>
+
+     <li><p>Otherwise, let <var title="">new memory</var> be a list
+     consisting of the items in <var title="">memory</var> with the
+     addition of <var title="">input</var>.</p></li>
+
+     <li><p>Create a new object, <var title="">output</var>, of the
+     same type as <var title="">input</var>: either an Array or an
+     Object.</p></li>
+
+     <li><p>For each property in <var title="">input</var>, add a
+     corresponding property to <var title="">output</var> having the
+     same name, and having a value created from invoking the
+     <span>internal structured cloning algorithm</span> recursively
+     with the value of the property as the "<var title="">input</var>"
+     arguemnt and <var title="">new memory</var> as the "<var
+     title="">memory</var>" argument. The order of the properties in
+     the <var title="">input</var> and <var title="">output</var>
+     objects must be the same.</p></li>
+
+     <li><p>Return <var title="">output</var>.</p></li>
+
+    </ol>
+
+   </dd>
+
+  </dl>
+
+
+
   <h4>DOMStringMap</h4>
 
   <p>The <code>DOMStringMap</code> interface represents a set of
@@ -37262,8 +37363,8 @@
   void <span title="dom-showNotification">showNotification</span>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
 
   // <span>cross-document messaging</span>
-  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);
+  void <span title="dom-window-postMessage-2">postMessage</span>(in any message, in DOMString targetOrigin);
+  void <span title="dom-window-postMessage-3">postMessage</span>(in any 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>;
@@ -48804,13 +48905,13 @@
   <p>The following interface is defined for this event:</p>
 
   <pre class="idl">interface <dfn>MessageEvent</dfn> : Event {
-  readonly attribute DOMString <span title="dom-MessageEvent-data">data</span>;
+  readonly attribute any <span title="dom-MessageEvent-data">data</span>;
   readonly attribute DOMString <span title="dom-MessageEvent-origin">origin</span>;
   readonly attribute DOMString <span title="dom-MessageEvent-lastEventId">lastEventId</span>;
   readonly attribute <span>Window</span> <span title="dom-MessageEvent-source">source</span>;
   readonly attribute <span>MessagePort</span> <span title="dom-MessageEvent-messagePort">messagePort</span>;
-  void <span title="dom-MessageEvent-initMessageEvent">initMessageEvent</span>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg, in DOMString originArg, in DOMString lastEventIdArg, in Window sourceArg, in <span>MessagePort</span> messagePortArg);
-  void <span title="dom-MessageEvent-initMessageEventNS">initMessageEventNS</span>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg, in DOMString originArg, in DOMString lastEventIdArg, in Window sourceArg, in <span>MessagePort</span> messagePortArg);
+  void <span title="dom-MessageEvent-initMessageEvent">initMessageEvent</span>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any dataArg, in DOMString originArg, in DOMString lastEventIdArg, in Window sourceArg, in <span>MessagePort</span> messagePortArg);
+  void <span title="dom-MessageEvent-initMessageEventNS">initMessageEventNS</span>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any dataArg, in DOMString originArg, in DOMString lastEventIdArg, in Window sourceArg, in <span>MessagePort</span> messagePortArg);
 };</pre>
 
   <p>The <dfn
@@ -50463,7 +50564,7 @@
   careful to allow access to certain properties but not others.</p>
 
 
-  <h4>Posting text</h4>
+  <h4>Posting messages</h4>
 
   <p>When a script invokes the <dfn
   title="dom-window-postMessage-2"><code>postMessage(<var
@@ -50490,6 +50591,17 @@
 
    <li>
 
+    <p>Let <var title="">message clone</var> be the result of
+    obtaining a <span>structured clone</span> of the <var
+    title="">message</var> argument.</p>
+
+    <p>If doing this raised an exception, then raise that exception
+    and abort these steps.</p>
+
+   </li>
+
+   <li>
+
     <p>Return from the <code
     title="dom-window-postMessage-2">postMessage()</code> method, but
     asynchronously continue running these steps.</p>
@@ -50515,12 +50627,11 @@
     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-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>
-    of the script that invoked the method, and the <code
+    the value of <var title="">message clone</var>, 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
@@ -50545,7 +50656,7 @@
   </ol>
 
 
-  <h4>Posting message ports</h4>
+  <h4>Posting messages with message ports</h4>
 
   <p>When a script invokes the <dfn
   title="dom-window-postMessage-3"><code>postMessage(<var
@@ -50573,6 +50684,15 @@
 
    </li>
 
+   <li>
+
+    <p>Let <var title="">message clone</var> be the result of
+    obtaining a <span>structured clone</span> of the <var
+    title="">message</var> argument. If this returns an exception,
+    then throw that exception and abort these steps.</p>
+
+   </li>
+
    <li> <!-- NEW STEP -->
 
     <p>If the <var title="">messagePort</var> argument is null, then
@@ -50621,12 +50741,11 @@
     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
+    the value of <var title="">message clone</var>, 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
@@ -50668,15 +50787,8 @@
   confused with the 'port' step. -->
 
 
-  <h4>Posting structured data</h4>
 
-  <p class="XXX">People often request the ability to send
-  name/value pairs, arrays, and numbers using postMessage() instead of
-  just strings.</p>
 
-
-
-
   <h3><dfn>Channel messaging</dfn></h3>
 
   <h4>Introduction</h4>
@@ -50741,8 +50853,8 @@
 
   <pre class="idl">interface <dfn>MessagePort</dfn> {
   readonly attribute boolean <span title="dom-MessagePort-active">active</span>;
-  void <span title="dom-MessagePort-postMessage">postMessage</span>(in DOMString message);
-  void <span title="dom-MessagePort-postMessage">postMessage</span>(in DOMString message, in <span>MessagePort</span> messagePort);<!--
+  void <span title="dom-MessagePort-postMessage">postMessage</span>(in any message);
+  void <span title="dom-MessagePort-postMessage">postMessage</span>(in any message, in <span>MessagePort</span> messagePort);<!--
   <span>MessagePort</span> <span title="dom-MessagePort-startConversation">startConversation</span>(in DOMString message);-->
   void <span title="dom-MessagePort-start">start</span>();
   void <span title="dom-MessagePort-close">close</span>();
@@ -50857,6 +50969,11 @@
    notice. we don't return false because if the port is _about_
    to be closed, the message might not be listened for anyway. -->
 
+   <li><p>Let <var title="">message clone</var> be the result of
+   obtaining a <span>structured clone</span> of the <var
+   title="">message</var> argument. If this returns an exception, then
+   throw that exception and abort these steps.</p></li>
+
    <li><p>Let <var title="">target port</var> be the port with which
    <var title="">source port</var> is entangled.</p></li>
 
@@ -50866,8 +50983,8 @@
    cancelable, and has no default action.</p></li>
 
    <li><p>Let the <code title="dom-MessageEvent-data">data</code>
-   attribute of the event have the value of <var
-   title="">message</var>, the method's first argument.</p></li>
+   attribute of the event have the value of <var title="">message
+   clone</var>.</p></li>
 
    <li><p>If the method was called with a second argument <var
    title="">data port</var> and that argument isn't null, then run the
@@ -50902,9 +51019,6 @@
 
   </ol>
 
-  <p class="XXX">People often request the ability to send
-  name/value pairs, arrays, and numbers using postMessage() instead of
-  just strings.</p>
 <!--
   <hr>
 

|