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
229
230
231
232
233
234
235
236
237
238
239
|
/* ***** 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 Transaction Manager.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corp.
* Portions created by the Initial Developer are Copyright (C) 2003
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* John Gaunt <jgaunt@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 ***** */
// from tmTransactionManager.h
//
// XXX documentation needs work
//////////////////////////////////////////////////////////////////////////////
// Overview of TransactionManager IPC Module
//
// Classes:
// tmIPCModule - From the tmTransactionManager's point of view, this
// is a proxy for the IPC daemon itself. The reverse is true
// from the daemon's point of view. This is an interface for the
// Transaction system to work with the IPC daemon as its transport
// layer.
// tmTransactionManager (TM) - Manages the different queues. Maintains
// the queues neccessary for different clients. Receives messages
// from the tmIPCModule and passes message to the IPC daemon through
// the tmIPCModule.
// tmQueue - this class manages the transactions for the different areas
// of the profiles being shared. Broken down by functional area there
// will be a queue for prefs, cookies etc, but not for profileA and
// profileB, and not for pref_delete, pref_create, pref_change etc...
// tmTransaction - the actual transaction being shared with the different
// tmClients. It contains the type of transaction, which will equate with
// a type of queue in existance, the owner of the transaction (an IPC daemon ID)
// and the actual text message to be shared.
//
//////////////////////////////////////////////////////////////////////////////
/// XXX some docs that need to be put somewhere:
//
// from tmqueue.cpp
// Docs - note that the status of the TM_ATTACH_REPLY is only for checking
// for TM_ERROR_FAILURE. Other numbers have no importance
// success of the status means the NS_ERROR_GET_CODE(status) will
// yield the index of the listener.
//
// move to documentation page - from tmqueue.h
//
// a queue is specific to profile
//
// UUID going out from the module is a handler in the client
// (will go to the XPCOM service impling that UUID)
// -- does it make sense to have different UUIDs for cookies/prefs/etc
//
#include "nsISupports.idl"
interface ipcITransactionObserver;
[scriptable, uuid(15561efb-8c58-4a47-813a-fa91cf730895)]
interface ipcITransactionService : nsISupports
{
/**
* Connects the application to the transaction manager, defines the
* namespace and initializes internal storage
*
* @param aNamespace
* A string defining the scope of the transaction domains. It is
* used internally to seperate process listening to the same domain
* (ie. preferences) but for two different namespaces (ie. profile1 vs
* profile2).
*
* @returns NS_OK if all memory allocated properly and the IPC service was
* reached and attached to successfully.
*
* @returns an NS_ERROR_<foo> code specific to the failure otherwise
*/
void init(in ACString aNamespace);
/**
* Links the observer passed in with the domain specified. This will allow
* the observer to post transactions dealing with this domain as well as
* receive transactions posted by other applications observing this
* domain.
*
* Return codes for this method confer information about the success of
* this call, not of the actual attaching of the observer to the domain.
* (except the TM_ERROR code - which means the observer can not attach)
* If the attach is successful the observer will have its OnAttachReply
* method called before this method returns.
*
* Note: This call is synchronous and will not return until the call to
* OnAttachReply is made.
*
* @param aDomainName
* the name of the domain, in the current namespace, to listen for
* transactions from. i.e. cookies
*
* @param aObserver
* this will be used to notify the application when transactions
* and messages come in.
*
* @param aLockingCall
* Have the Transaction Sevice acquire a lock based on the domain
* before attaching. This should be used when persistant storage
* is being used to prevent data corruption.
*
* @returns NS_OK if the attach message was sent to the Transaction Manager.
*
* @returns an NS_ERROR_<foo> code specific to the failure otherwise
*
* @returns TM_ERROR_QUEUE_EXISTS if the queue already exists which means
* someone has already attached to it.
*/
void attach(in ACString aDomainName,
in ipcITransactionObserver aObserver,
in PRBool aLockingCall);
/**
* Sends a detach message to the Transaction Manager to unlink the observer
* associated with the domain passed in.
*
* As in attach, return codes do not indicate success of detachment. The
* observer will have it's OnDetach method called if it is successfully
* detached.
*
* Note: This call is an asynchronous call.
*
* @param aDomainName
* the domain, in the current namespace, from which the client
* should be removed.
*
* @returns NS_OK if the detach message is sent to the Transaction Manager
*
* @returns NS_ERROR_FAILURE is something goes wrong
*
* @returns NS_ERRROR_UNEXPECTD if the domain does not have an observer
* attached
*/
void detach(in ACString aDomainName);
/**
* Sends a flush message to the Transaction Manager to remove all
* transactions for the domain. After this call there will be no
* transactions in the Transaction Manager for the namespace/domain
* pairing. It is up to the application to coordinate the flushing
* of the Transaction Manager with the writing of data to files,
* if needed.
*
* Note: This call is synchronous and will not return until the call to
* OnFlushReply is made.
*
* @param aDomainName
* The domain, in the current namespace, to flush.
*
* @param aLockingCall
* Have the Transaction Sevice acquire a lock based on the domain
* before flushing. This should be used when persistant storage
* is being used to prevent data corruption.
*
* @returns NS_OK if the flush message is sent to the Transaction Manager
*
* @returns NS_ERROR_FAILURE is something goes wrong
*
* @returns NS_ERRROR_UNEXPECTD if the domain does not have an observer
* attached
*/
void flush(in ACString aDomainName, in PRBool aLockingCall);
/**
* Send the data to the Transaction Manager to be broadcast to any
* applications that have registered as observers of this particular
* namespace/domain pairing.
*
* If this domain is not being observed (attach has not been called for
* this domain) the message is queued until the attach is made and then
* the message is sent to the Transaction Manager with the proper domain
* information.
*
* XXXjg - this may not be neccessary with the synch attach call.
*
* Note: This call is an asynchronous call.
*
* @param aDomainName
* the domain, in the current namespace, to which the data will be
* sent.
*
* @param aData
* The actual data to be sent.
*
* @param aDataLen
* The length of the data argument
*/
void postTransaction(in ACString aDomainName,
[array, const, size_is(aDataLen)]
in octet aData,
in unsigned long aDataLen);
};
%{C++
// singleton implementing ipcITransactionService
#define IPC_TRANSACTIONSERVICE_CLASSNAME \
"tmTransactionService"
#define IPC_TRANSACTIONSERVICE_CONTRACTID \
"@mozilla.org/ipc/transaction-service;1"
#define IPC_TRANSACTIONSERVICE_CID \
{ /* 1403adf4-94d1-4c67-a8ae-d9f86972d378 */ \
0x1403adf4, \
0x94d1, \
0x4c67, \
{0xa8, 0xae, 0xd9, 0xf8, 0x69, 0x72, 0xd3, 0x78} \
}
%}
|
