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/. */
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).
12 * See https://firefox-source-docs.mozilla.org/dom/ipc/jsactors.html for
13 * more details on how to use this architecture.
16 interface nsISupports;
18 [ChromeOnly, Exposed=Window]
19 interface JSWindowActorParent {
24 * Actor initialization occurs after the constructor is called but before the
25 * first message is delivered. Until the actor is initialized, accesses to
28 readonly attribute WindowGlobalParent? manager;
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.
36 readonly attribute WindowContext? windowContext;
39 readonly attribute CanonicalBrowsingContext? browsingContext;
41 JSWindowActorParent includes JSActor;
43 [ChromeOnly, Exposed=Window]
44 interface JSWindowActorChild {
49 * Actor initialization occurs after the constructor is called but before the
50 * first message is delivered. Until the actor is initialized, accesses to
53 readonly attribute WindowGlobalChild? manager;
56 * The WindowContext associated with this JSWindowActorChild. Until the actor
57 * is initialized, accesses to windowContext will fail.
59 readonly attribute WindowContext? windowContext;
62 readonly attribute Document? document;
65 readonly attribute BrowsingContext? browsingContext;
68 readonly attribute nsIDocShell? docShell;
71 * NOTE: As this returns a window proxy, it may not be currently referencing
72 * the document associated with this JSWindowActor. Generally prefer using
76 readonly attribute WindowProxy? contentWindow;
78 JSWindowActorChild includes JSActor;
81 * Used by ChromeUtils.registerWindowActor() to register JS window actor.
83 dictionary WindowActorOptions {
85 * If this is set to `true`, allow this actor to be created for subframes,
86 * and not just toplevel window globals.
88 boolean allFrames = false;
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
95 boolean includeChrome = false;
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.
104 sequence<DOMString> matches;
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.
114 sequence<UTF8String> remoteTypes;
117 * An array of MessageManagerGroup values which restrict which type
118 * of browser elements the actor is allowed to be loaded within.
120 sequence<DOMString> messageManagerGroups;
122 /** This fields are used for configuring individual sides of the actor. */
123 WindowActorSidedOptions parent;
124 WindowActorChildOptions child;
127 dictionary WindowActorSidedOptions {
129 * The JSM path which should be loaded for the actor on this side.
130 * If not passed, the specified side cannot receive messages, but may send
131 * them using `sendAsyncMessage` or `sendQuery`.
133 required ByteString moduleURI;
136 dictionary WindowActorEventListenerOptions : AddEventListenerOptions {
138 * If this attribute is set to true (the default), this event will cause the
139 * actor to be created when it is fired. If the attribute is set false, the
140 * actor will not receive the event unless it had already been created through
141 * some other mechanism.
143 * This should be set to `false` for event listeners which are only intended
144 * to perform cleanup operations, and will have no effect if the actor doesn't
147 boolean createActor = true;
150 dictionary WindowActorChildOptions : WindowActorSidedOptions {
152 * Events which this actor wants to be listening to. When these events fire,
153 * it will trigger actor creation, and then forward the event to the actor.
155 * NOTE: Listeners are not attached for windows loaded in chrome docshells.
157 * NOTE: `once` option is not support due to we register listeners in a shared
160 record<DOMString, WindowActorEventListenerOptions> events;
163 * An array of observer topics to listen to. An observer will be added for each
166 * Observer notifications in the list use nsGlobalWindowInner or
167 * nsGlobalWindowOuter object as their subject, and the events will only be
168 * dispatched to the corresponding window actor. If additional observer
169 * notification's subjects are needed, please file a bug for that.
171 sequence<ByteString> observers;