diff options
Diffstat (limited to 'dom/base/nsIMessageManager.idl')
| -rw-r--r-- | dom/base/nsIMessageManager.idl | 550 |
1 files changed, 550 insertions, 0 deletions
diff --git a/dom/base/nsIMessageManager.idl b/dom/base/nsIMessageManager.idl new file mode 100644 index 000000000..7c64bd222 --- /dev/null +++ b/dom/base/nsIMessageManager.idl @@ -0,0 +1,550 @@ +/* -*- 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/. */ + +#include "nsISupports.idl" + +interface mozIDOMWindowProxy; +interface nsIDocShell; +interface nsIContent; +interface nsIFrameLoader; +interface nsIPrincipal; + +/** + * 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 nsIMessageSender. Parent-side message managers that have many + * "other sides" are of type nsIMessageBroadcaster. + * + * 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 + * nsIMessageBroadcaster while the frame MMp's are simple message senders + * (nsIMessageSender). Their counterparts in the content processes are + * message senders implementing nsIContentFrameMessageManager. + * + * nsIMessageListenerManager + * / \ + * nsIMessageSender nsIMessageBroadcaster + * | + * nsISyncMessageSender (content process/in-process only) + * | + * nsIContentFrameMessageManager (content process/in-process only) + * | + * nsIInProcessContentFrameMessageManager (in-process only) + * + * + * Message managers in the chrome process can also be QI'ed to nsIFrameScriptLoader. + * + * + * 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) { + * let childMM = aMessage.target.QueryInterface(Ci.nsIMessageSender); + * switch (aMessage.name) { + * case "Foo:Request": + * // service request + * childMM.sendAsyncMessage("Foo:Response", { data }); + * } + * } + * }; + */ + +[scriptable, function, uuid(2b44eb57-a9c6-4773-9a1e-fe0818739a4c)] +interface nsIMessageListener : nsISupports +{ + /** + * This is for JS only. + * receiveMessage is called with one parameter, which has the following + * properties: + * { + * target: %the target of the message. Either an element owning + * the message manager, or message manager itself if no + * element owns it% + * name: %message name%, + * sync: %true or false%. + * data: %structured clone of the sent message data%, + * json: %same as .data, deprecated%, + * objects: %named table of jsvals/objects, or null% + * principal: %principal for the window app + * } + * + * 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. + */ + void receiveMessage(); +}; + +[scriptable, builtinclass, uuid(b949bfec-bb7d-47bc-b387-ac6a9b655072)] +interface nsIMessageListenerManager : nsISupports +{ + /** + * 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. + */ + void addMessageListener(in AString messageName, + in nsIMessageListener listener, + [optional] in boolean listenWhenClosed); + + /** + * 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. + */ + void removeMessageListener(in AString messageName, + in nsIMessageListener 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. + */ + void addWeakMessageListener(in AString messageName, + in nsIMessageListener listener); + + /** + * This undoes an |addWeakMessageListener| call. + */ + void removeWeakMessageListener(in AString messageName, + in nsIMessageListener listener); + + [notxpcom] boolean markForCC(); +}; + +/** + * 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. + */ +[scriptable, builtinclass, uuid(bb5d79e4-e73c-45e7-9651-4d718f4b994c)] +interface nsIMessageSender : nsIMessageListenerManager +{ + /** + * Send |messageName| and |obj| to the "other side" of this message + * manager. This invokes listeners who registered for + * |messageName|. + * + * See nsIMessageListener::receiveMessage() 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. + */ + [implicit_jscontext, optional_argc] + void sendAsyncMessage([optional] in AString messageName, + [optional] in jsval obj, + [optional] in jsval objects, + [optional] in nsIPrincipal principal, + [optional] in jsval 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. + */ + readonly attribute nsIMessageSender processMessageManager; +}; + +/** + * 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. + */ +[scriptable, builtinclass, uuid(4d7d62ad-4725-4f39-86cf-8fb22bf9c1d8)] +interface nsIMessageBroadcaster : nsIMessageListenerManager +{ + /** + * 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. + */ + [implicit_jscontext, optional_argc] + void broadcastAsyncMessage([optional] in AString messageName, + [optional] in jsval obj, + [optional] in jsval objects); + + /** + * Number of subordinate message managers. + */ + readonly attribute unsigned long childCount; + + /** + * Return a single subordinate message manager. + */ + nsIMessageListenerManager getChildAt(in unsigned long aIndex); +}; + +[scriptable, builtinclass, uuid(0e602c9e-1977-422a-a8e4-fe0d4a4f78d0)] +interface nsISyncMessageSender : nsIMessageSender +{ + /** + * 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. + */ + [implicit_jscontext, optional_argc] + jsval sendSyncMessage([optional] in AString messageName, + [optional] in jsval obj, + [optional] in jsval objects, + [optional] in nsIPrincipal principal); + + /** + * Like |sendSyncMessage()|, except re-entrant. New RPC messages may be + * issued even if, earlier on the call stack, we are waiting for a reply + * to an earlier sendRpcMessage() call. + * + * Both sendSyncMessage and sendRpcMessage will block until a reply is + * received, but they may be temporarily interrupted to process an urgent + * incoming message (such as a CPOW request). + */ + [implicit_jscontext, optional_argc] + jsval sendRpcMessage([optional] in AString messageName, + [optional] in jsval obj, + [optional] in jsval objects, + [optional] in nsIPrincipal principal); +}; + +[scriptable, builtinclass, uuid(13f3555f-769e-44ea-b607-5239230c3162)] +interface nsIMessageManagerGlobal : nsISyncMessageSender +{ + /** + * Print a string to stdout. + */ + void dump(in DOMString aStr); + + /** + * If leak detection is enabled, print a note to the leak log that this + * process will intentionally crash. + */ + void privateNoteIntentionalCrash(); + + /** + * Ascii base64 data to binary data and vice versa + */ + DOMString atob(in DOMString aAsciiString); + DOMString btoa(in DOMString aBase64Data); +}; + +[scriptable, builtinclass, uuid(694e367c-aa25-4446-8499-2c527c4bd838)] +interface nsIContentFrameMessageManager : nsIMessageManagerGlobal +{ + /** + * The current top level window in the frame or null. + */ + readonly attribute mozIDOMWindowProxy content; + + /** + * The top level docshell or null. + */ + readonly attribute nsIDocShell docShell; +}; + +[uuid(b39a3324-b574-4f85-8cdb-274d04f807ef)] +interface nsIInProcessContentFrameMessageManager : nsIContentFrameMessageManager +{ + [notxpcom] nsIContent getOwnerContent(); + [notxpcom] void cacheFrameLoader(in nsIFrameLoader aFrameLoader); +}; + +[scriptable, builtinclass, uuid(6d12e467-2446-46db-9965-e4e93cb87ca5)] +interface nsIContentProcessMessageManager : nsIMessageManagerGlobal +{ + /** + * Read out a copy of the object that was initialized in the parent + * process via nsIProcessScriptLoader.initialProcessData. + */ + [implicit_jscontext] + readonly attribute jsval initialProcessData; +}; + +[scriptable, builtinclass, uuid(bf61446b-ba24-4b1d-88c7-4f94724b9ce1)] +interface nsIFrameScriptLoader : nsISupports +{ + /** + * Load a script in the (remote) frame. aURL must be the absolute URL. + * data: URLs are also supported. For example data:,dump("foo\n"); + * If aAllowDelayedLoad 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. + */ + void loadFrameScript(in AString aURL, in boolean aAllowDelayedLoad, + [optional] in boolean aRunInGlobalScope); + + /** + * Removes aURL from the list of scripts which support delayed load. + */ + void removeDelayedFrameScript(in AString aURL); + + /** + * Returns all delayed scripts that will be loaded once a (remote) + * frame becomes available. The return value is a list of pairs + * [<URL>, <WasLoadedInGlobalScope>]. + */ + [implicit_jscontext] + jsval getDelayedFrameScripts(); +}; + +[scriptable, builtinclass, uuid(7e1e1a20-b24f-11e4-ab27-0800200c9a66)] +interface nsIProcessScriptLoader : nsISupports +{ + /** + * Load a script in the (possibly remote) process. aURL must be the absolute URL. + * data: URLs are also supported. For example data:,dump("foo\n"); + * If aAllowDelayedLoad 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. + */ + void loadProcessScript(in AString aURL, in boolean aAllowDelayedLoad); + + /** + * Removes aURL from the list of scripts which support delayed load. + */ + void removeDelayedProcessScript(in AString aURL); + + /** + * Returns all delayed scripts that will be loaded once a (remote) + * frame becomes available. The return value is a list of URLs. + */ + [implicit_jscontext] + jsval getDelayedProcessScripts(); +}; + +[scriptable, builtinclass, uuid(5b390753-abb3-49b0-ae3b-b803dab58144)] +interface nsIGlobalProcessScriptLoader : nsIProcessScriptLoader +{ + /** + * 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. 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. + */ + [implicit_jscontext] + readonly attribute jsval initialProcessData; +}; + +[scriptable, builtinclass, uuid(637e8538-4f8f-4a3d-8510-e74386233e19)] +interface nsIProcessChecker : nsISupports +{ + bool killChild(); + + /** + * Return true if the "remote" process has |aPermission|. This is + * intended to be used by JS implementations of cross-process DOM + * APIs, like so + * + * recvFooRequest: function(message) { + * if (!message.target.assertPermission("foo")) { + * return false; + * } + * // service foo request + * + * This interface only returns meaningful data when our content is + * in a separate process. If it shares the same OS process as us, + * then applying this permission check doesn't add any security, + * though it doesn't hurt anything either. + * + * Note: If the remote content process does *not* have |aPermission|, + * it will be killed as a precaution. + */ + boolean assertPermission(in DOMString aPermission); + + /** + * Return true if the "remote" process has |aManifestURL|. This is + * intended to be used by JS implementations of cross-process DOM + * APIs, like so + * + * recvFooRequest: function(message) { + * if (!message.target.assertContainApp("foo")) { + * return false; + * } + * // service foo request + * + * This interface only returns meaningful data when our content is + * in a separate process. If it shares the same OS process as us, + * then applying this manifest URL check doesn't add any security, + * though it doesn't hurt anything either. + * + * Note: If the remote content process does *not* contain |aManifestURL|, + * it will be killed as a precaution. + */ + boolean assertContainApp(in DOMString aManifestURL); + + boolean assertAppHasPermission(in DOMString aPermission); + + /** + * Return true if the "remote" process' principal has an appStatus equal to + * |aStatus|. + * + * This interface only returns meaningful data when our content is + * in a separate process. If it shares the same OS process as us, + * then applying this permission check doesn't add any security, + * though it doesn't hurt anything either. + * + * Note: If the remote content process does *not* has the |aStatus|, + * it will be killed as a precaution. + */ + boolean assertAppHasStatus(in unsigned short aStatus); + +}; |