pjs/ipc/ipcd/client/public/ipcIService.idl

/* ***** 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
{
    /**************************************************************************
     * properties of this process
     */

    /**
     * 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 string aName);
    void removeClientName(in string aName);


    /**************************************************************************
     * client query methods
     */

    /**
     * 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 with result.
     * @param aSync
     *        block the calling thread until the query completes.
     *
     * @return integer value identifying this query.
     */
    unsigned long queryClientByName(in string                 aName,
                                    in ipcIClientQueryHandler aHandler,
                                    in boolean                aSync);

    /**
     * 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 with result.
     * @param aSync
     *        block the calling thread until the query completes.
     *
     * @return integer value identifying this query.
     */
    unsigned long queryClientByID(in unsigned long          aClientID,
                                  in ipcIClientQueryHandler aHandler,
                                  in boolean                aSync);

    /**
     * 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.


    /**************************************************************************
     * message methods
     */

    /**
     * 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.
     * @param aSync
     *        block the calling thread until a response to this message is
     *        received.
     */
    void sendMessage(in unsigned long aClientID,
                     in nsIDRef       aTarget,
                    [array, const, size_is(aDataLen)]
                     in octet         aData,
                     in unsigned long aDataLen,
                     in boolean       aSync);
};

%{C++
// singleton implementing ipcIService
#define IPC_SERVICE_CLASSNAME \
    "ipcService"
#define IPC_SERVICE_CONTRACTID \
    "@mozilla.org/ipc/service;1"
#define IPC_SERVICE_CID                              \
{ /* 9f12676a-5168-4a08-beb8-edf8a593a1ca */         \
    0x9f12676a,                                      \
    0x5168,                                          \
    0x4a08,                                          \
    {0xbe, 0xb8, 0xed, 0xf8, 0xa5, 0x93, 0xa1, 0xca} \
}

// category and observer event defines
#define IPC_SERVICE_STARTUP_CATEGORY "ipc-startup-category"
#define IPC_SERVICE_STARTUP_TOPIC    "ipc-startup"
#define IPC_SERVICE_SHUTDOWN_TOPIC   "ipc-shutdown"
%}