1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
/* ***** 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;
/**
* 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 ID;
/**
* 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 addName(in string aName);
void removeName(in string aName);
/**
* add a new observer of client status change notifications.
*/
void addClientObserver(in ipcIClientObserver aObserver);
/**
* remove an observer of client status change notifications.
*/
void removeClientObserver(in ipcIClientObserver aObserver);
/**************************************************************************
* client query methods
*/
/**
* resolve the given client name to the id of a connected client. this
* involves a round trip to the daemon, and as a result the calling thread
* may block on this function call while waiting for the daemon to respond.
*/
unsigned long resolveClientName(in string aName);
/**
* tests whether a particular client is connected to the IPC daemon.
*/
boolean clientExists(in unsigned long aClientID);
// XXX need other functions to enumerate clients, clients implementing targets, etc.
// enumerator getClients();
// enumerator getClientsSupportingTarget(in nsIDRef aTarget);
// enumerator getClientNames(in unsigned long aClientID);
// enumerator getClientTargets(in unsigned long aClientID);
/**************************************************************************
* 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.
* @param aOnCurrentThread
* if true, then the message observer will be called on the same
* thread that calls defineTarget. otherwise, aObserver will be
* called on a background thread.
*/
void defineTarget(in nsIDRef aTarget,
in ipcIMessageObserver aObserver,
in boolean aOnCurrentThread);
/**
* 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 aReceiverID,
in nsIDRef aTarget,
[array, const, size_is(aDataLen)]
in octet aData,
in unsigned long aDataLen);
/**
* block the calling thread until a matching message is received.
*
* @param aSenderID
* pass 0 to wait for a message from the daemon. pass PR_UINT32_MAX
* to wait for a message from any source. otherwise, pass a client
* id to wait for a message from that particular client.
* @param aTarget
* wait for a message to be delivered to this target.
* @param aObserver
* this observer's OnMessageAvailable method is called when a
* matching message is available. pass null to use the default
* observer associated with aTarget.
* @param aTimeout
* indicates maximum length of time in milliseconds that this
* function may block the calling thread.
*
* @throws IPC_ERROR_WOULD_BLOCK if the timeout expires.
*
* the observer's OnMessageAvailable method may throw IPC_WAIT_NEXT_MESSAGE
* to indicate that it does not wish to handle the message that it was
* given, and that it will wait to be called with the next message. this
* enables the observer to keep messages in the queue that do not match the
* desired message. messages that remain in the queue will be dispatched
* asynchronously to the default message handler after waitMessage finishes.
*
* NOTE: this function may hang the calling thread until a matching message
* is received, so use it with caution.
*/
void waitMessage(in unsigned long aSenderID,
in nsIDRef aTarget,
in ipcIMessageObserver aObserver,
in unsigned long aTimeout);
/**
* Call this method to disable the default message observer for a target.
*/
void disableMessageObserver(in nsIDRef aTarget);
/**
* Call this method to re-enable the default message observer for a target.
*/
void enableMessageObserver(in nsIDRef aTarget);
};
%{C++
// category and observer event defines (XXX not yet implemented)
#define IPC_SERVICE_STARTUP_CATEGORY "ipc-startup-category"
#define IPC_SERVICE_STARTUP_TOPIC "ipc-startup"
#define IPC_SERVICE_SHUTDOWN_TOPIC "ipc-shutdown"
%}
|
