Skip to content

Commit

Permalink
Add postMessage overrides that take options
Browse files Browse the repository at this point in the history 
Closes #3799.
  • Loading branch information
@dtapuska @domenic
dtapuska authored and domenic committed Oct 26, 2018
1 parent 95e72ce commit c501dd8
Showing 1 changed file with 120 additions and 32 deletions.
152 changes: 120 additions & 32 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78126,9 +78126,13 @@ interface <dfn data-export="" data-dfn-type="interface">Window</dfn> : <span>Eve
void <span data-x="dom-print">print</span>();

void <span data-x="dom-window-postMessage">postMessage</span>(any message, USVString targetOrigin, optional sequence&lt;<span data-x="idl-object">object</span>&gt; transfer = []);
void <span data-x="dom-window-postMessage-options">postMessage</span>(any message, optional <span>WindowPostMessageOptions</span> options);
};
<span>Window</span> includes <span>GlobalEventHandlers</span>;
<span>Window</span> includes <span>WindowEventHandlers</span>;</code></pre>

dictionary <dfn>WindowPostMessageOptions</dfn> : <span>PostMessageOptions</span> {
USVString targetOrigin = "/";
};</code></pre>

<!-- for more features to add here, look here:
http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_window.asp
Expand Down Expand Up @@ -95977,31 +95981,38 @@ function receiver(e) {
<h4>Posting messages</h4>

<dl class="domintro">

<dt><var>window</var> . <code subdfn data-x="dom-window-postMessage">postMessage</code>(<var>message</var>, <var>targetOrigin</var> [, <var>transfer</var> ] )</dt>
<dt><var>window</var> . <code subdfn data-x="dom-window-postMessage">postMessage</code>(<var>message</var> [, <var>options</var> ] )</dt>

<dd>

<p>Posts a message to the given window. Messages can be structured objects, e.g. nested objects
and arrays, can contain JavaScript values (strings, numbers, <code>Date</code>
objects, etc), and can contain certain data objects such as <code>File</code> <code>Blob</code>,
<code>FileList</code>, and <code data-x="idl-ArrayBuffer">ArrayBuffer</code> objects.</p>

<p>Objects listed in <var>transfer</var> are transferred, not just cloned, meaning that
they are no longer usable on the sending side.</p>
<p>Objects listed in the <code data-x="">transfer</code> member of <var>options</var> are
transferred, not just cloned, meaning that they are no longer usable on the sending side.</p>

<p>A target origin can be specified using the <code data-x="">targetOrigin</code> member of
<var>options</var>. If not provided, it defaults to "<code data-x="">/</code>". This default
restricts the message to same-origin targets only.</p>

<p>If the origin of the target window doesn't match the given origin, the message is discarded,
to avoid information leakage. To send the message to the target regardless of origin, set the
target origin to "<code data-x="">*</code>". To restrict the message to same-origin targets only,
without needing to explicitly state the origin, set the target origin to "<code
data-x="">/</code>".</p>
<p>If the origin of the target window doesn't match the given target origin, the message is
discarded, to avoid information leakage. To send the message to the target regardless of origin,
set the target origin to "<code data-x="">*</code>".</p>

<p>Throws a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code> if
<var>transfer</var> array contains duplicate objects or if <var>message</var> could not be
cloned.</p>

</dd>

<dt><var>window</var> . <code data-x="dom-window-postMessage">postMessage</code>(<var>message</var>, <var>targetOrigin</var> [, <var>transfer</var> ] )</dt>

<dd><p>This is an alternate version of <code
data-x="dom-window-postMessage-options">postMessage()</code> where the target origin is specified
as a parameter. Calling <code data-x="">window.postMessage(message, target, transfer)</code> is
equivalent to <code
data-x="">window.postMessage(message, {targetOrigin, transfer})</code>.</p></dd>
</dl>

<p class="note">When posting a message to a <code>Window</code> of a <span>browsing context</span>
Expand All @@ -96015,14 +96026,11 @@ function receiver(e) {

<div w-nodev>

<p>The <dfn><code data-x="dom-window-postMessage">postMessage(<var>message</var>,
<var>targetOrigin</var>, <var>transfer</var>)</code></dfn> method, when invoked on a
<code>Window</code> object must run the following steps:</p>
<p>The <dfn>window post message steps</dfn>, given a <var>targetWindow</var>, <var>message</var>,
and <var>options</var>, are as follows:</p>

<ol> <!-- a lot of this is similar or identical to port.postMessage -->

<li><p>Let <var>targetWindow</var> be this <code>Window</code> object.</p>

<li><p>Let <var>targetRealm</var> be <var>targetWindow</var>'s <span
data-x="concept-global-object-realm">Realm</span>.</p></li>

Expand All @@ -96032,6 +96040,9 @@ function receiver(e) {
window, in same-origin cases. See discussion at
https://github.com/whatwg/html/issues/1542#issuecomment-233502636 -->

<li><p>Let <var>targetOrigin</var> be <var>options</var>["<code
data-x="">targetOrigin</code>"].</p></li>

<li><p>If <var>targetOrigin</var> is a single U+002F SOLIDUS character (/), then set
<var>targetOrigin</var> to <var>incumbentSettings</var>'s <span
data-x="concept-settings-object-origin">origin</span>.</p>
Expand All @@ -96052,6 +96063,8 @@ function receiver(e) {
</ol>
</li>

<li><p>Let <var>transfer</var> be <var>options</var>["<code data-x="">transfer</code>"].</p></li>

<li><p>Let <var>serializeWithTransferResult</var> be
<span>StructuredSerializeWithTransfer</span>(<var>message</var>, <var>transfer</var>). Rethrow
any exceptions.</p></li>
Expand All @@ -96070,7 +96083,7 @@ function receiver(e) {
origin">serialization</span> of <var>incumbentSettings</var>'s <span
data-x="concept-settings-object-origin">origin</span>.</p></li>

<li><p>Let <var>source</var> be the <code>WindowProxy</code> object's corresponding to
<li><p>Let <var>source</var> be the <code>WindowProxy</code> object corresponding to
<var>incumbentSettings</var>'s <span data-x="concept-settings-object-global">global
object</span> (a <code>Window</code> object).</p></li>

Expand Down Expand Up @@ -96105,6 +96118,30 @@ function receiver(e) {
</li>
</ol>

<p>The <dfn><code data-x="dom-window-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> method, when invoked on a
<code>Window</code> object, must run the following steps:</p>
<ol>
<li><p>Let <var>targetWindow</var> be this <code>Window</code> object.</p></li>

<li><p>Run the <span>window post message steps</span> providing <var>targetWindow</var>,
<var>message</var>, and <var>options</var>.</p></li>
</ol>

<p>The <dfn><code data-x="dom-window-postMessage">postMessage(<var>message</var>,
<var>targetOrigin</var>, <var>transfer</var>)</code></dfn> method, when invoked on a
<code>Window</code> object, must run the following steps:</p>

<ol>
<li><p>Let <var>targetWindow</var> be this <code>Window</code> object.</p></li>

<li><p>Let <var>options</var> be «[ "<code data-x="">targetOrigin</code>" →
<var>targetOrigin</var>, "<code data-x="">transfer</code>" → <var>transfer</var> ]».</p></li>

<li><p>Run the <span>window post message steps</span> providing <var>targetWindow</var>,
<var>message</var>, and <var>options</var>.</p></li>
</ol>

</div>


Expand Down Expand Up @@ -96380,16 +96417,22 @@ interface <dfn>MessageChannel</dfn> {
<pre><code class="idl" data-x="">[Exposed=(Window,Worker,AudioWorklet), <span>Transferable</span>]
interface <dfn>MessagePort</dfn> : <span>EventTarget</span> {
void <span data-x="dom-MessagePort-postMessage">postMessage</span>(any message, optional sequence&lt;<span data-x="idl-object">object</span>&gt; transfer = []);
void <span data-x="dom-MessagePort-postMessage-options">postMessage</span>(any message, <span>PostMessageOptions</span> options);
void <span data-x="dom-MessagePort-start">start</span>();
void <span data-x="dom-MessagePort-close">close</span>();

// event handlers
attribute <span>EventHandler</span> <span data-x="handler-MessagePort-onmessage">onmessage</span>;
attribute <span>EventHandler</span> <span data-x="handler-MessagePort-onmessageerror">onmessageerror</span>;
};

dictionary <dfn>PostMessageOptions</dfn> {
sequence&lt;<span data-x="idl-object">object</span>&gt; transfer = [];
};</code></pre>

<dl class="domintro">
<dt><var>port</var> . <code subdfn data-x="dom-MessagePort-postMessage">postMessage</code>(<var>message</var> [, <var>transfer</var>] )</dt>
<dt><var>port</var> . <code subdfn data-x="dom-MessagePort-postMessage-options">postMessage</code>(<var>message</var> [, { <code data-x="">transfer</code> }] )</dt>
<dd>
<p>Posts a message through the channel. Objects listed in <var>transfer</var> are
transferred, not just cloned, meaning that they are no longer usable on the sending side.</p>
Expand Down Expand Up @@ -96541,13 +96584,11 @@ interface <dfn>MessagePort</dfn> : <span>EventTarget</span> {

<hr>

<p>The <dfn><code data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>,
<var>transfer</var>)</code></dfn> method, when invoked on a <code>MessagePort</code> object, must
run the following steps:</p>
<p>The <dfn>message port post message steps</dfn>, given a <var>targetPort</var>, <var>message</var>
and <var>options</var> are as follows:</p>

<ol> <!-- a lot of this is similar or identical to window.postMessage -->
<li><p>Let <var>targetPort</var> be the port with which this <code>MessagePort</code> is
entangled, if any; otherwise let it be null.</p></li>
<ol> <!-- a lot of this is similar or identical to the window post message steps -->
<li><p>Let <var>transfer</var> be <var>options</var>["<code data-x="">transfer</code>"].</p></li>

<li><p>If <var>transfer</var> <span data-x="list contains">contains</span> this
<code>MessagePort</code>, then throw a <span>"<code>DataCloneError</code>"</span>
Expand Down Expand Up @@ -96614,6 +96655,33 @@ interface <dfn>MessagePort</dfn> : <span>EventTarget</span> {
</li>
</ol>

<p>The <dfn><code data-x="dom-MessagePort-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> method, when invoked on a <code>MessagePort</code> object must
run the following steps:</p>

<ol>
<li><p>Let <var>targetPort</var> be the port with which this <code>MessagePort</code> is
entangled, if any; otherwise let it be null.</p></li>

<li><p>Run the <span>message port post message steps</span> providing <var>targetPort</var>,
<var>message</var> and <var>options</var>.</p></li>
</ol>

<p>The <dfn><code data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>,
<var>transfer</var>)</code></dfn> method, when invoked on a <code>MessagePort</code> object
must run the following steps:</p>

<ol>
<li><p>Let <var>targetPort</var> be the port with which this <code>MessagePort</code> is
entangled, if any; otherwise let it be null.</p></li>

<li><p>Let <var>options</var> be «[ "<code data-x="">transfer</code>" → <var>transfer</var>
]».</p></li>

<li><p>Run the <span>message port post message steps</span> providing <var>targetPort</var>,
<var>message</var> and <var>options</var>.</p></li>
</ol>

<hr>

<p>The <dfn><code data-x="dom-MessagePort-start">start()</code></dfn> method, when invoked, must
Expand Down Expand Up @@ -97508,6 +97576,7 @@ interface <dfn>DedicatedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span>
[Replaceable] readonly attribute DOMString <span data-x="dom-DedicatedWorkerGlobalScope-name">name</span>;

void <span data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</span>(any message, optional sequence&lt;<span data-x="idl-object">object</span>&gt; transfer = []);
void <span data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(any message, <span>PostMessageOptions</span> options);

void <span data-x="dom-DedicatedWorkerGlobalScope-close">close</span>();

Expand All @@ -97532,6 +97601,9 @@ interface <dfn>DedicatedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span>
<dt><var>dedicatedWorkerGlobal</var> . <code subdfn
data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</code>(<var>message</var> [,
<var>transfer</var> ])</dt>
<dt><var>dedicatedWorkerGlobal</var> . <code subdfn
data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</code>(<var>message</var>
[, { <code data-x="">transfer</code> } ])</dt>
<dd>Clones <var>message</var> and transmits it to the <code>Worker</code> object associated with
<var>dedicatedWorkerGlobal</var>. <var>transfer</var> can be passed as a list of objects that are
to be transferred rather than cloned.</dd>
Expand All @@ -97548,10 +97620,16 @@ interface <dfn>DedicatedWorkerGlobalScope</dfn> : <span>WorkerGlobalScope</span>
data-x="concept-WorkerGlobalScope-name">name</span>. Its value represents the name given to the
worker using the <code>Worker</code> constructor, used primarily for debugging purposes.</p>

<p>The <dfn><code data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage()</code></dfn>
method on <code>DedicatedWorkerGlobalScope</code> objects must act as if, when invoked, it
immediately invoked <span data-x="dom-MessagePort-postMessage">the method of the same name</span>
on the port, with the same arguments, and returned the same return value.</p>
<p>The <dfn><code
data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage(<var>message</var>,
<var>transfer</var>)</code></dfn> and <dfn><code
data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> methods on <code>DedicatedWorkerGlobalScope</code> objects
act as if, when invoked, it immediately invoked the respective <code
data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>, <var>transfer</var>)</code>
and <code data-x="dom-MessagePort-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code> on the port, with the same arguments, and returned the same return
value.</p>

<p>To <dfn data-export="">close a worker</dfn>, given a <var>workerGlobal</var>, run these
steps:</p>
Expand Down Expand Up @@ -98243,6 +98321,7 @@ interface <dfn>Worker</dfn> : <span>EventTarget</span> {
void <span data-x="dom-Worker-terminate">terminate</span>();

void <span data-x="dom-Worker-postMessage">postMessage</span>(any message, optional sequence&lt;<span data-x="idl-object">object</span>&gt; transfer = []);
void <span data-x="dom-Worker-postMessage-options">postMessage</span>(any message, <span>PostMessageOptions</span> options);
attribute <span>EventHandler</span> <span data-x="handler-Worker-onmessage">onmessage</span>;
attribute <span>EventHandler</span> <span data-x="handler-Worker-onmessageerror">onmessageerror</span>;
};
Expand Down Expand Up @@ -98271,7 +98350,11 @@ enum <dfn>WorkerType</dfn> { "classic", "module" };
<dt><var>worker</var> . <code subdfn data-x="dom-Worker-terminate">terminate</code>()</dt>
<dd>Aborts <var>worker</var>'s associated global environment.</dd>

<dt><var>worker</var> . <code subdfn data-x="dom-Worker-postMessage">postMessage</code>(<var>message</var> [, <var>transfer</var> ])
<dt><var>worker</var> . <code subdfn
data-x="dom-Worker-postMessage">postMessage</code>(<var>message</var> [, <var>transfer</var> ] )
<dt><var>worker</var> . <code subdfn
data-x="dom-Worker-postMessage-options">postMessage</code>(<var>message</var> [, { <code
data-x="">transfer</code> } ] )
<dd>Clones <var>message</var> and transmits it to <var>worker</var>'s global environment.
<var>transfer</var> can be passed as a list of objects that are to be transferred rather than
cloned.</dd>
Expand All @@ -98290,10 +98373,15 @@ enum <dfn>WorkerType</dfn> { "classic", "module" };
<p>All messages received by that port must immediately be retargeted at the <code>Worker</code>
object.</p>

<p>The <dfn><code data-x="dom-Worker-postMessage">postMessage()</code></dfn> method on
<code>Worker</code> objects must act as if, when invoked, it immediately invoked <span
data-x="dom-MessagePort-postMessage">the method of the same name</span> on the port, with the same
arguments, and returned the same return value.</p>
<p>The <dfn><code data-x="dom-Worker-postMessage">postMessage(<var>message</var>,
<var>transfer</var>)</code></dfn> and <dfn><code
data-x="dom-Worker-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code></dfn> methods on <code>Worker</code> objects act as if, when invoked,
they immediately invoked the respective <code
data-x="dom-MessagePort-postMessage">postMessage(<var>message</var>, <var>transfer</var>)</code>
and <code data-x="dom-MessagePort-postMessage-options">postMessage(<var>message</var>,
<var>options</var>)</code> on the port, with the same arguments, and returned the same return
value.</p>

</div>

Expand Down

0 comments on commit c501dd8

Please sign in to comment.