HTML — 通信

9.3.1. 序論

var %o = document.getElementsByTagName('iframe')[0];
%o.contentWindow.postMessage('Hello world', 'https://b.example.org/');

window.addEventListener('message', receiver, false);
function receiver(%e) {
  if (%e.origin == 'https://example.com') {
    if (%e.data == 'Hello world') {
      %e.source.postMessage('Hello', %e.origin);
    } else {
      alert(%e.data);
    }
  }
}

9.3.2. ~security

9.3.3. ~messageの投函-法

%window.`~postMessageO(message [, options ])$m

%message を %window へ投函する。 %message は有構造~objにもなり得る。 例えば、 次に挙げるものを包含できる ⇒＃ 入子な~objや配列／ ~JS値（ `string^jT, `number^jT, `Date$jT ~obj, 等々）／ ある種の~data~obj（ `File$I, `Blob$I, `FileList$I, `ArrayBuffer$I など） ◎ Posts a message to the given window. Messages can be structured objects, e.g. nested objects and arrays, can contain JavaScript values (strings, numbers, Date objects, etc.), and can contain certain data objects such as File Blob, FileList, and ArrayBuffer objects.

%options の `transfer$m ~member内に~listされた~objは、 ~cloneされるのみならず，転送される — すなわち、 それ以降，それらは 送信-側からは利用-不能になる。 ◎ Objects listed in the transfer member of options are transferred, not just cloned, meaning that they are no longer usable on the sending side.

%options の `targetOrigin$m ~memberを利用して，宛先~生成元を指定できる。 供されない場合の既定は `/^l になる — この既定は、 %message の宛先を同一-生成元のみに制約する。 ◎ A target origin can be specified using the targetOrigin member of options. If not provided, it defaults to "/". This default restricts the message to same-origin targets only.

宛先 %window の生成元が宛先~生成元に合致しない場合、 情報~漏洩eを避けるため， %message は破棄される。 生成元に関わらず %message を宛先へ送信するためには、 宛先~生成元を `*^l に設定する。 ◎ 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 "*".

次のいずれかに該当する場合、 `DataCloneError$E が投出される ⇒＃ %transfer 配列が同じ~objを重複して包含している／ %message を~cloneできなかった ◎ Throws a "DataCloneError" DOMException if transfer array contains duplicate objects or if message could not be cloned.

%window.`postMessage(message, targetOrigin [, transfer ])$m

これは、 `postMessage()^m の別~versionであり， 宛先~生成元を~parameterとして指定する。 次の 2 つの~callは等価になる ⇒＃ window.postMessage(%message, %target, %transfer), window.postMessage(%message, {targetOrigin: %target, transfer: %transfer}) ◎ This is an alternate version of postMessage() where the target origin is specified as a parameter. Calling window.postMessage(message, target, transfer) is equivalent to window.postMessage(message, {targetOrigin, transfer}).

注記： 新たな`文書$へ~navigateされたばかりの`閲覧~文脈$に対応する`~window$に向けて，~messageを投函した場合、 その~messageは，意図した受信者に受信されない見込みが高い — 宛先 `閲覧~文脈$内の~scriptは、 ~message用の~listenerを設定しておく時間を要するので。 したがって、 一例として［ ~messageが 新たに作成された子 `iframe$e の`~window$に送信される状況 ］においては， 作者には次を行うこと勧める ⇒ 子である方の`文書$から先に，受信する用意が整った旨を親~宛に公告する~messageを投函させ、 親は，この~messageを待機してから~messageを投函し始める ◎ When posting a message to a Window of a browsing context that has just been navigated to a new Document is likely to result in the message not receiving its intended recipient: the scripts in the target browsing context have to have had time to set up listeners for the messages. Thus, for instance, in situations where a message is to be sent to the Window of newly created child iframe, authors are advised to have the child Document post a message to their parent announcing their readiness to receive messages, and for the parent to wait for this message before beginning posting messages.

9.4.1. 序論

`~channel~message法$ 【 `channel messaging^en （ “~channelを介した~messageの送信-法” ）】 を利用すれば、 作者は，独立な~code片どうし （例えば，異なる`閲覧~文脈$内で走っているもの） を直に通信させれる。 ◎ To enable independent pieces of code (e.g. running in different browsing contexts) to communicate directly, authors can use channel messaging.

この仕組みにおける通信~channelは、［ 両端に~portを伴う，二重化された~pipe ］として実装される。 一方の~portに送信される~messageは，他方の~portに送達され、 逆も同様になる。 各~messageは、 走っている`~task$を中断したり阻むことなく，~DOM~eventとして送達される。 ◎ Communication channels in this mechanism are implemented as two-ways pipes, with a port at each end. Messages sent in one port are delivered at the other port, and vice-versa. Messages are delivered as DOM events, without interrupting or blocking running tasks.

