Mercurial > pidgin
comparison src/protocols/sametime/meanwhile/mw_channel.h @ 10969:3ef77720e577
[gaim-migrate @ 12790]
importing meanwhile library for use in the sametime plugin
committer: Tailor Script <tailor@pidgin.im>
author | Christopher O'Brien <siege@pidgin.im> |
---|---|
date | Sun, 05 Jun 2005 02:50:13 +0000 |
parents | |
children | 0110fc7c6a8a |
comparison
equal
deleted
inserted
replaced
10968:e0d5038fbb7e | 10969:3ef77720e577 |
---|---|
1 | |
2 /* | |
3 Meanwhile - Unofficial Lotus Sametime Community Client Library | |
4 Copyright (C) 2004 Christopher (siege) O'Brien | |
5 | |
6 This library is free software; you can redistribute it and/or | |
7 modify it under the terms of the GNU Library General Public | |
8 License as published by the Free Software Foundation; either | |
9 version 2 of the License, or (at your option) any later version. | |
10 | |
11 This library is distributed in the hope that it will be useful, | |
12 but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 Library General Public License for more details. | |
15 | |
16 You should have received a copy of the GNU Library General Public | |
17 License along with this library; if not, write to the Free | |
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
19 */ | |
20 | |
21 #ifndef _MW_CHANNEL_H | |
22 #define _MW_CHANNEL_H | |
23 | |
24 | |
25 #include <time.h> | |
26 #include "mw_common.h" | |
27 | |
28 | |
29 /** @file channel.h | |
30 | |
31 Life-cycle of an outgoing channel: | |
32 | |
33 1: mwChannel_new is called. If there is a channel in the outgoing | |
34 collection in state NEW, then it is returned. Otherwise, a channel | |
35 is allocated, assigned a unique outgoing id, marked as NEW, and | |
36 returned. | |
37 | |
38 2: channel is set to INIT status (effectively earmarking it as in- | |
39 use). fields on the channel can then be set as necessary to | |
40 prepare it for creation. | |
41 | |
42 3: mwChannel_create is called. The channel is marked to WAIT status | |
43 and a message is sent to the server. The channel is also marked as | |
44 inactive as of that moment. | |
45 | |
46 4: the channel is accepted (step 5) or rejected (step 7) | |
47 | |
48 5: an accept message is received from the server, and the channel | |
49 is marked as OPEN, and the inactive mark is removed. And messages | |
50 in the in or out queues for that channel are processed. The channel | |
51 is now ready to be used. | |
52 | |
53 6: data is sent and received over the channel | |
54 | |
55 7: the channel is closed either by receipt of a close message or by | |
56 local action. If by local action, then a close message is sent to | |
57 the server. The channel is cleaned up, its queues dumped, and it | |
58 is set to NEW status to await re-use. | |
59 | |
60 Life-cycle of an incoming channel: | |
61 | |
62 1: a channel create message is received. A channel is allocated and | |
63 given an id matching the message. It is placed in status WAIT, and | |
64 marked as inactive as of that moment. The service matching that | |
65 channel is alerted of the incoming creation request. | |
66 | |
67 2: the service can either accept (step 3) or reject (step 5) the | |
68 channel | |
69 | |
70 3: mwChannel_accept is called. The channel is marked as OPEN, and | |
71 an accept message is sent to the server. And messages in the in or | |
72 out queues for that channel are processed. The channel is now ready | |
73 to be used. | |
74 | |
75 4: data is sent and received over the channel | |
76 | |
77 5: The channel is closed either by receipt of a close message or by | |
78 local action. If by local action, then a close message is sent to | |
79 the server. The channel is cleaned up, its queues dumped, and it | |
80 is deallocated. */ | |
81 | |
82 | |
83 /* place-holders */ | |
84 struct mwCipherInstance; | |
85 struct mwMsgChannelAccept; | |
86 struct mwMsgChannelCreate; | |
87 struct mwMsgChannelDestroy; | |
88 struct mwMsgChannelSend; | |
89 struct mwService; | |
90 struct mwSession; | |
91 | |
92 | |
93 | |
94 /** @struct mwChannel | |
95 Represents a channel to a service */ | |
96 struct mwChannel; | |
97 | |
98 | |
99 /** @struct mwChannelSet | |
100 Collection of channels */ | |
101 struct mwChannelSet; | |
102 | |
103 | |
104 /** special ID indicating the master channel */ | |
105 #define MW_MASTER_CHANNEL_ID 0x00000000 | |
106 | |
107 | |
108 /** non-zero if a channel id appears to be that of an outgoing channel */ | |
109 #define mwChannel_idIsOutgoing(id) \ | |
110 (! (0x80000000 & (id))) | |
111 | |
112 /** non-zero if a channel id appears to be that of an incoming channel */ | |
113 #define mwChannel_idIsIncoming(id) \ | |
114 (! mwChannel_idIsOutgoing(id)) | |
115 | |
116 /** non-zero if a channel appears to be an outgoing channel */ | |
117 #define mwChannel_isOutgoing(chan) \ | |
118 mwChannel_idIsOutgoing(mwChannel_getId(chan)) | |
119 | |
120 /** non-zero if a channel appears to be an incoming channel */ | |
121 #define mwChannel_isIncoming(chan) \ | |
122 mwChannel_idIsIncoming(mwChannel_getId(chan)) | |
123 | |
124 | |
125 /** channel status */ | |
126 enum mwChannelState { | |
127 mwChannel_NEW, /**< channel is newly allocated, in the pool */ | |
128 mwChannel_INIT, /**< channel is being prepared, out of the pool */ | |
129 mwChannel_WAIT, /**< channel is waiting for accept */ | |
130 mwChannel_OPEN, /**< channel is accepted and open */ | |
131 mwChannel_DESTROY, /**< channel is being destroyed */ | |
132 mwChannel_ERROR, /**< channel is being destroyed due to error */ | |
133 mwChannel_UNKNOWN, /**< unknown state, or error determining state */ | |
134 }; | |
135 | |
136 | |
137 #define mwChannel_isState(chan, state) \ | |
138 (mwChannel_getState(chan) == (state)) | |
139 | |
140 | |
141 /** channel statistic fields. | |
142 @see mwChannel_getStatistic */ | |
143 enum mwChannelStatField { | |
144 mwChannelStat_MSG_SENT, /**< total send-on-chan messages sent */ | |
145 mwChannelStat_MSG_RECV, /**< total send-on-chan messages received */ | |
146 mwChannelStat_U_BYTES_SENT, /**< total bytes sent, pre-encryption */ | |
147 mwChannelStat_U_BYTES_RECV, /**< total bytes received, post-decryption */ | |
148 mwChannelStat_OPENED_AT, /**< time when channel was opened */ | |
149 mwChannelStat_CLOSED_AT, /**< time when channel was closed */ | |
150 }; | |
151 | |
152 | |
153 /** Allocate and initialize a channel set for a session */ | |
154 struct mwChannelSet *mwChannelSet_new(struct mwSession *); | |
155 | |
156 | |
157 /** Clear and deallocate a channel set. Closes, clears, and frees all | |
158 contained channels. */ | |
159 void mwChannelSet_free(struct mwChannelSet *); | |
160 | |
161 | |
162 /** Create an incoming channel with the given channel id. Channel's state | |
163 will be set to WAIT. Primarily for use in mw_session */ | |
164 struct mwChannel *mwChannel_newIncoming(struct mwChannelSet *, guint32 id); | |
165 | |
166 | |
167 /** Create an outgoing channel. Its channel ID will be generated by | |
168 the owning channel set. Channel's state will be set to INIT */ | |
169 struct mwChannel *mwChannel_newOutgoing(struct mwChannelSet *); | |
170 | |
171 | |
172 /** Obtain a reference to a channel by its id. | |
173 @returns the channel matching chan, or NULL */ | |
174 struct mwChannel *mwChannel_find(struct mwChannelSet *cs, guint32 chan); | |
175 | |
176 | |
177 /** get the ID for a channel. 0x00 indicates an error, as that is not | |
178 a permissible value */ | |
179 guint32 mwChannel_getId(struct mwChannel *); | |
180 | |
181 | |
182 /** get the session for a channel. */ | |
183 struct mwSession *mwChannel_getSession(struct mwChannel *); | |
184 | |
185 | |
186 /** get the ID of the service for a channel. This may be 0x00 for NEW | |
187 channels */ | |
188 guint32 mwChannel_getServiceId(struct mwChannel *); | |
189 | |
190 | |
191 /** get the service for a channel. This may be NULL for NEW | |
192 channels */ | |
193 struct mwService *mwChannel_getService(struct mwChannel *); | |
194 | |
195 | |
196 /** associate a channel with an owning service */ | |
197 void mwChannel_setService(struct mwChannel *chan, struct mwService *srvc); | |
198 | |
199 | |
200 /** get service-specific data. This is for use by service | |
201 implementations to easily associate information with the | |
202 channel */ | |
203 gpointer mwChannel_getServiceData(struct mwChannel *chan); | |
204 | |
205 | |
206 /** set service-specific data. This is for use by service | |
207 implementations to easily associate information with the | |
208 channel */ | |
209 void mwChannel_setServiceData(struct mwChannel *chan, | |
210 gpointer data, GDestroyNotify clean); | |
211 | |
212 | |
213 void mwChannel_removeServiceData(struct mwChannel *chan); | |
214 | |
215 | |
216 guint32 mwChannel_getProtoType(struct mwChannel *chan); | |
217 | |
218 | |
219 void mwChannel_setProtoType(struct mwChannel *chan, guint32 proto_type); | |
220 | |
221 | |
222 guint32 mwChannel_getProtoVer(struct mwChannel *chan); | |
223 | |
224 | |
225 void mwChannel_setProtoVer(struct mwChannel *chan, guint32 proto_ver); | |
226 | |
227 | |
228 guint32 mwChannel_getOptions(struct mwChannel *chan); | |
229 | |
230 | |
231 void mwChannel_setOptions(struct mwChannel *chan, guint32 options); | |
232 | |
233 | |
234 /** User at the other end of the channel. The target user for outgoing | |
235 channels, the creator for incoming channels */ | |
236 struct mwLoginInfo *mwChannel_getUser(struct mwChannel *chan); | |
237 | |
238 | |
239 /** direct reference to the create addtl information for a channel */ | |
240 struct mwOpaque *mwChannel_getAddtlCreate(struct mwChannel *); | |
241 | |
242 | |
243 /** direct reference to the accept addtl information for a channel */ | |
244 struct mwOpaque *mwChannel_getAddtlAccept(struct mwChannel *); | |
245 | |
246 | |
247 /** automatically adds instances of all ciphers in the session to the | |
248 list of supported ciphers for a channel */ | |
249 void mwChannel_populateSupportedCipherInstances(struct mwChannel *chan); | |
250 | |
251 | |
252 /** add a cipher instance to a channel's list of supported | |
253 ciphers. Channel must be NEW. */ | |
254 void mwChannel_addSupportedCipherInstance(struct mwChannel *chan, | |
255 struct mwCipherInstance *ci); | |
256 | |
257 | |
258 /** the list of supported ciphers for a channel. This list will be | |
259 empty once a cipher has been selected for the channel */ | |
260 GList *mwChannel_getSupportedCipherInstances(struct mwChannel *chan); | |
261 | |
262 | |
263 /** select a cipher instance for a channel. A NULL instance indicates | |
264 that no encryption should be used. */ | |
265 void mwChannel_selectCipherInstance(struct mwChannel *chan, | |
266 struct mwCipherInstance *ci); | |
267 | |
268 | |
269 /** get the state of a channel */ | |
270 enum mwChannelState mwChannel_getState(struct mwChannel *); | |
271 | |
272 | |
273 /** obtain the value for a statistic field as a gpointer */ | |
274 gpointer mwChannel_getStatistic(struct mwChannel *chan, | |
275 enum mwChannelStatField stat); | |
276 | |
277 | |
278 /** Formally open a channel. | |
279 | |
280 For outgoing channels: instruct the session to send a channel | |
281 create message to the server, and to mark the channel (which must | |
282 be in INIT status) as being in WAIT status. | |
283 | |
284 For incoming channels: configures the channel according to options | |
285 in the channel create message. Marks the channel as being in WAIT | |
286 status | |
287 */ | |
288 int mwChannel_create(struct mwChannel *chan); | |
289 | |
290 | |
291 /** Formally accept an incoming channel. Instructs the session to send | |
292 a channel accept message to the server, and to mark the channel as | |
293 being OPEN. */ | |
294 int mwChannel_accept(struct mwChannel *chan); | |
295 | |
296 | |
297 /** Destroy a channel. Sends a channel-destroy message to the server, | |
298 and perform cleanup to remove the channel. | |
299 | |
300 @param chan the channel to destroy | |
301 @param reason the reason code for closing the channel | |
302 @param data optional additional information | |
303 */ | |
304 int mwChannel_destroy(struct mwChannel *chan, guint32 reason, | |
305 struct mwOpaque *data); | |
306 | |
307 | |
308 /** Compose a send-on-channel message, encrypt it as per the channel's | |
309 specification, and send it */ | |
310 int mwChannel_send(struct mwChannel *chan, guint32 msg_type, | |
311 struct mwOpaque *msg); | |
312 | |
313 | |
314 /** Compose a send-on-channel message, and if encrypt is TRUE, encrypt | |
315 it as per the channel's specification, and send it */ | |
316 int mwChannel_sendEncrypted(struct mwChannel *chan, | |
317 guint32 msg_type, struct mwOpaque *msg, | |
318 gboolean encrypt); | |
319 | |
320 | |
321 /** pass a create message to a channel for handling */ | |
322 void mwChannel_recvCreate(struct mwChannel *chan, | |
323 struct mwMsgChannelCreate *msg); | |
324 | |
325 | |
326 /** pass an accept message to a channel for handling */ | |
327 void mwChannel_recvAccept(struct mwChannel *chan, | |
328 struct mwMsgChannelAccept *msg); | |
329 | |
330 | |
331 /** pass a destroy message to a channel for handling */ | |
332 void mwChannel_recvDestroy(struct mwChannel *chan, | |
333 struct mwMsgChannelDestroy *msg); | |
334 | |
335 | |
336 /** Feed data into a channel. */ | |
337 void mwChannel_recv(struct mwChannel *chan, struct mwMsgChannelSend *msg); | |
338 | |
339 | |
340 #endif | |
341 |