dom/chrome-webidl/JSWindowActor.webidl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /**
   8  * An actor architecture designed to allow compositional parent/content
   9  * communications. The lifetime of a JSWindowActor{Child, Parent} is the `WindowGlobalParent`
  10  * (for the parent-side) / `WindowGlobalChild` (for the child-side).
  11  *
  12  * See https://firefox-source-docs.mozilla.org/dom/ipc/jsactors.html for
  13  * more details on how to use this architecture.
  14  */
  15
  16 interface nsISupports;
  17
  18 [ChromeOnly, Exposed=Window]
  19 interface JSWindowActorParent {
  20   [ChromeOnly]
  21   constructor();
  22
  23   /**
  24    * Actor initialization occurs after the constructor is called but before the
  25    * first message is delivered. Until the actor is initialized, accesses to
  26    * manager will fail.
  27    */
  28   readonly attribute WindowGlobalParent? manager;
  29
  30   /**
  31    * The WindowContext associated with this JSWindowActorParent. For
  32    * JSWindowActorParent this is identical to `manager`, but is also exposed as
  33    * `windowContext` for consistency with `JSWindowActorChild`. Until the actor
  34    * is initialized, accesses to windowContext will fail.
  35    */
  36   readonly attribute WindowContext? windowContext;
  37
  38   [Throws]
  39   readonly attribute CanonicalBrowsingContext? browsingContext;
  40 };
  41 JSWindowActorParent includes JSActor;
  42
  43 [ChromeOnly, Exposed=Window]
  44 interface JSWindowActorChild {
  45   [ChromeOnly]
  46   constructor();
  47
  48   /**
  49    * Actor initialization occurs after the constructor is called but before the
  50    * first message is delivered. Until the actor is initialized, accesses to
  51    * manager will fail.
  52    */
  53   readonly attribute WindowGlobalChild? manager;
  54
  55   /**
  56    * The WindowContext associated with this JSWindowActorChild. Until the actor
  57    * is initialized, accesses to windowContext will fail.
  58    */
  59   readonly attribute WindowContext? windowContext;
  60
  61   [Throws]
  62   readonly attribute Document? document;
  63
  64   [Throws]
  65   readonly attribute BrowsingContext? browsingContext;
  66
  67   [Throws]
  68   readonly attribute nsIDocShell? docShell;
  69
  70   /**
  71    * NOTE: As this returns a window proxy, it may not be currently referencing
  72    * the document associated with this JSWindowActor. Generally prefer using
  73    * `document`.
  74    */
  75   [Throws]
  76   readonly attribute WindowProxy? contentWindow;
  77 };
  78 JSWindowActorChild includes JSActor;
  79
  80 /**
  81  * Used by ChromeUtils.registerWindowActor() to register JS window actor.
  82  */
  83 dictionary WindowActorOptions {
  84   /**
  85    * If this is set to `true`, allow this actor to be created for subframes,
  86    * and not just toplevel window globals.
  87    */
  88   boolean allFrames = false;
  89
  90   /**
  91    * If this is set to `true`, allow this actor to be created for window
  92    * globals loaded in chrome browsing contexts, such as those used to load the
  93    * tabbrowser.
  94    */
  95   boolean includeChrome = false;
  96
  97   /**
  98    * An array of URL match patterns (as accepted by the MatchPattern
  99    * class in MatchPattern.webidl) which restrict which pages the actor
 100    * may be instantiated for. If this is defined, only documents URL which match
 101    * are allowed to have the given actor created for them. Other
 102    * documents will fail to have their actor constructed, returning nullptr.
 103    */
 104   sequence<DOMString> matches;
 105
 106   /**
 107    * An array of remote type which restricts the actor is allowed to instantiate
 108    * in specific process type. If this is defined, the prefix of process type
 109    * matches the remote type by prefix match is allowed to instantiate, ex: if
 110    * Fission is enabled, the prefix of process type will be `webIsolated`, it
 111    * can prefix match remote type either `web` or `webIsolated`. If not passed,
 112    * all content processes are allowed to instantiate the actor.
 113    */
 114   sequence<UTF8String> remoteTypes;
 115
 116   /**
 117    * An array of MessageManagerGroup values which restrict which type
 118    * of browser elements the actor is allowed to be loaded within.
 119    */
 120   sequence<DOMString> messageManagerGroups;
 121
 122   /** This fields are used for configuring individual sides of the actor. */
 123   WindowActorSidedOptions parent;
 124   WindowActorChildOptions child;
 125 };
 126
 127 dictionary WindowActorSidedOptions {
 128   /**
 129    * The JSM path which should be loaded for the actor on this side.
 130    *
 131    * Mutually exclusive with `esModuleURI`.
 132    *
 133    * If neither this nor `esModuleURI` is passed, the specified side cannot receive
 134    * messages, but may send them using `sendAsyncMessage` or `sendQuery`.
 135    *
 136    * TODO: Remove this once m-c, c-c, and out-of-tree code migrations finish
 137    *       (bug 1866732).
 138    */
 139   ByteString moduleURI;
 140
 141   /**
 142    * The ESM path which should be loaded for the actor on this side.
 143    *
 144    * Mutually exclusive with `moduleURI`.
 145    *
 146    * If neither this nor `moduleURI` is passed, the specified side cannot
 147    * receive messages, but may send them using `sendAsyncMessage` or
 148    * `sendQuery`.
 149    */
 150   ByteString esModuleURI;
 151 };
 152
 153 dictionary WindowActorEventListenerOptions : AddEventListenerOptions {
 154   /**
 155    * If this attribute is set to true (the default), this event will cause the
 156    * actor to be created when it is fired. If the attribute is set false, the
 157    * actor will not receive the event unless it had already been created through
 158    * some other mechanism.
 159    *
 160    * This should be set to `false` for event listeners which are only intended
 161    * to perform cleanup operations, and will have no effect if the actor doesn't
 162    * already exist.
 163    */
 164   boolean createActor = true;
 165 };
 166
 167 dictionary WindowActorChildOptions : WindowActorSidedOptions {
 168   /**
 169    * Events which this actor wants to be listening to. When these events fire,
 170    * it will trigger actor creation, and then forward the event to the actor.
 171    *
 172    * NOTE: Listeners are not attached for windows loaded in chrome docshells.
 173    *
 174    * NOTE: `once` option is not support due to we register listeners in a shared
 175    * location.
 176    */
 177   record<DOMString, WindowActorEventListenerOptions> events;
 178
 179  /**
 180   * An array of observer topics to listen to. An observer will be added for each
 181   * topic in the list.
 182   *
 183   * Observer notifications in the list use nsGlobalWindowInner or
 184   * nsGlobalWindowOuter object as their subject, and the events will only be
 185   * dispatched to the corresponding window actor. If additional observer
 186   * notification's subjects are needed, please file a bug for that.
 187   */
 188   sequence<ByteString> observers;
 189 };