Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 576 insertions, 0 deletions

diff --git a/dom/chrome-webidl/MessageManager.webidl b/dom/chrome-webidl/MessageManager.webidl
new file mode 100644
index 0000000000..d77f1751ee
--- /dev/null
+++ b/dom/chrome-webidl/MessageManager.webidl
@@ -0,0 +1,576 @@
+/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+interface nsIEventTarget;
+interface Principal;
+
+/**
+ * Message managers provide a way for chrome-privileged JS code to
+ * communicate with each other, even across process boundaries.
+ *
+ * Message managers are separated into "parent side" and "child side".
+ * These don't always correspond to process boundaries, but can.  For
+ * each child-side message manager, there is always exactly one
+ * corresponding parent-side message manager that it sends messages
+ * to.  However, for each parent-side message manager, there may be
+ * either one or many child-side managers it can message.
+ *
+ * Message managers that always have exactly one "other side" are of
+ * type MessageSender.  Parent-side message managers that have many
+ * "other sides" are of type MessageBroadcaster.
+ *
+ * Child-side message managers can send synchronous messages to their
+ * parent side, but not the other way around.
+ *
+ * There are two realms of message manager hierarchies.  One realm
+ * approximately corresponds to DOM elements, the other corresponds to
+ * process boundaries.
+ *
+ * Message managers corresponding to DOM elements
+ * ==============================================
+ *
+ * In this realm of message managers, there are
+ *  - "frame message managers" which correspond to frame elements
+ *  - "window message managers" which correspond to top-level chrome
+ *    windows
+ *  - "group message managers" which correspond to named message
+ *    managers with a specific window MM as the parent
+ *  - the "global message manager", on the parent side.  See below.
+ *
+ * The DOM-realm message managers can communicate in the ways shown by
+ * the following diagram.  The parent side and child side can
+ * correspond to process boundaries, but don't always.
+ *
+ *  Parent side                         Child side
+ * -------------                       ------------
+ *  global MMg
+ *   |
+ *   +-->window MMw1
+ *   |    |
+ *   |    +-->frame MMp1_1<------------>frame MMc1_1
+ *   |    |
+ *   |    +-->frame MMp1_2<------------>frame MMc1_2
+ *   |    |
+ *   |    +-->group MMgr1
+ *   |    |    |
+ *   |    |    +-->frame MMp2_1<------->frame MMc2_1
+ *   |    |    |
+ *   |    |    +-->frame MMp2_2<------->frame MMc2_2
+ *   |    |
+ *   |    +-->group MMgr2
+ *   |    |    ...
+ *   |    |
+ *   |    ...
+ *   |
+ *   +-->window MMw2
+ *   ...
+ *
+ * For example: a message sent from MMc1_1, from the child side, is
+ * sent only to MMp1_1 on the parent side.  However, note that all
+ * message managers in the hierarchy above MMp1_1, in this diagram
+ * MMw1 and MMg, will also notify their message listeners when the
+ * message arrives.
+ *
+ * A message sent from MMc2_1 will be sent to MMp2_1 and also notify
+ * all message managers in the hierarchy above that, including the
+ * group message manager MMgr1.
+
+ * For example: a message broadcast through the global MMg on the
+ * parent side would be broadcast to MMw1, which would transitively
+ * broadcast it to MMp1_1, MM1p_2.  The message would next be
+ * broadcast to MMgr1, which would broadcast it to MMp2_1 and MMp2_2.
+ * After that it would broadcast to MMgr2 and then to MMw2, and so
+ * on down the hierarchy.
+ *
+ *   ***** PERFORMANCE AND SECURITY WARNING *****
+ * Messages broadcast through the global MM and window or group MMs
+ * can result in messages being dispatched across many OS processes,
+ * and to many processes with different permissions.  Great care
+ * should be taken when broadcasting.
+ *
+ * Interfaces
+ * ----------
+ *
+ * The global MMg and window MMw's are message broadcasters implementing
+ * MessageBroadcaster while the frame MMp's are simple message senders (MessageSender).
+ * Their counterparts in the content processes are message senders implementing
+ * ContentFrameMessageManager.
+ *
+ *                 MessageListenerManager
+ *               /                        \
+ * MessageSender                            MessageBroadcaster
+ *       |
+ * SyncMessageSender (content process/in-process only)
+ *       |
+ * ContentFrameMessageManager (content process/in-process only)
+ *       |
+ * nsIInProcessContentFrameMessageManager (in-process only)
+ *
+ *
+ * Message managers in the chrome process also implement FrameScriptLoader.
+ *
+ *
+ * Message managers corresponding to process boundaries
+ * ====================================================
+ *
+ * The second realm of message managers is the "process message
+ * managers".  With one exception, these always correspond to process
+ * boundaries.  The picture looks like
+ *
+ *  Parent process                      Child processes
+ * ----------------                    -----------------
+ *  global (GPPMM)
+ *   |
+ *   +-->parent in-process PIPMM<-->child in-process CIPPMM
+ *   |
+ *   +-->parent (PPMM1)<------------------>child (CPMM1)
+ *   |
+ *   +-->parent (PPMM2)<------------------>child (CPMM2)
+ *   ...
+ *
+ * Note, PIPMM and CIPPMM both run in the parent process.
+ *
+ * For example: the parent-process PPMM1 sends messages to the
+ * child-process CPMM1.
+ *
+ * For example: CPMM1 sends messages directly to PPMM1. The global GPPMM
+ * will also notify their message listeners when the message arrives.
+ *
+ * For example: messages sent through the global GPPMM will be
+ * dispatched to the listeners of the same-process, CIPPMM, CPMM1,
+ * CPMM2, etc.
+ *
+ *   ***** PERFORMANCE AND SECURITY WARNING *****
+ * Messages broadcast through the GPPMM can result in messages
+ * being dispatched across many OS processes, and to many processes
+ * with different permissions.  Great care should be taken when
+ * broadcasting.
+ *
+ * Requests sent to parent-process message listeners should usually
+ * have replies scoped to the requesting CPMM.  The following pattern
+ * is common
+ *
+ *  const ParentProcessListener = {
+ *    receiveMessage: function(aMessage) {
+ *      switch (aMessage.name) {
+ *      case "Foo:Request":
+ *        // service request
+ *        aMessage.target.sendAsyncMessage("Foo:Response", { data });
+ *      }
+ *    }
+ *  };
+ */
+
+dictionary ReceiveMessageArgument
+{
+  /**
+   * The target of the message. Either an element owning the message manager, or message
+   * manager itself if no element owns it.
+   */
+  required nsISupports target;
+
+  /**
+   * Message name.
+   */
+  required DOMString name;
+
+  required boolean sync;
+
+  /**
+   * Structured clone of the sent message data
+   */
+  any data = null;
+
+  /**
+   * Same as .data, deprecated.
+   */
+  any json = null;
+
+  sequence<MessagePort> ports;
+
+  FrameLoader targetFrameLoader;
+};
+
+[Exposed=Window]
+callback interface MessageListener
+{
+  /**
+   * Each listener is invoked with its own copy of the message
+   * parameter.
+   *
+   * When the listener is called, 'this' value is the target of the message.
+   *
+   * If the message is synchronous, the possible return value is
+   * returned as JSON (will be changed to use structured clones).
+   * When there are multiple listeners to sync messages, each
+   * listener's return value is sent back as an array.  |undefined|
+   * return values show up as undefined values in the array.
+   */
+  any receiveMessage(ReceiveMessageArgument argument);
+};
+
+[ChromeOnly, Exposed=Window]
+interface MessageListenerManager
+{
+  // All the methods are pulled in via mixin.
+};
+MessageListenerManager includes MessageListenerManagerMixin;
+
+interface mixin MessageListenerManagerMixin
+{
+  /**
+   * Register |listener| to receive |messageName|.  All listener
+   * callbacks for a particular message are invoked when that message
+   * is received.
+   *
+   * The message manager holds a strong ref to |listener|.
+   *
+   * If the same listener registers twice for the same message, the
+   * second registration is ignored.
+   *
+   * Pass true for listenWhenClosed if you want to receive messages
+   * during the short period after a frame has been removed from the
+   * DOM and before its frame script has finished unloading. This
+   * parameter only has an effect for frame message managers in
+   * the main process. Default is false.
+   */
+  [Throws]
+  undefined addMessageListener(DOMString messageName,
+                               MessageListener listener,
+                               optional boolean listenWhenClosed = false);
+
+  /**
+   * Undo an |addMessageListener| call -- that is, calling this causes us to no
+   * longer invoke |listener| when |messageName| is received.
+   *
+   * removeMessageListener does not remove a message listener added via
+   * addWeakMessageListener; use removeWeakMessageListener for that.
+   */
+  [Throws]
+  undefined removeMessageListener(DOMString messageName,
+                                  MessageListener listener);
+
+  /**
+   * This is just like addMessageListener, except the message manager holds a
+   * weak ref to |listener|.
+   *
+   * If you have two weak message listeners for the same message, they may be
+   * called in any order.
+   */
+  [Throws]
+  undefined addWeakMessageListener(DOMString messageName,
+                                   MessageListener listener);
+
+  /**
+   * This undoes an |addWeakMessageListener| call.
+   */
+  [Throws]
+  undefined removeWeakMessageListener(DOMString messageName,
+                                      MessageListener listener);
+};
+
+/**
+ * Message "senders" have a single "other side" to which messages are
+ * sent.  For example, a child-process message manager will send
+ * messages that are only delivered to its one parent-process message
+ * manager.
+ */
+[ChromeOnly, Exposed=Window]
+interface MessageSender : MessageListenerManager
+{
+  // All the methods are pulled in via mixin.
+};
+MessageSender includes MessageSenderMixin;
+
+/**
+ * Anyone including this MUST also incude MessageListenerManagerMixin.
+ */
+interface mixin MessageSenderMixin {
+  /**
+   * Send |messageName| and |obj| to the "other side" of this message
+   * manager.  This invokes listeners who registered for
+   * |messageName|.
+   *
+   * See ReceiveMessageArgument for the format of the data delivered to listeners.
+   * @throws NS_ERROR_NOT_INITIALIZED if the sender is not initialized.  For
+   *         example, we will throw NS_ERROR_NOT_INITIALIZED if we try to send
+   *         a message to a cross-process frame but the other process has not
+   *         yet been set up.
+   * @throws NS_ERROR_FAILURE when the message receiver cannot be found.  For
+   *         example, we will throw NS_ERROR_FAILURE if we try to send a message
+   *         to a cross-process frame whose process has crashed.
+   */
+  [Throws]
+  undefined sendAsyncMessage(optional DOMString? messageName = null,
+                             optional any obj,
+                             optional any transfers);
+
+  /**
+   * For remote browsers there is always a corresponding process message
+   * manager. The intention of this attribute is to link leaf level frame
+   * message managers on the parent side with the corresponding process
+   * message managers (if there is one). For any other cases this property
+   * is null.
+   */
+  [Throws]
+  readonly attribute MessageSender? processMessageManager;
+
+  /**
+   * For remote browsers, this contains the remoteType of the content child.
+   * Otherwise, it is empty.
+   */
+  [Throws]
+  readonly attribute UTF8String remoteType;
+};
+
+[ChromeOnly, Exposed=Window]
+interface SyncMessageSender : MessageSender
+{
+  // All the methods are pulled in via mixin.
+};
+SyncMessageSender includes SyncMessageSenderMixin;
+
+/**
+ * Anyone including this MUST also incude MessageSenderMixin.
+ */
+interface mixin SyncMessageSenderMixin
+{
+  /**
+   * Like |sendAsyncMessage()|, except blocks the sender until all
+   * listeners of the message have been invoked.  Returns an array
+   * containing return values from each listener invoked.
+   */
+  [Throws]
+  sequence<any> sendSyncMessage(optional DOMString? messageName = null,
+                                optional any obj);
+};
+
+/**
+ * ChildProcessMessageManager is used in a child process to communicate with the parent
+ * process.
+ */
+[ChromeOnly, Exposed=Window]
+interface ChildProcessMessageManager : SyncMessageSender
+{
+};
+
+/**
+ * Mixin for message manager globals.  Anyone including this MUST also
+ * include SyncMessageSenderMixin.
+ */
+interface mixin MessageManagerGlobal
+{
+  /**
+   * Print a string to stdout.
+   */
+  undefined dump(DOMString str);
+
+  /**
+   * Ascii base64 data to binary data and vice versa
+   */
+  [Throws]
+  DOMString atob(DOMString asciiString);
+  [Throws]
+  DOMString btoa(DOMString base64Data);
+};
+
+interface mixin FrameScriptLoader
+{
+  /**
+   * Load a script in the (remote) frame. |url| must be the absolute URL.
+   * data: URLs are also supported. For example data:,dump("foo\n");
+   * If allowDelayedLoad is true, script will be loaded when the
+   * remote frame becomes available. Otherwise the script will be loaded
+   * only if the frame is already available.
+   */
+  [Throws]
+  undefined loadFrameScript(DOMString url, boolean allowDelayedLoad,
+                            optional boolean runInGlobalScope = false);
+
+  /**
+   * Removes |url| from the list of scripts which support delayed load.
+   */
+  undefined removeDelayedFrameScript(DOMString url);
+
+  /**
+   * Returns all delayed scripts that will be loaded once a (remote)
+   * frame becomes available. The return value is a list of pairs
+   * [<URL>, <WasLoadedInGlobalScope>].
+   */
+  [Throws]
+  sequence<sequence<any>> getDelayedFrameScripts();
+};
+
+interface mixin ProcessScriptLoader
+{
+  /**
+   * Load a script in the (possibly remote) process. |url| must be the absolute
+   * URL. data: URLs are also supported. For example data:,dump("foo\n");
+   * If allowDelayedLoad is true, script will be loaded when the
+   * remote frame becomes available. Otherwise the script will be loaded
+   * only if the frame is already available.
+   */
+  [Throws]
+  undefined loadProcessScript(DOMString url, boolean allowDelayedLoad);
+
+  /**
+   * Removes |url| from the list of scripts which support delayed load.
+   */
+  undefined removeDelayedProcessScript(DOMString url);
+
+  /**
+   * Returns all delayed scripts that will be loaded once a (remote)
+   * frame becomes available. The return value is a list of pairs
+   * [<URL>, <WasLoadedInGlobalScope>].
+   */
+  [Throws]
+  sequence<sequence<any>> getDelayedProcessScripts();
+};
+
+/**
+ * Anyone including GlobalProcessScriptLoader MUST also include ProcessScriptLoader.
+ */
+interface mixin GlobalProcessScriptLoader
+{
+  /**
+   * Allows the parent process to set the initial process data for
+   * new, not-yet-created child processes. This attribute should only
+   * be used by the global parent process message manager. When a new
+   * process is created, it gets a copy of this data (via structured
+   * cloning). It can access the data via the initialProcessData
+   * attribute of its childprocessmessagemanager.
+   *
+   * This value will always be a JS object if it's not null or undefined. Different
+   * users are expected to set properties on this object. The property name should be
+   * unique enough that other Gecko consumers won't accidentally choose it.
+   */
+  [Throws]
+  readonly attribute any initialProcessData;
+
+  readonly attribute MozWritableSharedMap sharedData;
+};
+
+[ChromeOnly, Exposed=Window]
+interface ContentFrameMessageManager : EventTarget
+{
+  /**
+   * The current top level window in the frame or null.
+   */
+  [Throws]
+  readonly attribute WindowProxy? content;
+
+  /**
+   * The top level docshell or null.
+   */
+  [Throws]
+  readonly attribute nsIDocShell? docShell;
+
+  /**
+   * Returns the SchedulerEventTarget corresponding to the TabGroup
+   * for this frame.
+   */
+  readonly attribute nsIEventTarget? tabEventTarget;
+
+};
+ContentFrameMessageManager includes MessageManagerGlobal;
+ContentFrameMessageManager includes SyncMessageSenderMixin;
+ContentFrameMessageManager includes MessageSenderMixin;
+ContentFrameMessageManager includes MessageListenerManagerMixin;
+
+[ChromeOnly, Exposed=Window]
+interface ContentProcessMessageManager
+{
+  /**
+   * Read out a copy of the object that was initialized in the parent
+   * process via ProcessScriptLoader.initialProcessData.
+   */
+  [Throws]
+  readonly attribute any initialProcessData;
+
+  readonly attribute MozSharedMap? sharedData;
+};
+ContentProcessMessageManager includes MessageManagerGlobal;
+ContentProcessMessageManager includes SyncMessageSenderMixin;
+ContentProcessMessageManager includes MessageSenderMixin;
+ContentProcessMessageManager includes MessageListenerManagerMixin;
+
+/**
+ * Message "broadcasters" don't have a single "other side" that they send messages to, but
+ * rather a set of subordinate message managers. For example, broadcasting a message
+ * through a window message manager will broadcast the message to all frame message
+ * managers within its window.
+ */
+[ChromeOnly, Exposed=Window]
+interface MessageBroadcaster : MessageListenerManager
+{
+  /**
+   * Like |sendAsyncMessage()|, but also broadcasts this message to
+   * all "child" message managers of this message manager.  See long
+   * comment above for details.
+   *
+   * WARNING: broadcasting messages can be very expensive and leak
+   * sensitive data.  Use with extreme caution.
+   */
+  [Throws]
+  undefined broadcastAsyncMessage(optional DOMString? messageName = null,
+                                  optional any obj);
+
+  /**
+   * Number of subordinate message managers.
+   */
+  readonly attribute unsigned long childCount;
+
+  /**
+   * Return a single subordinate message manager.
+   */
+  MessageListenerManager? getChildAt(unsigned long aIndex);
+
+  /**
+   * Some processes are kept alive after their last tab/window are closed for testing
+   * (see dom.ipc.keepProcessesAlive). This function releases those.
+   */
+   undefined releaseCachedProcesses();
+};
+
+/**
+ * ChromeMessageBroadcaster is used for window and group message managers.
+ */
+[ChromeOnly, Exposed=Window]
+interface ChromeMessageBroadcaster : MessageBroadcaster
+{
+};
+ChromeMessageBroadcaster includes FrameScriptLoader;
+
+/**
+ * ParentProcessMessageManager is used in a parent process to communicate with all the
+ * child processes.
+ */
+[ChromeOnly, Exposed=Window]
+interface ParentProcessMessageManager : MessageBroadcaster
+{
+};
+ParentProcessMessageManager includes ProcessScriptLoader;
+ParentProcessMessageManager includes GlobalProcessScriptLoader;
+
+[ChromeOnly, Exposed=Window]
+interface ChromeMessageSender : MessageSender
+{
+};
+ChromeMessageSender includes FrameScriptLoader;
+
+/**
+ * ProcessMessageManager is used in a parent process to communicate with a child process
+ * (or with the process itself in a single-process scenario).
+ */
+[ChromeOnly, Exposed=Window]
+interface ProcessMessageManager : MessageSender
+{
+  // PID of the process being communicated with.
+  readonly attribute long osPid;
+
+  // Whether this is message manager for the current process.
+  readonly attribute boolean isInProcess;
+};
+ProcessMessageManager includes ProcessScriptLoader;