nsISyncMessageSender

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

Inherits from: nsIMessageListenerManager

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.

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

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).

Methods

jsval sendSyncMessage([optional] in AString messageName,

                          [optional] in jsval obj,

                          [optional] in jsval objects,

                          [optional] in nsIPrincipal principal);

jsval sendRpcMessage([optional] in AString messageName,

                          [optional] in jsval obj,

                          [optional] in jsval objects,

                          [optional] in nsIPrincipal principal);

sendSyncMessage()

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.

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`

Returns

Array: an array of structured clones of the objects returned by all the listeners to this message, one element for each listener. If there was only one listener, it is an array with a single element.

sendRpcMessage()

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.

Parameters

Name	Type	Description
`messageName`	String	The name of the message. Optional. This becomes the `name` property of the received message.
`obj`	JSONable 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`