Short URL: http://html5.org/r/2533
| SVN | Bug | Comment | Time (UTC) |
|---|---|---|---|
| 2533 | Add 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>