HTML Standard Tracker

Filter

File a bug

SVNBugCommentTime (UTC)
2533Add structured data support to postMessage().2008-12-16 04:46
@@ -5510,20 +5510,121 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
 
    <li>Return true.</li>
 
   </ol>
 
   <p>Objects implementing the <code>DOMTokenList</code> interface must
   <dfn title="dom-tokenlist-toString">stringify</dfn> to the object's
   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
   name-value pairs. When a <code>DOMStringMap</code> object is
   instanced, it is associated with three algorithms, one for getting
   values from names, one for setting names to certain values, and one
   for deleting names.</p>
 
   <p class="XXX">The names of the methods on this interface are
   temporary and will be fixed when the Web IDL / "Language Bindings
@@ -37255,22 +37356,22 @@ explain that only direct children of the <menu> matter
   DOMString <span title="dom-prompt">prompt</span>(in DOMString message);
   DOMString <span title="dom-prompt">prompt</span>(in DOMString message, in DOMString default);
   void <span title="dom-print">print</span>();
   any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url);
   any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments);<!--
   any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments, in DOMString features);-->
   void <span title="dom-showNotification">showNotification</span>(in DOMString title, in DOMString subtitle, in DOMString description);
   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>;
            attribute <span>EventListener</span> <span title="handler-onbeforeunload">onbeforeunload</span>;
            attribute <span>EventListener</span> <span title="handler-onblur">onblur</span>;
            attribute <span>EventListener</span> <span title="handler-onchange">onchange</span>;
            attribute <span>EventListener</span> <span title="handler-onclick">onclick</span>;
            attribute <span>EventListener</span> <span title="handler-oncontextmenu">oncontextmenu</span>;
            attribute <span>EventListener</span> <span title="handler-ondblclick">ondblclick</span>;
            attribute <span>EventListener</span> <span title="handler-ondrag">ondrag</span>;
@@ -48797,27 +48898,27 @@ XXX Once we resolve the style="" issue, address these:
   <h3>Event definitions</h3>
 
   <p>Messages in <span>server-sent events</span>, <span>Web
   sockets</span>, <span>cross-document messaging</span>, and
   <span>channel messaging</span> use the <dfn
   title="event-message"><code>message</code></dfn> event.</p>
 
   <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
   title="dom-MessageEvent-initMessageEvent"><code>initMessageEvent()</code></dfn>
   and <dfn
   title="dom-MessageEvent-initMessageEventNS"><code>initMessageEventNS()</code></dfn>
   methods must initialize the event in a manner analogous to the
   similarly-named methods in the DOM3 Events interfaces. <a
   href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
 
@@ -50456,21 +50557,21 @@ function receiver(e) {
   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>
+  <h4>Posting messages</h4>
 
   <p>When a script invokes the <dfn
   title="dom-window-postMessage-2"><code>postMessage(<var
   title="">message</var>, <var
   title="">targetOrigin</var>)</code></dfn> method (with only two
   arguments) on a <code>Window</code> object, the user agent must
   follow these steps:
 
   <ol>
 
@@ -50483,20 +50584,31 @@ function receiver(e) {
     <span>URL</span> with a <code
     title="url-host-specific">&lt;host-specific&gt;</code> component
     that is neither empty nor a single U+002F SOLIDUS character (/),
     then throw a <code>SYNTAX_ERR</code> exception and abort the
     overall set of steps.</p>
 
    </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.</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>
 
    </li>
 
    <li>
 
     <p>If the <var title="">targetOrigin</var> argument has a value
     other than a single literal U+002A ASTERISK character ("*"), and
@@ -50508,26 +50620,25 @@ function receiver(e) {
 
    </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-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
     <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>
 
@@ -50538,21 +50649,21 @@ function receiver(e) {
     method was invoked. The <span>task source</span> for this <span
     title="concept-task">task</span> is the <span>posted message task
     source</span>.</p>
     <!-- XXX apply any body/window dispatch decisions here -->
 
    </li>
 
   </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
   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:
 
   <ol>
 
@@ -50566,20 +50677,29 @@ function receiver(e) {
     title="parse a url">parsing</span> it as a <span>URL</span> fails,
     or <span title="resolve a url">resolving</span> it results in a
     <span>URL</span> with a <code
     title="url-host-specific">&lt;host-specific&gt;</code> component
     that is neither empty nor a single U+002F SOLIDUS character (/),
     then throw a <code>SYNTAX_ERR</code> exception and abort the
     overall set of steps.</p>
 
    </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
     act as if the method had just been <span
     title="dom-window-postMessage-2">called with two arguments</span>,
     <var title="">message</var> and <var
     title="">targetOrigin</var>.</p>
 
    </li>
 
@@ -50614,26 +50734,25 @@ function receiver(e) {
 
    </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
+    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
     <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>
 
@@ -50661,27 +50780,20 @@ function receiver(e) {
   <p class="note">These steps, with the exception of the second and
   third steps 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. -->
 
 
-  <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>
 
   <p><em>This section is non-normative.</em></p>
 
   <p class="XXX">An introduction to the channel and port
   APIs.</p>
@@ -50734,22 +50846,22 @@ interface <dfn>MessageChannel</dfn> {
   <code>MessageChannel</code> object was created.</p>
 
 
   <h4>Message ports</h4>
 
   <p>Each channel has two message ports. Data sent through one port is
   received by the other port, and vice versa.</p>
 
   <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>();
 
   // event handler attributes
            attribute <span>EventListener</span> <span title="handler-MessagePort-onmessage">onmessage</span>;
 };</pre>
 
   <p>Objects implementing the <code>MessagePort</code> interface must
   also implement the <code>EventTarget</code> interface.</p>
@@ -50850,31 +50962,36 @@ interface <dfn>MessageChannel</dfn> {
 
    <li><p>Let <var title="">data port</var> be the method's second
    argument, if any.</p></li>
 
    <li><p>If the <var title="">source port</var> is not entangled with
    another port, then return and abort these steps.</p></li>
    <!-- we don't raise an exception because this can happen moment's
    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>
 
    <li><p>Create an event that uses the <code>MessageEvent</code>
    interface, with the name <code
    title="event-message">message</code>, which does not bubble, is
    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
    following substeps:</p>
 
     <ol>
 
      <li><p>If the <var title="">data port</var> is the <var
      title="">source port</var> or the <var title="">target
      port</var>, then throw an <code>INVALID_ACCESS_ERR</code>
@@ -50895,23 +51012,20 @@ interface <dfn>MessageChannel</dfn> {
    </li>
 
    <li><p>Return from the method, but continue with these
    steps.</p></li>
 
    <li><p>Add the event to the <span>port message queue</span> of <var
    title="">target port</var>.</p></li>
 
   </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>
 
   <p>The <dfn
   title="dom-MessagePort-startConversation"><code>startConversation(<var
   title="">message</var>)</code></dfn> method is a convenience method
   that simplifies create a new <code>MessageChannel</code> and
   invoking <code
   title="dom-MessagePort-postMessage">postMessage()</code> with one of
   the new ports. When invoked on a port <var title="">source

|