JSWindowActor.webidl (6054B)
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 ESM path which should be loaded for the actor on this side. 130 * 131 * If this is not is passed, the specified side cannot receive messages, but 132 * may send them using `sendAsyncMessage` or `sendQuery`. 133 */ 134 ByteString esModuleURI; 135 }; 136 137 dictionary WindowActorEventListenerOptions : AddEventListenerOptions { 138 /** 139 * If this attribute is set to true (the default), this event will cause the 140 * actor to be created when it is fired. If the attribute is set false, the 141 * actor will not receive the event unless it had already been created through 142 * some other mechanism. 143 * 144 * This should be set to `false` for event listeners which are only intended 145 * to perform cleanup operations, and will have no effect if the actor doesn't 146 * already exist. 147 */ 148 boolean createActor = true; 149 }; 150 151 dictionary WindowActorChildOptions : WindowActorSidedOptions { 152 /** 153 * Events which this actor wants to be listening to. When these events fire, 154 * it will trigger actor creation, and then forward the event to the actor. 155 * 156 * NOTE: Listeners are not attached for windows loaded in chrome docshells. 157 * 158 * NOTE: `once` option is not support due to we register listeners in a shared 159 * location. 160 */ 161 record<DOMString, WindowActorEventListenerOptions> events; 162 163 /** 164 * An array of observer topics to listen to. An observer will be added for each 165 * topic in the list. 166 * 167 * Observer notifications in the list use nsGlobalWindowInner or 168 * nsGlobalWindowOuter object as their subject, and the events will only be 169 * dispatched to the corresponding window actor. If additional observer 170 * notification's subjects are needed, please file a bug for that. 171 */ 172 sequence<ByteString> observers; 173 };