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 <[email protected]>
|
---|
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__
|
---|