接続（ “連絡された” 2 個の~port）を作成するためには、 `new MessageChannel()$m 構築子を~callする： ◎ To create a connection (two "entangled" ports), the MessageChannel() constructor is called:

var %channel = new MessageChannel();

一方の~portは 局所~portとして保たれ、 他方の~portは ~remote~codeへ送信される — 例えば `window.postMessage()$m を利用して： ◎ One of the ports is kept as the local port, and the other port is sent to the remote code, e.g. using postMessage():

%otherWindow.postMessage('hello', 'https://example.com', [%channel.port2]);

~messageを送信するためには、 局所~port上の ``postMessage()$m ~methodを利用する： ◎ To send messages, the postMessage() method on the port is used:

%channel.port1.postMessage('hello');

~messageを受信するためには、 `message$et ~eventを~listenする： ◎ To receive messages, one listens to message events:

%channel.port1.onmessage = handleMessage;
function handleMessage(%event) {
  /* 
~messageは %event の`data$m 属性~内にある
◎
message is in event.data
 */
  // ...
}

~portに送信する~dataは、 有構造~dataも可能である。 例えば，次では、 文字列たちが成す配列が `MessagePort$I に渡される： ◎ Data sent on a port can be structured data; for example here an array of strings is passed on a MessagePort:

%channel.port1.postMessage(['hello', 'world']);

<script src="contacts.js"></script> <!-- 
%contacts ~objを公開する
◎
exposes a contacts object
 -->
<script src="compose-mail.js"></script> <!-- 
%composer ~objを公開する
◎
exposes a composer object
 -->
<script>
 var %channel = new MessageChannel();
 %composer.addContactsProvider(%channel.port1);
 %contacts.registerConsumer(%channel.port2);
</script>

function addContactsProvider(%port) {
  %port.onmessage = function (%event) {
    switch (%event.data.messageType) {
      case 'search-result': handleSearchResult(%event.data.results); break;
      case 'search-done': handleSearchDone(); break;
      case 'search-error': handleSearchError(%event.data.message); break;
      // ...
    }
  };
};

function addContactsProvider(%port) {
  %port.addEventListener('message', function (%event) {
    if (%event.data.messageType == 'search-result')
      handleSearchResult(%event.data.results);
  });
  %port.addEventListener('message', function (%event) {
    if (%event.data.messageType == 'search-done')
      handleSearchDone();
  });
  %port.addEventListener('message', function (%event) {
    if (%event.data.messageType == 'search-error')
      handleSearchError(%event.data.message);
  });
  // ...
  %port.start();
};

9.4.2. ~message~channel

[Exposed=(Window,Worker)]
interface `MessageChannel@I {
  ``MessageChannel$mc();

  readonly attribute `MessagePort$I `port1$m;
  readonly attribute `MessagePort$I `port2$m;
};

%channel = `new MessageChannel()$m

2 個の新たな `MessagePort$I ~objが伴われた，新たな `MessageChannel$I ~objを返す。 ◎ Returns a new MessageChannel object with two new MessagePort objects.

%channel.`port1$m

1 個目の `MessagePort$I ~objを返す。 ◎ Returns the first MessagePort object.

%channel.`port2$m

2 個目の `MessagePort$I ~objを返す。 ◎ Returns the second MessagePort object.

各 `MessageChannel$I ~objには、 `~port 1@, `~port 2@ が結付けられる — どちらも `MessagePort$I ~objを与える。 ◎ A MessageChannel object has an associated port 1 and an associated port 2, both MessagePort objects.

9.4.3. ~message~port

各~channelは、 2 個の~message~portを持つ。 一方の~portから送信された~dataは，他方の~portに受信され、 逆も同様になる。 ◎ Each channel has two message ports. Data sent through one port is received by the other port, and vice versa.

[Exposed=(Window,Worker,AudioWorklet), `Transferable$]
interface `MessagePort@I : `EventTarget$I {
  undefined ``postMessage$m(any %message, sequence<`object$> %transfer);
  undefined ``~postMessageO$m(any %message, optional `StructuredSerializeOptions$I %options = {});
  undefined ``start$m();
  undefined ``close$m();

