Skip to content

Commit

Permalink
Add postMessage overloads that provide PostMessageOptions.
Browse files Browse the repository at this point in the history 
Fixes issue whatwg#3799
  • Loading branch information
@dtapuska @domenic
dtapuska authored and domenic committed Oct 26, 2018
1 parent 95e72ce commit 473195e
Showing 1 changed file with 118 additions and 29 deletions.
147 changes: 118 additions & 29 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 @@ -95978,29 +95982,37 @@ function receiver(e) {

<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 specific using 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>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>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 restricts
the message to same-origin targets only.</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</code>(message, target,
transfer) is equivalent to <code data-x="">window.postMessage</code>(message, {targetOrigin:
targetOrigin, transfer: transfer}).</p>

</dd>

</dl>

Expand All @@ -96015,14 +96027,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 +96041,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 the value of <var>options</var>'s <code
data-x="">targetOrigin</code> member.</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 +96064,9 @@ function receiver(e) {
</ol>
</li>

<li><p>Let <var>transfer</var> be the value of <var>options</var>'s <code
data-x="">transfer</code> member.</p></li>

<li><p>Let <var>serializeWithTransferResult</var> be
<span>StructuredSerializeWithTransfer</span>(<var>message</var>, <var>transfer</var>). Rethrow
any exceptions.</p></li>
Expand Down Expand Up @@ -96105,6 +96120,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 «[ "<var>targetOrigin</var>" → <var>targetOrigin</var>,
"<var>transfer</var>" → <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 +96419,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> [, <var>options</var>] )</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 +96586,12 @@ 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>
<li><p>Let <var>transfer</var> be the value of <var>options</var>'s <code
data-x="">transfer</code> member.</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 @@ -96616,6 +96660,35 @@ interface <dfn>MessagePort</dfn> : <span>EventTarget</span> {

<hr>

<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>

<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>

<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 «[ "<var>transfer</var>" → <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
enable this <code>MessagePort</code> object's <span>port message queue</span>, if it is not
already enabled.</p>
Expand Down Expand Up @@ -97508,6 +97581,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 +97606,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> [,
<var>options</var> ])</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 +97625,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 <span
data-x="dom-MessagePort-postMessage">postMessage(<var>message</var> [, <var>transfer</var>]
)</span> 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 +98326,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 +98355,8 @@ 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> [, <var>options</var> ] )
<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 +98375,14 @@ 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, 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>

</div>

Expand Down

0 comments on commit 473195e

Please sign in to comment.