257 lines
9.8 KiB
Plaintext
257 lines
9.8 KiB
Plaintext
/* ***** 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 ipcIMessageObserver;
|
|
interface ipcIClientObserver;
|
|
interface ipcIClientQueryHandler;
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
[scriptable, uuid(53d3e3a7-528f-4b09-9eab-9416272568c0)]
|
|
interface ipcIService : nsISupports
|
|
{
|
|
/**
|
|
* returns the "client ID" assigned to this process by the IPC daemon.
|
|
*
|
|
* @throws NS_ERROR_NOT_AVAILABLE if no connection to the IPC daemon.
|
|
*/
|
|
readonly attribute unsigned long clientID;
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
void addClientName(in ACString aName);
|
|
void removeClientName(in ACString aName);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aName
|
|
* the name of the client being queried.
|
|
* @param aHandler
|
|
* the handler to be notified asynchronously of result.
|
|
*
|
|
* @return integer value identifying this query.
|
|
*/
|
|
unsigned long queryClientByName(in ACString aName,
|
|
in ipcIClientQueryHandler aHandler);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aClientID
|
|
* the ID of the client being queried.
|
|
* @param aHandler
|
|
* the handler to be notified asynchronously of result.
|
|
*
|
|
* @return integer value identifying this query.
|
|
*/
|
|
unsigned long queryClientByID(in unsigned long aClientID,
|
|
in ipcIClientQueryHandler aHandler);
|
|
|
|
/**
|
|
* called to cancel a pending query.
|
|
*
|
|
* @param aQueryID
|
|
* the return value from one of the "query" methods.
|
|
*/
|
|
void cancelQuery(in unsigned long aQueryID);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aObserver
|
|
* the client observer.
|
|
*/
|
|
void setClientObserver(in ipcIClientObserver aObserver);
|
|
|
|
// XXX need other functions to enumerate clients, clients implementing targets, etc.
|
|
|
|
/**
|
|
* 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);
|
|
|
|
/**
|
|
* send message asynchronously to a client or a module in the IPC daemon.
|
|
* there is no guarantee that the message will be delivered.
|
|
*
|
|
* @param 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.
|
|
* @param aTarget
|
|
* the target of the message. if aClientID is 0, then this is the
|
|
* ID of the daemon module that should receive this message.
|
|
* @param aData
|
|
* the message data.
|
|
* @param aDataLen
|
|
* the message length.
|
|
*/
|
|
void sendMessage(in unsigned long aClientID,
|
|
in nsIDRef aTarget,
|
|
[array, const, size_is(aDataLen)]
|
|
in octet aData,
|
|
in unsigned long aDataLen);
|
|
};
|
|
|
|
/**
|
|
* ipcIMessageObserver
|
|
*/
|
|
[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.
|
|
*/
|
|
void onMessageAvailable(in nsIDRef aTarget,
|
|
[array, const, size_is(aDataLen)]
|
|
in octet aData,
|
|
in unsigned long aDataLen);
|
|
};
|
|
|
|
/**
|
|
* ipcIClientObserver
|
|
*/
|
|
[scriptable, uuid(42283079-030c-4b13-b069-a08b7ad5eab2)]
|
|
interface ipcIClientObserver : nsISupports
|
|
{
|
|
const unsigned long CLIENT_UP = 1;
|
|
const unsigned long CLIENT_DOWN = 2;
|
|
|
|
void onClientStatus(in unsigned long aClientID,
|
|
in unsigned long aClientStatus);
|
|
};
|
|
|
|
/**
|
|
* ipcIClientQueryHandler
|
|
*
|
|
* the methods on this interface are called when the result of a client query
|
|
* becomes available.
|
|
*/
|
|
[scriptable, uuid(6fefea5c-f747-4bb0-972f-2a7b363a01db)]
|
|
interface ipcIClientQueryHandler : nsISupports
|
|
{
|
|
/**
|
|
* called on completion of a client query.
|
|
*
|
|
* @param aQueryID
|
|
* the return value from one of the "query" methods.
|
|
* @param aStatus
|
|
* the status of the query. if this is a failure code, then the
|
|
* query failed, otherwise the query succeeded. the value of this
|
|
* parameter explains the reason for any failure.
|
|
* @param aClientID
|
|
* ...
|
|
*/
|
|
void onQueryComplete(in unsigned long aQueryID,
|
|
in nsresult aStatus,
|
|
in unsigned long aClientID,
|
|
[array, size_is(aNameCount)]
|
|
in string aClientNames,
|
|
in unsigned long aNameCount,
|
|
[array, const, size_is(aTargetCount)]
|
|
in nsIDPtr aClientTargets,
|
|
in unsigned long aTargetCount);
|
|
};
|
|
|
|
%{C++
|
|
#define IPC_SERVICE_STARTUP_CATEGORY "ipc-startup-category"
|
|
#define IPC_SERVICE_STARTUP_TOPIC "ipc-startup"
|
|
#define IPC_SERVICE_SHUTDOWN_TOPIC "ipc-shutdown"
|
|
|
|
#define IPC_SERVICE_PREF_PRIMARY_CLIENT_NAME "ipc.primary-client-name"
|
|
%}
|