Mercurial > pidgin
annotate src/protocols/sametime/meanwhile/mw_common.h @ 12270:a2bbde197826
[gaim-migrate @ 14572]
here.
committer: Tailor Script <tailor@pidgin.im>
author | Christopher O'Brien <siege@pidgin.im> |
---|---|
date | Wed, 30 Nov 2005 04:33:52 +0000 |
parents | 5b3368008513 |
children | a2ebf585d8c6 |
rev | line source |
---|---|
10969 | 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_COMMON_H | |
22 #define _MW_COMMON_H | |
23 | |
24 | |
25 #include <glib.h> | |
26 | |
27 | |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
28 /** @file mw_common.h |
10969 | 29 |
30 Common data types and functions for handling those types. | |
31 | |
32 Functions in this file all fit into similar naming conventions of | |
33 <code>TYPE_ACTION</code> as per the activity they perform. The | |
34 following actions are available: | |
35 | |
36 <code>void TYPE_put(struct mwPutBuffer *b, TYPE *val)</code> | |
37 - marshalls val onto the buffer b. The buffer will grow as necessary | |
38 to fit all the data put into it. For guint16, guint32, and | |
39 gboolean, <code>TYPE val</code> is used instead of <code>TYPE | |
40 \*val</code>. | |
41 | |
42 <code>void TYPE_get(struct mwGetBuffer *b, TYPE *val)</code> | |
43 - unmarshals val from the buffer b. Failure (due to lack of | |
44 insufficient remaining buffer) is indicated in the buffer's error | |
45 field. A call to a _get function with a buffer in an error state | |
46 has to effect. | |
47 | |
48 <code>void TYPE_clear(TYPE *val)</code> | |
49 - zeros and frees internal members of val, but does not free val | |
50 itself. Needs to be called before free-ing any complex types which | |
51 have been unmarshalled from a TYPE_get or populated from a | |
52 TYPE_clone call to prevent memory leaks. | |
53 | |
54 <code>void TYPE_clone(TYPE *to, TYPE *from)</code> | |
55 - copies/clones members of from into to. May result in memory | |
56 allocation for some types. Note that to is not cleared | |
57 before-hand, it must already be in a pristine condition. | |
58 | |
59 <code>gboolean TYPE_equal(TYPE *y, TYPE *z)</code> | |
60 - simple equality test. | |
61 */ | |
62 | |
63 | |
64 /** @struct mwPutBuffer | |
65 buffer to be written to */ | |
66 struct mwPutBuffer; | |
67 | |
68 /** @struct mwGetBuffer | |
69 buffer to be read from */ | |
70 struct mwGetBuffer; | |
71 | |
72 | |
73 /** A length of binary data, not null-terminated. */ | |
74 struct mwOpaque { | |
12270
a2bbde197826
[gaim-migrate @ 14572]
Christopher O'Brien <siege@pidgin.im>
parents:
12005
diff
changeset
|
75 gsize len; /**< length of data. */ |
a2bbde197826
[gaim-migrate @ 14572]
Christopher O'Brien <siege@pidgin.im>
parents:
12005
diff
changeset
|
76 unsigned char *data; /**< data, normally with no NULL termination */ |
10969 | 77 }; |
78 | |
79 | |
80 /* 8.3.6 Login Types */ | |
81 | |
82 /** The type of login. Normally meaning the type of client code being | |
83 used to login with. | |
84 | |
85 If you know of any additional client identifiers, please add them | |
86 below. | |
87 | |
88 If you are using Meanwhile in your client code and would like to | |
89 differentiate yourself, please email siege at preoccupied dot net | |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
90 with all the relevant information you can think of and I'll add it |
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
91 to the text mapping as well |
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
92 |
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
93 @see mwLoginType_getName |
10969 | 94 */ |
95 enum mwLoginType { | |
96 mwLogin_LIB = 0x1000, /**< official Lotus binary library */ | |
97 mwLogin_JAVA_WEB = 0x1001, /**< official Lotus Java applet */ | |
98 mwLogin_BINARY = 0x1002, /**< official Lotus binary application */ | |
99 mwLogin_JAVA_APP = 0x1003, /**< official Lotus Java application */ | |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
100 mwLogin_LINKS = 0x100a, /**< official Sametime Links toolkit */ |
10969 | 101 |
102 /* now we're getting crazy */ | |
12270
a2bbde197826
[gaim-migrate @ 14572]
Christopher O'Brien <siege@pidgin.im>
parents:
12005
diff
changeset
|
103 mwLogin_NOTES_6_5 = 0x1200, |
12005
5b3368008513
[gaim-migrate @ 14298]
Christopher O'Brien <siege@pidgin.im>
parents:
11943
diff
changeset
|
104 mwLogin_NOTES_6_5_3 = 0x1203, |
5b3368008513
[gaim-migrate @ 14298]
Christopher O'Brien <siege@pidgin.im>
parents:
11943
diff
changeset
|
105 mwLogin_NOTES_7_0_beta = 0x1210, |
5b3368008513
[gaim-migrate @ 14298]
Christopher O'Brien <siege@pidgin.im>
parents:
11943
diff
changeset
|
106 mwLogin_NOTES_7_0 = 0x1214, |
12270
a2bbde197826
[gaim-migrate @ 14572]
Christopher O'Brien <siege@pidgin.im>
parents:
12005
diff
changeset
|
107 mwLogin_ICT = 0x1300, |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
108 mwLogin_ICT_1_7_8_2 = 0x1302, |
12005
5b3368008513
[gaim-migrate @ 14298]
Christopher O'Brien <siege@pidgin.im>
parents:
11943
diff
changeset
|
109 mwLogin_ICT_SIP = 0x1303, |
5b3368008513
[gaim-migrate @ 14298]
Christopher O'Brien <siege@pidgin.im>
parents:
11943
diff
changeset
|
110 mwLogin_NOTESBUDDY_4_14 = 0x1400, /**< 0xff00 mask? */ |
10969 | 111 mwLogin_NOTESBUDDY_4_15 = 0x1405, |
12005
5b3368008513
[gaim-migrate @ 14298]
Christopher O'Brien <siege@pidgin.im>
parents:
11943
diff
changeset
|
112 mwLogin_NOTESBUDDY_4_16 = 0x1406, |
10969 | 113 mwLogin_SANITY = 0x1600, |
114 mwLogin_ST_PERL = 0x1625, | |
115 mwLogin_PMR_ALERT = 0x1650, | |
116 mwLogin_TRILLIAN = 0x16aa, /**< http://sf.net/st-plugin/ */ | |
117 mwLogin_TRILLIAN_IBM = 0x16bb, | |
118 mwLogin_MEANWHILE = 0x1700, /**< Meanwhile library */ | |
119 }; | |
120 | |
121 | |
122 /* 8.2 Common Structures */ | |
123 /* 8.2.1 Login Info block */ | |
124 | |
125 struct mwLoginInfo { | |
126 char *login_id; /**< community-unique ID of the login */ | |
127 guint16 type; /**< @see mwLoginType */ | |
128 char *user_id; /**< community-unique ID of the user */ | |
129 char *user_name; /**< name of user (nick name, full name, etc) */ | |
130 char *community; /**< community name (usually domain name) */ | |
131 gboolean full; /**< if FALSE, following fields non-existant */ | |
132 char *desc; /**< implementation defined description */ | |
133 guint32 ip_addr; /**< ip addr of the login */ | |
134 char *server_id; /**< unique ID of login's server */ | |
135 }; | |
136 | |
137 | |
138 /* 8.2.2 Private Info Block */ | |
139 | |
140 struct mwUserItem { | |
141 gboolean full; /**< if FALSE, don't include name */ | |
142 char *id; /**< user id */ | |
143 char *community; /**< community */ | |
144 char *name; /**< user name */ | |
145 }; | |
146 | |
147 | |
148 struct mwPrivacyInfo { | |
149 gboolean deny; /**< deny (true) or allow (false) users */ | |
150 guint32 count; /**< count of users */ | |
151 struct mwUserItem *users; /**< the users list */ | |
152 }; | |
153 | |
154 | |
155 /* 8.3.5 User Status Types */ | |
156 | |
157 enum mwStatusType { | |
158 mwStatus_ACTIVE = 0x0020, | |
159 mwStatus_IDLE = 0x0040, | |
160 mwStatus_AWAY = 0x0060, | |
161 mwStatus_BUSY = 0x0080, | |
162 }; | |
163 | |
164 | |
165 /* 8.2.3 User Status Block */ | |
166 | |
167 struct mwUserStatus { | |
168 guint16 status; /**< @see mwStatusType */ | |
169 guint32 time; /**< last status change time in seconds */ | |
170 char *desc; /**< status description */ | |
171 }; | |
172 | |
173 | |
174 /* 8.2.4 ID Block */ | |
175 | |
176 struct mwIdBlock { | |
177 char *user; /**< user id (login id or empty for some services) */ | |
178 char *community; /**< community id (NULL for same community) */ | |
179 }; | |
180 | |
181 | |
182 /* 8.3.8.2 Awareness Presence Types */ | |
183 | |
184 /* @todo move mwAwareType, mwAwareIdBlock and mwAwareSnapshot into the | |
185 aware service and out of common */ | |
186 | |
187 /** type codes for mwAwareIdBlock */ | |
188 enum mwAwareType { | |
189 mwAware_USER = 0x0002, /**< a single user */ | |
190 mwAware_GROUP = 0x0003, /**< a group */ | |
191 mwAware_SERVER = 0x0008, /**< a server */ | |
192 }; | |
193 | |
194 | |
195 /* 8.4.2 Awareness Messages */ | |
196 /* 8.4.2.1 Awareness ID Block */ | |
197 | |
198 struct mwAwareIdBlock { | |
199 guint16 type; /**< @see mwAwareType */ | |
200 char *user; /**< user id */ | |
201 char *community; /**< community id (NULL for same community) */ | |
202 }; | |
203 | |
204 | |
205 /* 8.4.2.4 Snapshot */ | |
206 | |
207 struct mwAwareSnapshot { | |
208 struct mwAwareIdBlock id; | |
209 char *group; /**< group this id belongs to */ | |
210 gboolean online; /**< is this user online? */ | |
211 char *alt_id; /**< alternate ID, often same as id.user */ | |
212 struct mwUserStatus status; /**< status of this user */ | |
213 char *name; /**< Formatted version of ID */ | |
214 }; | |
215 | |
216 | |
217 /** encryption blocks */ | |
218 struct mwEncryptItem { | |
219 guint16 id; /**< cipher identifier */ | |
220 struct mwOpaque info; /**< cipher information */ | |
221 }; | |
222 | |
223 | |
224 /** @name buffer utility functions */ | |
225 /*@{*/ | |
226 | |
227 | |
228 /** allocate a new empty buffer */ | |
229 struct mwPutBuffer *mwPutBuffer_new(); | |
230 | |
231 | |
232 /** write raw data to the put buffer */ | |
233 void mwPutBuffer_write(struct mwPutBuffer *b, gpointer data, gsize len); | |
234 | |
235 | |
236 /** destroy the buffer */ | |
237 void mwPutBuffer_free(struct mwPutBuffer *b); | |
238 | |
239 | |
240 /** move the buffer's data into an opaque, destroy the buffer */ | |
241 void mwPutBuffer_finalize(struct mwOpaque *to, struct mwPutBuffer *from); | |
242 | |
243 | |
244 /** allocate a new buffer with a copy of the given data */ | |
245 struct mwGetBuffer *mwGetBuffer_new(struct mwOpaque *data); | |
246 | |
247 | |
248 /** read len bytes of raw data from the get buffer into mem. If len is | |
249 greater than the count of bytes remaining in the buffer, the | |
250 buffer's error flag will NOT be set. | |
251 | |
252 @returns count of bytes successfully copied to mem */ | |
253 gsize mwGetBuffer_read(struct mwGetBuffer *b, gpointer mem, gsize len); | |
254 | |
255 | |
256 /** skip len bytes in the get buffer. If len is greater than the count | |
257 of bytes remaining in the buffer, the buffer's error flag will NOT | |
258 be set. | |
259 | |
260 @returns count of bytes successfully skipped */ | |
261 gsize mwGetBuffer_advance(struct mwGetBuffer *b, gsize len); | |
262 | |
263 | |
264 /** allocate a new buffer backed by the given data. Calling | |
265 mwGetBuffer_free will not result in the underlying data being | |
266 freed */ | |
267 struct mwGetBuffer *mwGetBuffer_wrap(const struct mwOpaque *data); | |
268 | |
269 | |
270 /** destroy the buffer */ | |
271 void mwGetBuffer_free(struct mwGetBuffer *b); | |
272 | |
273 | |
274 /** reset the buffer to the very beginning. Also clears the buffer's | |
275 error flag. */ | |
276 void mwGetBuffer_reset(struct mwGetBuffer *b); | |
277 | |
278 | |
279 /** count of remaining available bytes */ | |
280 gsize mwGetBuffer_remaining(struct mwGetBuffer *b); | |
281 | |
282 | |
283 /** TRUE if an error occurred while reading a basic type from this | |
284 buffer */ | |
285 gboolean mwGetBuffer_error(struct mwGetBuffer *b); | |
286 | |
287 | |
288 /*@}*/ | |
289 | |
290 | |
291 /** provides a textual name for a given login type. If the type is not | |
292 known by name, returns NULL */ | |
293 const char *mwLoginType_getName(enum mwLoginType type); | |
294 | |
295 | |
296 /** @name Basic Data Type Marshalling | |
297 The basic types are combined to construct the complex types. | |
298 */ | |
299 /*@{*/ | |
300 | |
301 | |
302 void guint16_put(struct mwPutBuffer *b, guint16 val); | |
303 | |
304 void guint16_get(struct mwGetBuffer *b, guint16 *val); | |
305 | |
306 guint16 guint16_peek(struct mwGetBuffer *b); | |
307 | |
308 | |
309 void guint32_put(struct mwPutBuffer *b, guint32 val); | |
310 | |
311 void guint32_get(struct mwGetBuffer *b, guint32 *val); | |
312 | |
313 guint32 guint32_peek(struct mwGetBuffer *b); | |
314 | |
315 | |
316 void gboolean_put(struct mwPutBuffer *b, gboolean val); | |
317 | |
318 void gboolean_get(struct mwGetBuffer *b, gboolean *val); | |
319 | |
320 gboolean gboolean_peek(struct mwGetBuffer *b); | |
321 | |
322 | |
323 void mwString_put(struct mwPutBuffer *b, const char *str); | |
324 | |
325 void mwString_get(struct mwGetBuffer *b, char **str); | |
326 | |
327 | |
328 void mwOpaque_put(struct mwPutBuffer *b, const struct mwOpaque *o); | |
329 | |
330 void mwOpaque_get(struct mwGetBuffer *b, struct mwOpaque *o); | |
331 | |
332 void mwOpaque_clear(struct mwOpaque *o); | |
333 | |
334 void mwOpaque_free(struct mwOpaque *o); | |
335 | |
336 void mwOpaque_clone(struct mwOpaque *to, const struct mwOpaque *from); | |
337 | |
338 | |
339 /*@}*/ | |
340 | |
341 | |
342 /** @name Complex Data Type Marshalling */ | |
343 /*@{*/ | |
344 | |
345 | |
346 void mwLoginInfo_put(struct mwPutBuffer *b, const struct mwLoginInfo *info); | |
347 | |
348 void mwLoginInfo_get(struct mwGetBuffer *b, struct mwLoginInfo *info); | |
349 | |
350 void mwLoginInfo_clear(struct mwLoginInfo *info); | |
351 | |
352 void mwLoginInfo_clone(struct mwLoginInfo *to, const struct mwLoginInfo *from); | |
353 | |
354 | |
355 void mwUserItem_put(struct mwPutBuffer *b, const struct mwUserItem *user); | |
356 | |
357 void mwUserItem_get(struct mwGetBuffer *b, struct mwUserItem *user); | |
358 | |
359 void mwUserItem_clear(struct mwUserItem *user); | |
360 | |
361 void mwUserItem_clone(struct mwUserItem *to, const struct mwUserItem *from); | |
362 | |
363 | |
364 void mwPrivacyInfo_put(struct mwPutBuffer *b, | |
365 const struct mwPrivacyInfo *info); | |
366 | |
367 void mwPrivacyInfo_get(struct mwGetBuffer *b, struct mwPrivacyInfo *info); | |
368 | |
369 void mwPrivacyInfo_clear(struct mwPrivacyInfo *info); | |
370 | |
10982
dcc37a23f815
[gaim-migrate @ 12813]
Christopher O'Brien <siege@pidgin.im>
parents:
10969
diff
changeset
|
371 void mwPrivacyInfo_clone(struct mwPrivacyInfo *to, |
dcc37a23f815
[gaim-migrate @ 12813]
Christopher O'Brien <siege@pidgin.im>
parents:
10969
diff
changeset
|
372 const struct mwPrivacyInfo *from); |
dcc37a23f815
[gaim-migrate @ 12813]
Christopher O'Brien <siege@pidgin.im>
parents:
10969
diff
changeset
|
373 |
10969 | 374 |
375 void mwUserStatus_put(struct mwPutBuffer *b, | |
376 const struct mwUserStatus *stat); | |
377 | |
378 void mwUserStatus_get(struct mwGetBuffer *b, struct mwUserStatus *stat); | |
379 | |
380 void mwUserStatus_clear(struct mwUserStatus *stat); | |
381 | |
382 void mwUserStatus_clone(struct mwUserStatus *to, | |
383 const struct mwUserStatus *from); | |
384 | |
385 | |
386 void mwIdBlock_put(struct mwPutBuffer *b, const struct mwIdBlock *id); | |
387 | |
388 void mwIdBlock_get(struct mwGetBuffer *b, struct mwIdBlock *id); | |
389 | |
390 void mwIdBlock_clear(struct mwIdBlock *id); | |
391 | |
392 void mwIdBlock_clone(struct mwIdBlock *to, | |
393 const struct mwIdBlock *from); | |
394 | |
395 guint mwIdBlock_hash(const struct mwIdBlock *idb); | |
396 | |
397 gboolean mwIdBlock_equal(const struct mwIdBlock *a, | |
398 const struct mwIdBlock *b); | |
399 | |
400 | |
401 void mwAwareIdBlock_put(struct mwPutBuffer *b, | |
402 const struct mwAwareIdBlock *idb); | |
403 | |
404 void mwAwareIdBlock_get(struct mwGetBuffer *b, struct mwAwareIdBlock *idb); | |
405 | |
406 void mwAwareIdBlock_clear(struct mwAwareIdBlock *idb); | |
407 | |
408 void mwAwareIdBlock_clone(struct mwAwareIdBlock *to, | |
409 const struct mwAwareIdBlock *from); | |
410 | |
411 guint mwAwareIdBlock_hash(const struct mwAwareIdBlock *a); | |
412 | |
413 gboolean mwAwareIdBlock_equal(const struct mwAwareIdBlock *a, | |
414 const struct mwAwareIdBlock *b); | |
415 | |
416 | |
417 void mwAwareSnapshot_get(struct mwGetBuffer *b, | |
418 struct mwAwareSnapshot *idb); | |
419 | |
420 void mwAwareSnapshot_clear(struct mwAwareSnapshot *idb); | |
421 | |
422 void mwAwareSnapshot_clone(struct mwAwareSnapshot *to, | |
423 const struct mwAwareSnapshot *from); | |
424 | |
425 | |
426 void mwEncryptItem_put(struct mwPutBuffer *b, | |
427 const struct mwEncryptItem *item); | |
428 | |
429 void mwEncryptItem_get(struct mwGetBuffer *b, struct mwEncryptItem *item); | |
430 | |
431 void mwEncryptItem_clear(struct mwEncryptItem *item); | |
432 | |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
433 void mwEncryptItem_free(struct mwEncryptItem *item); |
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
434 |
10969 | 435 |
436 /*@}*/ | |
437 | |
438 | |
439 #endif |