Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
ipcIService Interface Reference

ipcIService More...

import "ipcIService.idl";

Inheritance diagram for ipcIService:
Inheritance graph
[legend]
Collaboration diagram for ipcIService:
Collaboration graph
[legend]

List of all members.

Public Member Functions

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.

Public Attributes

readonly attribute unsigned long ID
 returns the "client ID" assigned to this process by the IPC daemon.

Detailed Description

ipcIService

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.

Definition at line 73 of file ipcIService.idl.


Member Function Documentation

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.

boolean ipcIService::clientExists ( in unsigned long  aClientID)

tests whether a particular client is connected to the IPC daemon.

void ipcIService::defineTarget ( in nsIDRef  aTarget,
in ipcIMessageObserver  aObserver,
in boolean  aOnCurrentThread 
)

set a message observer for a particular message target.

Parameters:
aTargetthe message target being observed. any existing observer will be replaced.
aObserverthe message observer to receive incoming messages for the specified target. pass null to remove the existing observer.
aOnCurrentThreadif 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,
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.

there is no guarantee that the message will be delivered.

Parameters:
aClientIDthe client ID of the foreign application that should receive this message. pass 0 to send a message to a module in the IPC daemon.
aTargetthe target of the message. if aClientID is 0, then this is the ID of the daemon module that should receive this message.
aDatathe message data.
aDataLenthe message length.
void ipcIService::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.

Parameters:
aSenderIDpass 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.
aTargetwait for a message to be delivered to this target.
aObserverthis observer's OnMessageAvailable method is called when a matching message is available. pass null to use the default observer associated with aTarget.
aTimeoutindicates maximum length of time in milliseconds that this function may block the calling thread.
Exceptions:
IPC_ERROR_WOULD_BLOCKif 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.


Member Data Documentation

readonly attribute unsigned long ipcIService::ID

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

Exceptions:
NS_ERROR_NOT_AVAILABLEif no connection to the IPC daemon.

Definition at line 84 of file ipcIService.idl.


The documentation for this interface was generated from the following file: