2002-10-31 11:19:27 +03:00
|
|
|
/* ***** BEGIN LICENSE BLOCK *****
|
|
|
|
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
|
|
*
|
|
|
|
* The contents of this file are subject to the Mozilla Public License Version
|
|
|
|
* 1.1 (the "License"); you may not use this file except in compliance with
|
|
|
|
* the License. You may obtain a copy of the License at
|
|
|
|
* http://www.mozilla.org/MPL/
|
|
|
|
*
|
|
|
|
* Software distributed under the License is distributed on an "AS IS" basis,
|
|
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
|
|
* for the specific language governing rights and limitations under the
|
|
|
|
* License.
|
|
|
|
*
|
|
|
|
* The Original Code is Mozilla IPC.
|
|
|
|
*
|
|
|
|
* The Initial Developer of the Original Code is
|
|
|
|
* Netscape Communications Corporation.
|
|
|
|
* Portions created by the Initial Developer are Copyright (C) 2002
|
|
|
|
* the Initial Developer. All Rights Reserved.
|
|
|
|
*
|
|
|
|
* Contributor(s):
|
|
|
|
* Darin Fisher <darin@netscape.com>
|
|
|
|
*
|
|
|
|
* Alternatively, the contents of this file may be used under the terms of
|
|
|
|
* either the GNU General Public License Version 2 or later (the "GPL"), or
|
|
|
|
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
|
|
* in which case the provisions of the GPL or the LGPL are applicable instead
|
|
|
|
* of those above. If you wish to allow use of your version of this file only
|
|
|
|
* under the terms of either the GPL or the LGPL, and not to allow others to
|
|
|
|
* use your version of this file under the terms of the MPL, indicate your
|
|
|
|
* decision by deleting the provisions above and replace them with the notice
|
|
|
|
* and other provisions required by the GPL or the LGPL. If you do not delete
|
|
|
|
* the provisions above, a recipient may use your version of this file under
|
|
|
|
* the terms of any one of the MPL, the GPL or the LGPL.
|
|
|
|
*
|
|
|
|
* ***** END LICENSE BLOCK ***** */
|
|
|
|
|
|
|
|
#include "nsISupports.idl"
|
|
|
|
|
|
|
|
interface nsISimpleEnumerator;
|
|
|
|
interface ipcIMessageObserver;
|
|
|
|
interface ipcIClientObserver;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* the IPC service provides the means to communicate with an external IPC
|
2002-11-05 22:42:22 +03:00
|
|
|
* 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.
|
2002-10-31 11:19:27 +03:00
|
|
|
*
|
|
|
|
* at application startup, the IPC service will attempt to establish a
|
2002-11-05 22:42:22 +03:00
|
|
|
* connection with the IPC daemon. the IPC daemon will be automatically
|
|
|
|
* started if necessary. when a connection has been established, the IPC
|
|
|
|
* service will broadcast an "ipc-startup" notification using the observer
|
|
|
|
* service.
|
2002-10-31 11:19:27 +03:00
|
|
|
*
|
2002-11-05 22:42:22 +03:00
|
|
|
* XXX startup category
|
|
|
|
*
|
|
|
|
* when the connection to the IPC daemon is closed, an "ipc-shutdown"
|
|
|
|
* notification will be broadcast.
|
2002-10-31 11:19:27 +03:00
|
|
|
*
|
|
|
|
* each client has a name. the client name need not be unique across all
|
2002-11-05 22:42:22 +03:00
|
|
|
* clients, but it is usually good if it is. the IPC service does not require
|
2002-10-31 11:19:27 +03:00
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
[scriptable, uuid(53d3e3a7-528f-4b09-9eab-9416272568c0)]
|
|
|
|
interface ipcIService : nsISupports
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* returns the "client ID" assigned to this application by the IPC daemon.
|
|
|
|
* this number is the name given to our application for the current
|
|
|
|
* session. after a profile change, our client ID will change.
|
|
|
|
*
|
|
|
|
* @throws NS_ERROR_NOT_AVAILABLE if no connection to the IPC daemon.
|
|
|
|
*/
|
|
|
|
readonly attribute unsigned long clientID;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* client aliases give the client a way to register itself under multiple
|
|
|
|
* names. for example, the mozilla browser might register itself under
|
|
|
|
* the name "mozilla", but it could also register itself under the aliases
|
|
|
|
* "browser", "mail", "news", "addrbook", and so on. aliases provide a
|
|
|
|
* simple mechanism for clients to discover other clients.
|
|
|
|
*/
|
|
|
|
void addClientAlias(in ACString aAlias);
|
|
|
|
void removeClientAlias(in ACString aAlias);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* query info about a particular client given its client name.
|
|
|
|
*
|
|
|
|
* @param aNameOrAlias name or alias of the client being queried.
|
|
|
|
* @param aObserver client observer to be notified.
|
|
|
|
*
|
|
|
|
* @return integer token identifying this request.
|
|
|
|
*/
|
|
|
|
unsigned long queryClientByName(in ACString aNameOrAlias,
|
|
|
|
in ipcIClientObserver aObserver);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* query info about a particular client given its client ID.
|
|
|
|
*
|
|
|
|
* @return integer token identifying this request.
|
|
|
|
*/
|
|
|
|
unsigned long queryClientByID(in unsigned long aClientID,
|
|
|
|
in ipcIClientObserver aObserver);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* set client observer. observer is notified whenever the status of
|
|
|
|
* a client changes.
|
|
|
|
*
|
|
|
|
* @param aClientID the ID of the client to observe.
|
|
|
|
* @param aObserver the client observer.
|
|
|
|
*/
|
|
|
|
void setClientObserver(in unsigned long aClientID,
|
|
|
|
in ipcIClientObserver aObserver);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* set a message observer for a particular message target.
|
|
|
|
*
|
|
|
|
* @param aTarget the message target being observed. any existing
|
|
|
|
* observer will be replaced.
|
|
|
|
* @param aObserver the message observer to receive incoming messages
|
|
|
|
* for the specified target. pass null to remove the
|
|
|
|
* existing observer.
|
|
|
|
*/
|
|
|
|
void setMessageObserver(in nsIDRef aTarget, in ipcIMessageObserver aObserver);
|
|
|
|
|
|
|
|
/**
|
2002-10-31 20:55:19 +03:00
|
|
|
* send message asynchronously to a client or a module in the IPC daemon.
|
|
|
|
* there is no guarantee that the message will be delivered.
|
2002-10-31 11:19:27 +03:00
|
|
|
*
|
|
|
|
* @param aClientID the client ID of the foreign application that should
|
2002-10-31 20:55:19 +03:00
|
|
|
* receive this message. pass 0 to send a message to a
|
|
|
|
* module in the IPC daemon.
|
|
|
|
* @param aTarget the target of the message. if aClientID is 0, then
|
|
|
|
* this is the ID of the daemon module that should
|
2002-10-31 11:19:27 +03:00
|
|
|
* receive this message.
|
2002-10-31 20:55:19 +03:00
|
|
|
* @param aData the message data.
|
|
|
|
* @param aDataLen the message length.
|
2002-10-31 11:19:27 +03:00
|
|
|
*/
|
2002-10-31 20:55:19 +03:00
|
|
|
[noscript] void sendMessage(in unsigned long aClientID,
|
|
|
|
in nsIDRef aTarget,
|
|
|
|
in string aData,
|
|
|
|
in unsigned long aDataLen);
|
2002-10-31 11:19:27 +03:00
|
|
|
};
|
|
|
|
|
|
|
|
[scriptable, uuid(e40a4a3c-2dc1-470e-ab7f-5675fe1f1384)]
|
|
|
|
interface ipcIMessageObserver : nsISupports
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* @param aTarget the target of the message, corresponding to the target
|
|
|
|
* this observer was registered under. this parameter is
|
|
|
|
* passed to allow an observer instance to receive
|
|
|
|
* messages for more than one target.
|
|
|
|
* @param aData the data of the message.
|
|
|
|
* @param aDataLen the data length of the message.
|
|
|
|
*/
|
|
|
|
[noscript] void onMessageAvailable(in nsIDRef aTarget,
|
|
|
|
in string aData,
|
|
|
|
in unsigned long aDataLen);
|
|
|
|
};
|
|
|
|
|
|
|
|
[scriptable, uuid(e858d450-62b2-482d-99bb-3b5425aa28cc)]
|
|
|
|
interface ipcIClientInfo : nsISupports
|
|
|
|
{
|
|
|
|
readonly attribute unsigned long ID;
|
|
|
|
readonly attribute ACString name;
|
|
|
|
readonly attribute nsISimpleEnumerator aliases;
|
|
|
|
readonly attribute nsISimpleEnumerator targets;
|
|
|
|
};
|
|
|
|
|
|
|
|
[scriptable, uuid(42283079-030c-4b13-b069-a08b7ad5eab2)]
|
|
|
|
interface ipcIClientObserver : nsISupports
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* client status values
|
|
|
|
*/
|
|
|
|
const unsigned long CLIENT_UP = 1;
|
|
|
|
const unsigned long CLIENT_DOWN = 2;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @param aRequestToken the request token returned from the call that
|
|
|
|
* initiated this observation. 0 if initiated
|
|
|
|
* from a setClientObserver call.
|
|
|
|
* @param aClientInfo client info.
|
|
|
|
* @param aStatus client status (e.g. CLIENT_UP).
|
|
|
|
*/
|
|
|
|
void onClientStatus(in unsigned long aRequestToken,
|
2002-11-05 22:42:22 +03:00
|
|
|
in unsigned long aStatus,
|
|
|
|
in ipcIClientInfo aClientInfo);
|
2002-10-31 11:19:27 +03:00
|
|
|
|
|
|
|
// XXX do we care about changes to the aliases and targets supported
|
|
|
|
// by a client? if so, how should we pass this information up?
|
|
|
|
};
|