ipcIService

IID:53d3e3a7-528f-4b09-9eab-9416272568c0
Inherits From:nsISupports

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.


Properties

readonly PRUint32 clientID

Returns the "client ID" assigned to this process by the IPC daemon.


Methods

void addClientName ( char* name ) void cancelQuery ( PRUint32 queryID ) PRUint32 queryClientByID ( PRUint32 clientID , ipcIClientQueryHandler handler , PRBool sync ) PRUint32 queryClientByName ( char* name , ipcIClientQueryHandler handler , PRBool sync ) void removeClientName ( char* name ) void sendMessage ( PRUint32 clientID , nsIDRef target , arrayof PRUint8 data , PRUint32 dataLen , PRBool sync ) void setClientObserver ( ipcIClientObserver observer ) void setMessageObserver ( nsIDRef target , ipcIMessageObserver observer )

void addClientName ( char* name )

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.

Arguments:
name

void cancelQuery ( PRUint32 queryID )

Called to cancel a pending query.

Arguments:
queryID: the return value from one of the "query" methods.

PRUint32 queryClientByID ( PRUint32 clientID , ipcIClientQueryHandler handler , PRBool sync )

Query info about a particular client given its client ID. the observer's onClientInfo method is called with the result of the lookup, or if there is no client matching the given name, the observer's onClientDown method will be called instead.

Arguments:
clientID: the ID of the client being queried.
handler: the handler to be notified with result.
sync: block the calling thread until the query completes.
Returns:
integer value identifying this query.

PRUint32 queryClientByName ( char* name , ipcIClientQueryHandler handler , PRBool sync )

Query info about a particular client given its client name. the observer's onClientInfo method is called with the result of the lookup, or if there is no client matching the given name, the observer's onClientDown method will be called instead.

Arguments:
name: the name of the client being queried.
handler: the handler to be notified with result.
sync: block the calling thread until the query completes.
Returns:
integer value identifying this query.

void removeClientName ( char* name )

Arguments:
name

void sendMessage ( PRUint32 clientID , nsIDRef target , arrayof PRUint8 data , PRUint32 dataLen , PRBool sync )

Send message asynchronously to a client or a module in the IPC daemon. there is no guarantee that the message will be delivered.

Arguments:
clientID: 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.
target: the target of the message. if clientID is 0, then this is the ID of the daemon module that should receive this message.
data: the message data.
dataLen: the message length.
sync: block the calling thread until a response to this message is received.

void setClientObserver ( ipcIClientObserver observer )

Set client observer. observer's onClientUp method is called whenever a new client comes online, and the observer's onClientDown method is called whenever a client goes offline.

Arguments:
observer: the client observer.

void setMessageObserver ( nsIDRef target , ipcIMessageObserver observer )

Set a message observer for a particular message target.

Arguments:
target: the message target being observed. any existing observer will be replaced.
observer: the message observer to receive incoming messages for the specified target. pass null to remove the existing observer.

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
No comments available
Add a note

Copyright © 1999 - 2005 XULPlanet.com