IDL file: mozilla-central/source/dom/base/nsIMessageManager.idl

Inherits from: nsIMessageListenerManager

Message senders enable clients to send asynchronous messages to a single "other side". For example, a child-process message manager will send messages that are only delivered to its one parent-process message manager.

To send messages to multiple "other sides", you would use nsIMessageBroadcaster.

See Message Manager interfaces for more details on the distinction between message senders and message broadcasters.

Methods

void sendAsyncMessage([optional] in AString messageName,
                      [optional] in jsval obj,
                      [optional] in jsval objects,
                      [optional] in nsIPrincipal principal);

sendAsyncMessage()

Send messageName and obj to the "other side" of this message manager. This invokes listeners who registered for messageName using a nsIMessageListenerManager.

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.

Parameters

Name Type Description
messageName String

The name of the message. Optional.

This becomes the name property of the received message.

obj Object.

The message payload.

A structured clone of this becomes the data property of the received message.

objects Object.

An object each of whose properties is an object.

This becomes the objects property of the received message, with each original object replaced with a cross process object wrapper for it.

principal nsIPrincipal