Back to index

lightning-sunbird  0.9+nobinonly
ipcModule.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is Mozilla IPC.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 2002
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *   Darin Fisher <darin@netscape.com>
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef ipcModule_h__
00039 #define ipcModule_h__
00040 
00041 #include "nsID.h"
00042 
00043 //
00044 // a client handle is used to efficiently reference a client instance object
00045 // used by the daemon to represent a connection with a particular client app.
00046 //
00047 // modules should treat it as an opaque type.
00048 //
00049 typedef class ipcClient *ipcClientHandle;
00050 
00051 //-----------------------------------------------------------------------------
00052 // interface implemented by the module:
00053 //-----------------------------------------------------------------------------
00054 
00055 //
00056 // the version of ipcModuleMethods data structure.
00057 //
00058 #define IPC_MODULE_METHODS_VERSION (1<<16) // 1.0
00059 
00060 //
00061 // each module defines the following structure:
00062 //
00063 struct ipcModuleMethods
00064 {
00065     //
00066     // this field holds the version of the data structure, which is always the
00067     // value of IPC_MODULE_METHODS_VERSION against which the module was built.
00068     //
00069     PRUint32 version;
00070 
00071     //
00072     // called after this module is registered.
00073     //
00074     void (* init) (void);
00075 
00076     //
00077     // called when this module will no longer be accessed.
00078     //
00079     void (* shutdown) (void);
00080 
00081     //
00082     // called when a new message arrives for this module.
00083     //
00084     // params:
00085     //   client  - an opaque "handle" to an object representing the client that
00086     //             sent the message.  modules should not store the value of this
00087     //             beyond the duration fo this function call.  (e.g., the handle
00088     //             may be invalid after this function call returns.)  modules
00089     //             wishing to hold onto a reference to a "client" should store
00090     //             the client's ID (see IPC_GetClientID).
00091     //   target  - message target
00092     //   data    - message data
00093     //   dataLen - message data length
00094     //
00095     void (* handleMsg) (ipcClientHandle client,
00096                         const nsID     &target,
00097                         const void     *data,
00098                         PRUint32        dataLen);
00099 
00100     //
00101     // called when a new client connects to the IPC daemon.
00102     //
00103     void (* clientUp) (ipcClientHandle client);
00104 
00105     //
00106     // called when a client disconnects from the IPC daemon.
00107     //
00108     void (* clientDown) (ipcClientHandle client);
00109 };
00110 
00111 //-----------------------------------------------------------------------------
00112 // interface implemented by the daemon:
00113 //-----------------------------------------------------------------------------
00114 
00115 //
00116 // the version of ipcDaemonMethods data structure.
00117 //
00118 #define IPC_DAEMON_METHODS_VERSION (1<<16) // 1.0
00119 
00120 //
00121 // enumeration functions may return FALSE to stop enumeration.
00122 //
00123 typedef PRBool (* ipcClientEnumFunc)       (void *closure, ipcClientHandle client, PRUint32 clientID);
00124 typedef PRBool (* ipcClientNameEnumFunc)   (void *closure, ipcClientHandle client, const char *name);
00125 typedef PRBool (* ipcClientTargetEnumFunc) (void *closure, ipcClientHandle client, const nsID &target);
00126 
00127 //
00128 // the daemon provides the following structure:
00129 //
00130 struct ipcDaemonMethods
00131 {
00132     PRUint32 version;
00133 
00134     //
00135     // called to send a message to another module.
00136     //
00137     // params:
00138     //   client  - identifies the client from which this message originated.
00139     //   target  - message target
00140     //   data    - message data
00141     //   dataLen - message data length
00142     //
00143     // returns:
00144     //   PR_SUCCESS if message was dispatched.
00145     //   PR_FAILURE if message could not be dispatched (possibly because
00146     //              no module is registered for the given message target).
00147     //
00148     PRStatus (* dispatchMsg) (ipcClientHandle client, 
00149                               const nsID     &target,
00150                               const void     *data,
00151                               PRUint32        dataLen);
00152 
00153     //
00154     // called to send a message to a particular client or to broadcast a
00155     // message to all clients.
00156     //
00157     // params:
00158     //   client  - if null, then broadcast message to all clients.  otherwise,
00159     //             send message to the client specified.
00160     //   target  - message target
00161     //   data    - message data
00162     //   dataLen - message data length
00163     //
00164     // returns:
00165     //   PR_SUCCESS if message was sent (or queued up to be sent later).
00166     //   PR_FAILURE if message could not be sent (possibly because the client
00167     //              does not have a registered observer for the msg's target).
00168     //
00169     PRStatus (* sendMsg) (ipcClientHandle client,
00170                           const nsID     &target,
00171                           const void     *data,
00172                           PRUint32        dataLen);
00173 
00174     //
00175     // called to lookup a client handle given its client ID.  each client has
00176     // a unique ID.
00177     //
00178     ipcClientHandle (* getClientByID) (PRUint32 clientID);
00179 
00180     //
00181     // called to lookup a client by name or alias.  names are not necessary
00182     // unique to individual clients.  this function returns the client first
00183     // registered under the given name.
00184     //
00185     ipcClientHandle (* getClientByName) (const char *name);
00186 
00187     //
00188     // called to enumerate all clients.
00189     //
00190     void (* enumClients) (ipcClientEnumFunc func, void *closure);
00191 
00192     //
00193     // returns the client ID of the specified client.
00194     //
00195     PRUint32 (* getClientID) (ipcClientHandle client);
00196 
00197     //
00198     // functions for inspecting the names and targets defined for a particular
00199     // client instance.
00200     //
00201     PRBool (* clientHasName)     (ipcClientHandle client, const char *name);
00202     PRBool (* clientHasTarget)   (ipcClientHandle client, const nsID &target);
00203     void   (* enumClientNames)   (ipcClientHandle client, ipcClientNameEnumFunc func, void *closure);
00204     void   (* enumClientTargets) (ipcClientHandle client, ipcClientTargetEnumFunc func, void *closure);
00205 };
00206 
00207 //-----------------------------------------------------------------------------
00208 // interface exported by a DSO implementing one or more modules:
00209 //-----------------------------------------------------------------------------
00210 
00211 struct ipcModuleEntry
00212 {
00213     //
00214     // identifies the message target of this module.
00215     //
00216     nsID target;
00217 
00218     //
00219     // module methods
00220     //
00221     ipcModuleMethods *methods;
00222 };
00223 
00224 //-----------------------------------------------------------------------------
00225 
00226 #define IPC_EXPORT extern "C" NS_EXPORT
00227 
00228 //
00229 // IPC_EXPORT int IPC_GetModules(const ipcDaemonMethods *, const ipcModuleEntry **);
00230 //
00231 // params:
00232 //   methods - the daemon's methods
00233 //   entries - the module entries defined by the DSO
00234 //
00235 // returns:
00236 //   length of the |entries| array.
00237 //
00238 typedef int (* ipcGetModulesFunc) (const ipcDaemonMethods *methods, const ipcModuleEntry **entries);
00239 
00240 #endif // !ipcModule_h__