Message manager overview

There's a single global frame message manager in the chrome process.

This operates on all frames, in all content tabs. If you load a frame script using the global frame message manager, the script gets loaded separately into every open tab: three times, in the diagram above. Similarly, if you send a message using the global frame message manager, it's received by all content tabs, and is then delivered to any frame scripts that are listening for it.

Its most important functions and attributes are:

childCount : contains the number of children (typically, browser windows)

getChildAt() : get the child at the given index

loadFrameScript() : load a frame script into every tab in the browser

broadcastAsyncMessage() : send a message to frame scripts

addMessageListener() : start listening to a specific message from all frame scripts

removeMessageListener() : stop listening to a specific message

nsIFrameScriptLoader

nsIMessageListenerManager

nsIMessageBroadcaster

Access it using Components.classes:

// chrome script
let globalMM = Cc["@mozilla.org/globalmessagemanager;1"]
  .getService(Ci.nsIMessageListenerManager);

You can also access it as the mm property of Services.jsm, if you are in the parent process.

There's a window message manager for every browser window: two, in the diagram above.

It operates on all content tabs in a given window. If you load a frame script using the window message manager it gets loaded separately into each tab open in that particular window. If you send a message using the window message manager, it gets sent to all content tabs in that window.

Its most important functions and attributes are:

childCount : contains the number of children (typically, browser tabs)

getChildAt() : get the child at the given index

loadFrameScript() : load a frame script into every tab in this window

broadcastAsyncMessage() : send a message to all frame scripts in this window

addMessageListener() : start listening to a specific message from frame scripts

removeMessageListener() : stop listening to a specific message

nsIFrameScriptLoader

nsIMessageListenerManager

nsIMessageBroadcaster

You can access it as a property of the browser window:

// chrome script
let windowMM = window.messageManager;

Finally, there's a browser message manager for every open content tab: three, in the diagram above.

This corresponds one-to-one with a content tab. Scripts you load using a browser message manager are loaded only into that content tab, and messages you send are delivered only to that content tab.

You can mix and match: so for example, you could load a script into every tab using the global message manager, but then send a message to the script instance loaded into a specific tab by using the browser message manager.

Its most important functions are:

loadFrameScript() : load a frame script into this browser frame (tab)

sendAsyncMessage() : send a message to all frame scripts in this browser frame

addMessageListener() : start listening to a specific message from frame scripts

removeMessageListener() : stop listening to a specific message

nsIProcessChecker

nsIFrameScriptLoader

nsIMessageListenerManager

nsIMessageSender

The browser message manager can be accessed as a property of the XUL <browser> element:

// chrome script
let browserMM = gBrowser.selectedBrowser.messageManager;

There's a content frame message manager for every open tab. It's the content-side end of frame message manager conversations.

Frame scripts are loaded into the content frame message manager scope, and messages from chrome message managers end up here.

The content frame message manager provides the global object for frame scripts (but note that there is trickery to ensure that top-level variables defined by frame scripts are not shared).

Frame scripts can use this object to send messages to the chrome process, and to receive messages from the chrome process.

Its most important attributes and functions are:

content : access the DOM window hosted by the tab

docShell : access the top-level docshell

Components : access privileged objects and APIs

addEventListener() : listen to DOM events

addMessageListener() : receive messages from the chrome process

sendAsyncMessage() : send asynchronous messages to the chrome process

sendSyncMessage() : send synchronous messages to the chrome process

nsIDOMEventTarget

nsIMessageListenerManager

nsIMessageSender

nsISyncMessageSender

nsIContentFrameMessageManager

The global parent process message manager (GPPMM) is global to the parent process.

• Messages sent using the GPPMM get sent to all CPMMs in all child processes.
• Process scripts loaded using the GPPMM get loaded in all child processes.

Its most important functions and attributes are:

childCount : contains the number of children (child processes, plus the in-content child)

getChildAt() : get the child at the given index

loadProcessScript() : load a process script into every content process

broadcastAsyncMessage() : send a message to all process scripts

addMessageListener() : start listening to a specific message from process scripts

removeMessageListener() : stop listening to a specific message

nsIProcessScriptLoader

nsIMessageListenerManager

nsIMessageBroadcaster

You can access the GPPMM with code like this:

// parent process
let ppmm = Cc["@mozilla.org/parentprocessmessagemanager;1"]
           .getService(Ci.nsIMessageBroadcaster);

You can also access it as the ppmm property of Services.jsm, if you are in the parent process.

There's one parent process message manager (PPMM) in the parent process for every child process, and its API is oriented to that one child process.

• Messages sent using the PPMM are received only by the corresponding CPMM
• Scripts loaded using the PPMM are loaded only into the corresponding child process.

Its most important functions are:

loadProcessScript() : load a process script into the content process

broadcastAsyncMessage() : send a message to process scripts

addMessageListener() : start listening to a specific message from process scripts

removeMessageListener() : stop listening to a specific message

nsIProcessChecker

nsIProcessScriptLoader

nsIMessageListenerManager

nsIMessageSender

You can access a PPMM using the getChildAt() function in the GPPMM:

// parent process
let ppmm = Services.ppmm.getChildAt(1);

There's one child process message manager (CPMM) in each child process. Messages sent using the CPMM are sent to the corresponding PPMM and are also relayed to the GPPMM.

Its most important attributes and functions are:

Components : access privileged objects and APIs

addMessageListener() : receive messages from the parent process

sendAsyncMessage() : send asynchronous messages to the parent process

sendSyncMessage() : send synchronous messages to the parent process

nsIMessageListenerManager

nsIMessageSender

nsISyncMessageSender

nsIContentProcessMessageManager

Code running in a child process can access the CPMM with code like this:

// child process script
let cpmm = Cc["@mozilla.org/childprocessmessagemanager;1"]
           .getService(Ci.nsISyncMessageSender);

You can also access it as the cpmm property of Services.jsm, if you are in the child process.