  // event handlers
  attribute `EventHandler$I ``onmessage$m;
  attribute `EventHandler$I ``onmessageerror$m;
  attribute `EventHandler$I ``onclose$m;
};

dictionary `StructuredSerializeOptions@I {
  sequence<`object$> `transfer@m = [];
};

%port.``postMessage( message, transfer)$m【！ [, transfer]】

%port.``~postMessageO(message [, options])$m

~channelを通して~messageを投函する。 ［ %transfer ／［ %options の `transfer$m ~member ］］内に~listされた~objは、 ~cloneされるのみならず転送される — すなわち、 送信-側からは，それ以降 それらを利用できなくなる。 ◎ Posts a message through the channel. Objects listed in transfer are transferred, not just cloned, meaning that they are no longer usable on the sending side.

次の場合は `DataCloneError$E が投出される ⇒ %transfer が 同じ［ ~obj／~port ］を重複して包含する場合 ／ %message を~cloneできなかった場合 ◎ Throws a "DataCloneError" DOMException if transfer contains duplicate objects or port, or if message could not be cloned.

%port.``start()$m

この~portに受信される／された~messageを配送させ始める。 ◎ Begins dispatching messages received on the port.

%port.``close()$m

この~portを切断する。 以降、 この~portは作動中でなくなる。 ◎ Disconnects the port, so that it is no longer active.

ある~port %P の`~port~message~queue$ %Q が可能化されたときは、 `~event~loop$は， %Q をその`~task~source$の一つとして利用する†モノトスル。 【†すなわち、 %Q を成す各~taskを~event~loopの中で走らすことになる。】 %P に`関連な大域~obj$は`~window$である場合、 %Q に~queueされた`~task$の`文書$tKは， %P に`関連な大域~obj$に`結付けられた文書$になるモノトスル。 ◎ When a port's port message queue is enabled, the event loop must use it as one of its task sources. When a port's relevant global object is a Window, all tasks queued on its port message queue must be associated with the port's relevant global object's associated Document.

注記： ［ 当の文書は`全部的に作動中$である ］が［ 【~port用に登録された】すべての~event~listenerは、 `全部的に作動中$でない文書の文脈~内で作成されていた ］場合、 ~queueされた各~messageは，それらの文書が再び`全部的に作動中$に［ ならない限り／なるまでは ］，受信されないことになる。 ◎ If the document is fully active, but the event listeners were all created in the context of documents that are not fully active, then the messages will not be received unless and until the documents become fully active again.

［ `MessagePort$I の`搬送-済みか$ ~EQ ~F ］の下では、 その`~port~message~queue$は，`~event~loop$の目的においては無視するモノトスル （代わりに，`未搬送な~port~message~queue$が利用される）。 ◎ When a MessagePort's has been shipped flag is false, its port message queue must be ignored for the purposes of the event loop. (The unshipped port message queue is used instead.)

注記： `MessagePort$I ~obj %P の`搬送-済みか$は、［ %P, %P の相手~側~port, %P の~clone元~obj ］のいずれかが，転送されるか, すでにされている ］ときに ~T にされる。 %P の`搬送-済みか$が ~T にされて以降は、 %P の`~port~message~queue$は first-class `~task~source$ 【すなわち， “通常の，独立な” ~task~source】 として動作し，`未搬送な~port~message~queue$には影響しなくなる 【その一部を成さなくなる】。 ◎ The has been shipped flag is set to true when a port, its twin, or the object it was cloned from, is or has been transferred. When a MessagePort's has been shipped flag is true, its port message queue acts as a first-class task source, unaffected to any unshipped port message queue.

`MessagePort$I ~objは`転送-可能$である： ◎ MessagePort objects are transferable objects.＼

• その`転送-手続き$は、所与の ( %値, %~data保持体 ) に対し，次を走らす： ◎ Their transfer steps, given value and dataHolder, are:

  1. %値 の`搬送-済みか$ ~SET ~T ◎ Set value's has been shipped flag to true.
  2. %~data保持体.`PortMessageQueue^sl ~SET %値 の`~port~message~queue$ ◎ Set dataHolder.[[PortMessageQueue]] to value's port message queue.

  3. ~IF［ ある別~port %~remote~port が %値 に連絡されている ］： ◎ If value is entangled with another port remotePort, then:

     1. %~remote~port の`搬送-済みか$ ~SET ~T ◎ Set remotePort's has been shipped flag to true.

