Back to index
|void||addName (in string aName)|
|this process can appear under several client names. |
|void||removeName (in string aName)|
|void||addClientObserver (in ipcIClientObserver aObserver)|
|add a new observer of client status change notifications. |
|void||removeClientObserver (in ipcIClientObserver aObserver)|
|remove an observer of client status change notifications. |
|unsigned long||resolveClientName (in string aName)|
|resolve the given client name to the id of a connected client. |
|boolean||clientExists (in unsigned long aClientID)|
|tests whether a particular client is connected to the IPC daemon. |
|void||defineTarget (in nsIDRef aTarget, in ipcIMessageObserver aObserver, in boolean aOnCurrentThread)|
|set a message observer for a particular message target. |
|void||sendMessage (in unsigned long aReceiverID, in nsIDRef aTarget,[array, const, size_is(aDataLen)] in octet aData, in unsigned long aDataLen)|
|send message asynchronously to a client or a module in the IPC daemon. |
|void||waitMessage (in unsigned long aSenderID, in nsIDRef aTarget, in ipcIMessageObserver aObserver, in unsigned long aTimeout)|
|block the calling thread until a matching message is received. |
|void||disableMessageObserver (in nsIDRef aTarget)|
|Call this method to disable the default message observer for a target. |
|void||enableMessageObserver (in nsIDRef aTarget)|
|Call this method to re-enable the default message observer for a target. |
|readonly attribute unsigned long||ID|
|returns the "client ID" assigned to this process by the IPC daemon. |
the IPC service provides the means to communicate with an external IPC daemon and/or other mozilla-based applications on the same physical system. the IPC daemon hosts modules (some builtin and others dynamically loaded) with which applications may interact.
at application startup, the IPC service will attempt to establish a connection with the IPC daemon. the IPC daemon will be automatically started if necessary. when a connection has been established, the IPC service will enumerate the "ipc-startup-category" and broadcast an "ipc-startup" notification using the observer service.
when the connection to the IPC daemon is closed, an "ipc-shutdown" notification will be broadcast.
each client has a name. the client name need not be unique across all clients, but it is usually good if it is. the IPC service does not require unique names. instead, the IPC daemon assigns each client a unique ID that is good for the current "session." clients can query other clients by name or by ID. the IPC service supports forwarding messages from one client to another via the IPC daemon.
for performance reasons, this system should not be used to transfer large amounts of data. instead, applications may choose to utilize shared memory, and rely on the IPC service for synchronization and small message transfer only.
add a new observer of client status change notifications.
this process can appear under several client names.
use the following methods to add or remove names for this process.
for example, the mozilla browser might have the primary name "mozilla", but it could also register itself under the names "browser", "mail", "news", "addrbook", etc. other IPC clients can then query the IPC daemon for the client named "mail" in order to talk with a mail program.
XXX An IPC client name resembles a XPCOM contract ID.
tests whether a particular client is connected to the IPC daemon.
|void ipcIService::defineTarget||(||in nsIDRef||aTarget,|
set a message observer for a particular message target.
|aTarget||the message target being observed. any existing observer will be replaced.|
|aObserver||the message observer to receive incoming messages for the specified target. pass null to remove the existing observer.|
|aOnCurrentThread||if true, then the message observer will be called on the same thread that calls defineTarget. otherwise, aObserver will be called on a background thread.|
Call this method to disable the default message observer for a target.
Call this method to re-enable the default message observer for a target.
remove an observer of client status change notifications.
resolve the given client name to the id of a connected client.
this involves a round trip to the daemon, and as a result the calling thread may block on this function call while waiting for the daemon to respond.
|void ipcIService::sendMessage||(||in unsigned long||aReceiverID,|
|[array, const, size_is(aDataLen)] in octet||aData,|
|in unsigned long||aDataLen|
send message asynchronously to a client or a module in the IPC daemon.
there is no guarantee that the message will be delivered.
|aClientID||the client ID of the foreign application that should receive this message. pass 0 to send a message to a module in the IPC daemon.|
|aTarget||the target of the message. if aClientID is 0, then this is the ID of the daemon module that should receive this message.|
|aData||the message data.|
|aDataLen||the message length.|
|void ipcIService::waitMessage||(||in unsigned long||aSenderID,|
|in unsigned long||aTimeout|
block the calling thread until a matching message is received.
|aSenderID||pass 0 to wait for a message from the daemon. pass PR_UINT32_MAX to wait for a message from any source. otherwise, pass a client id to wait for a message from that particular client.|
|aTarget||wait for a message to be delivered to this target.|
|aObserver||this observer's OnMessageAvailable method is called when a matching message is available. pass null to use the default observer associated with aTarget.|
|aTimeout||indicates maximum length of time in milliseconds that this function may block the calling thread.|
|IPC_ERROR_WOULD_BLOCK||if the timeout expires.|
the observer's OnMessageAvailable method may throw IPC_WAIT_NEXT_MESSAGE to indicate that it does not wish to handle the message that it was given, and that it will wait to be called with the next message. this enables the observer to keep messages in the queue that do not match the desired message. messages that remain in the queue will be dispatched asynchronously to the default message handler after waitMessage finishes.
NOTE: this function may hang the calling thread until a matching message is received, so use it with caution.