ipc/ipcd/daemon/public/ipcModule.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Mozilla IPC.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 2002
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Darin Fisher <darin@netscape.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef ipcModule_h__
  39 #define ipcModule_h__
  40
  41 #include "nsID.h"
  42
  43 //
  44 // a client handle is used to efficiently reference a client instance object
  45 // used by the daemon to represent a connection with a particular client app.
  46 //
  47 // modules should treat it as an opaque type.
  48 //
  49 typedef class ipcClient *ipcClientHandle;
  50
  51 //-----------------------------------------------------------------------------
  52 // interface implemented by the module:
  53 //-----------------------------------------------------------------------------
  54
  55 //
  56 // the version of ipcModuleMethods data structure.
  57 //
  58 #define IPC_MODULE_METHODS_VERSION (1<<16) // 1.0
  59
  60 //
  61 // each module defines the following structure:
  62 //
  63 struct ipcModuleMethods
  64 {
  65     //
  66     // this field holds the version of the data structure, which is always the
  67     // value of IPC_MODULE_METHODS_VERSION against which the module was built.
  68     //
  69     PRUint32 version;
  70
  71     //
  72     // called after this module is registered.
  73     //
  74     void (* init) (void);
  75
  76     //
  77     // called when this module will no longer be accessed.
  78     //
  79     void (* shutdown) (void);
  80
  81     //
  82     // called when a new message arrives for this module.
  83     //
  84     // params:
  85     //   client  - an opaque "handle" to an object representing the client that
  86     //             sent the message.  modules should not store the value of this
  87     //             beyond the duration fo this function call.  (e.g., the handle
  88     //             may be invalid after this function call returns.)  modules
  89     //             wishing to hold onto a reference to a "client" should store
  90     //             the client's ID (see IPC_GetClientID).
  91     //   target  - message target
  92     //   data    - message data
  93     //   dataLen - message data length
  94     //
  95     void (* handleMsg) (ipcClientHandle client,
  96                         const nsID     &target,
  97                         const void     *data,
  98                         PRUint32        dataLen);
  99
 100     //
 101     // called when a new client connects to the IPC daemon.
 102     //
 103     void (* clientUp) (ipcClientHandle client);
 104
 105     //
 106     // called when a client disconnects from the IPC daemon.
 107     //
 108     void (* clientDown) (ipcClientHandle client);
 109 };
 110
 111 //-----------------------------------------------------------------------------
 112 // interface implemented by the daemon:
 113 //-----------------------------------------------------------------------------
 114
 115 //
 116 // the version of ipcDaemonMethods data structure.
 117 //
 118 #define IPC_DAEMON_METHODS_VERSION (1<<16) // 1.0
 119
 120 //
 121 // enumeration functions may return FALSE to stop enumeration.
 122 //
 123 typedef PRBool (* ipcClientEnumFunc)       (void *closure, ipcClientHandle client, PRUint32 clientID);
 124 typedef PRBool (* ipcClientNameEnumFunc)   (void *closure, ipcClientHandle client, const char *name);
 125 typedef PRBool (* ipcClientTargetEnumFunc) (void *closure, ipcClientHandle client, const nsID &target);
 126
 127 //
 128 // the daemon provides the following structure:
 129 //
 130 struct ipcDaemonMethods
 131 {
 132     PRUint32 version;
 133
 134     //
 135     // called to send a message to another module.
 136     //
 137     // params:
 138     //   client  - identifies the client from which this message originated.
 139     //   target  - message target
 140     //   data    - message data
 141     //   dataLen - message data length
 142     //
 143     // returns:
 144     //   PR_SUCCESS if message was dispatched.
 145     //   PR_FAILURE if message could not be dispatched (possibly because
 146     //              no module is registered for the given message target).
 147     //
 148     PRStatus (* dispatchMsg) (ipcClientHandle client,
 149                               const nsID     &target,
 150                               const void     *data,
 151                               PRUint32        dataLen);
 152
 153     //
 154     // called to send a message to a particular client or to broadcast a
 155     // message to all clients.
 156     //
 157     // params:
 158     //   client  - if null, then broadcast message to all clients.  otherwise,
 159     //             send message to the client specified.
 160     //   target  - message target
 161     //   data    - message data
 162     //   dataLen - message data length
 163     //
 164     // returns:
 165     //   PR_SUCCESS if message was sent (or queued up to be sent later).
 166     //   PR_FAILURE if message could not be sent (possibly because the client
 167     //              does not have a registered observer for the msg's target).
 168     //
 169     PRStatus (* sendMsg) (ipcClientHandle client,
 170                           const nsID     &target,
 171                           const void     *data,
 172                           PRUint32        dataLen);
 173
 174     //
 175     // called to lookup a client handle given its client ID.  each client has
 176     // a unique ID.
 177     //
 178     ipcClientHandle (* getClientByID) (PRUint32 clientID);
 179
 180     //
 181     // called to lookup a client by name or alias.  names are not necessary
 182     // unique to individual clients.  this function returns the client first
 183     // registered under the given name.
 184     //
 185     ipcClientHandle (* getClientByName) (const char *name);
 186
 187     //
 188     // called to enumerate all clients.
 189     //
 190     void (* enumClients) (ipcClientEnumFunc func, void *closure);
 191
 192     //
 193     // returns the client ID of the specified client.
 194     //
 195     PRUint32 (* getClientID) (ipcClientHandle client);
 196
 197     //
 198     // functions for inspecting the names and targets defined for a particular
 199     // client instance.
 200     //
 201     PRBool (* clientHasName)     (ipcClientHandle client, const char *name);
 202     PRBool (* clientHasTarget)   (ipcClientHandle client, const nsID &target);
 203     void   (* enumClientNames)   (ipcClientHandle client, ipcClientNameEnumFunc func, void *closure);
 204     void   (* enumClientTargets) (ipcClientHandle client, ipcClientTargetEnumFunc func, void *closure);
 205 };
 206
 207 //-----------------------------------------------------------------------------
 208 // interface exported by a DSO implementing one or more modules:
 209 //-----------------------------------------------------------------------------
 210
 211 struct ipcModuleEntry
 212 {
 213     //
 214     // identifies the message target of this module.
 215     //
 216     nsID target;
 217
 218     //
 219     // module methods
 220     //
 221     ipcModuleMethods *methods;
 222 };
 223
 224 //-----------------------------------------------------------------------------
 225
 226 #define IPC_EXPORT extern "C" NS_EXPORT
 227
 228 //
 229 // IPC_EXPORT int IPC_GetModules(const ipcDaemonMethods *, const ipcModuleEntry **);
 230 //
 231 // params:
 232 //   methods - the daemon's methods
 233 //   entries - the module entries defined by the DSO
 234 //
 235 // returns:
 236 //   length of the |entries| array.
 237 //
 238 typedef int (* ipcGetModulesFunc) (const ipcDaemonMethods *methods, const ipcModuleEntry **entries);
 239
 240 #endif // !ipcModule_h__