     2. %~data保持体.`RemotePort^sl ~SET %~remote~port ◎ Set dataHolder.[[RemotePort]] to remotePort.

  4. ~ELSE ⇒ %~data保持体.`RemotePort^sl ~SET ~NULL ◎ Otherwise, set dataHolder.[[RemotePort]] to null.

• その`転送-受信-時の手続き$は、所与の ( %~data保持体, %値 ) に対し，次を走らす： ◎ Their transfer-receiving steps, given dataHolder and value, are:

  1. %値 の`搬送-済みか$ ~SET ~T ◎ Set value's has been shipped flag to true.

  2. %~data保持体.`PortMessageQueue^sl を成す ~EACH( `message$et ~eventを発火する`~task$ %~task ) に対し：

     1. %~task を %値 の`~port~message~queue$に移動する — この`~port~message~queue$は、 （初期~時の）不能化~状態のまま変えないとする
     2. ~IF［ %値 に`関連な大域~obj$は`~window$である ］ ⇒ %~task の`文書$tK ~SET %値 に`関連な大域~obj$に`結付けられた文書$
     ◎ Move all the tasks that are to fire message events in dataHolder.[[PortMessageQueue]] to the port message queue of value, if any,＼ leaving value's port message queue in its initial disabled state, and,＼ if value's relevant global object is a Window, associating the moved tasks with value's relevant global object's associated Document.
  3. ~IF［ %~data保持体.`RemotePort^sl ~NEQ ~NULL ］ ⇒ `~portを連絡する$( %~data保持体.`RemotePort^sl, %値 ) ⇒ （これは、 元の転送された~portと %~data保持体.`RemotePort^sl との連絡を断つことになる。） ◎ If dataHolder.[[RemotePort]] is not null, then entangle dataHolder.[[RemotePort]] and value. (This will disentangle dataHolder.[[RemotePort]] from the original port that was transferred.)

`MessagePort$I ~interfaceを実装している すべての~objは、［ 以下に挙げる`~event~handler$, および対応する`~event~handler~event型$ ］を`~event~handler~IDL属性$として~supportするモノトスル： ◎ The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all objects implementing the MessagePort interface:

%P の`~port~message~queue$は、 `MessagePort$I ~obj %P の ``onmessage$m ~IDL属性が初回に設定された時点で， %P の ``start()$m ~methodが~callされたかのように可能化されるモノトスル。 ◎ The first time a MessagePort object's onmessage IDL attribute is set, the port's port message queue must be enabled, as if the start() method had been called.

9.4.4. ~portと~garbage収集

`MessagePort$I ~obj %O が~garbage収集されたときは、 %O が他と連絡されている場合には，次を遂行するモノトスル ⇒ `~portの連絡を断つ$( %O ) ◎ When a MessagePort object o is garbage collected, if o is entangled, then the user agent must disentangle o.

`MessagePort$I ~obj %O が他と連絡されていて，［ `message$et ／ `messageerror$et ］~event~listenerが登録されている間は、 ~UAは，［ %O に連絡された `MessagePort$I ~objは %O への強い参照を有する ］かのように動作するモノトスル。 ◎ When a MessagePort object o is entangled and message or messageerror event listener is registered, user agents must act as if o's entangled MessagePort object has a strong reference to o.

更には， `MessagePort$I ~obj %O は、 ~OR↓ が満たされている間は，~garbage収集されないモノトスル： ◎ Furthermore, a MessagePort object must not be garbage collected＼

• ある`~task~queue$内の ある`~task$が、 %O に向けて配送される~eventを参照している ◎ while there exists an event referenced by a task in a task queue that is to be dispatched on that MessagePort object, or＼
• %O の`~port~message~queue$は、 空でない, かつ 可能化されている ◎ while the MessagePort object's port message queue is enabled and not empty.

注記： 作者には、 `MessagePort$I ~objを明示的に~closeして，それらの連絡を断つことが強く奨励される — そうすれば、 それらの資源を収集し直せるようになる。 多数の `MessagePort$I ~objを作成して，それらを~closeすることなく破棄することは、 ~memory利用量が一時に跳ね上がり得る — ~garbage収集は、 とりわけ［ `MessagePort$I に対する~garbage収集に~cross-processの協調も孕まれ得る所 ］では，即座に遂行されるとは限らないので。 ◎ Authors are strongly encouraged to explicitly close MessagePort objects to disentangle them, so that their resources can be recollected. Creating many MessagePort objects and discarding them without closing them can lead to high transient memory usage since garbage collection is not necessarily performed promptly, especially for MessagePorts where garbage collection can involve cross-process coordination.