Mercurial > pidgin
annotate src/protocols/sametime/meanwhile/mw_common.h @ 11943:0110fc7c6a8a
[gaim-migrate @ 14234]
Bringing things up to date with the last Meanwhile release, 0.5.0 and the last
gaim-meanwhile plugin release, 1.2.5 (which should be the last plugin release
against oldstatus, if all goes well with HEAD and no major bugs crop up)
It builds, so that's a start. The status bits that have been empty since the
first import of the sametime stuff are still empty, but I'm going to try and
fill those in tomorrow. I've decided to try and start using HEAD actively, to
encourage me to get this freaking prpl fully functional.
committer: Tailor Script <tailor@pidgin.im>
author | Christopher O'Brien <siege@pidgin.im> |
---|---|
date | Wed, 02 Nov 2005 03:39:03 +0000 |
parents | dcc37a23f815 |
children | 5b3368008513 |
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 { | |
75 gsize len; /**< length of data. */ | |
76 char *data; /**< data, normally with no NULL termination */ | |
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 */ | |
103 mwLogin_NOTES_6_5 = 0x1200, | |
104 mwLogin_NOTES_7_0 = 0x1210, | |
105 mwLogin_ICT = 0x1300, | |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
106 mwLogin_ICT_1_7_8_2 = 0x1302, |
10969 | 107 mwLogin_NOTESBUDDY = 0x1400, /**< 0xff00 mask? */ |
108 mwLogin_NOTESBUDDY_4_15 = 0x1405, | |
109 mwLogin_SANITY = 0x1600, | |
110 mwLogin_ST_PERL = 0x1625, | |
111 mwLogin_PMR_ALERT = 0x1650, | |
112 mwLogin_TRILLIAN = 0x16aa, /**< http://sf.net/st-plugin/ */ | |
113 mwLogin_TRILLIAN_IBM = 0x16bb, | |
114 mwLogin_MEANWHILE = 0x1700, /**< Meanwhile library */ | |
115 }; | |
116 | |
117 | |
118 /* 8.2 Common Structures */ | |
119 /* 8.2.1 Login Info block */ | |
120 | |
121 struct mwLoginInfo { | |
122 char *login_id; /**< community-unique ID of the login */ | |
123 guint16 type; /**< @see mwLoginType */ | |
124 char *user_id; /**< community-unique ID of the user */ | |
125 char *user_name; /**< name of user (nick name, full name, etc) */ | |
126 char *community; /**< community name (usually domain name) */ | |
127 gboolean full; /**< if FALSE, following fields non-existant */ | |
128 char *desc; /**< implementation defined description */ | |
129 guint32 ip_addr; /**< ip addr of the login */ | |
130 char *server_id; /**< unique ID of login's server */ | |
131 }; | |
132 | |
133 | |
134 /* 8.2.2 Private Info Block */ | |
135 | |
136 struct mwUserItem { | |
137 gboolean full; /**< if FALSE, don't include name */ | |
138 char *id; /**< user id */ | |
139 char *community; /**< community */ | |
140 char *name; /**< user name */ | |
141 }; | |
142 | |
143 | |
144 struct mwPrivacyInfo { | |
145 gboolean deny; /**< deny (true) or allow (false) users */ | |
146 guint32 count; /**< count of users */ | |
147 struct mwUserItem *users; /**< the users list */ | |
148 }; | |
149 | |
150 | |
151 /* 8.3.5 User Status Types */ | |
152 | |
153 enum mwStatusType { | |
154 mwStatus_ACTIVE = 0x0020, | |
155 mwStatus_IDLE = 0x0040, | |
156 mwStatus_AWAY = 0x0060, | |
157 mwStatus_BUSY = 0x0080, | |
158 }; | |
159 | |
160 | |
161 /* 8.2.3 User Status Block */ | |
162 | |
163 struct mwUserStatus { | |
164 guint16 status; /**< @see mwStatusType */ | |
165 guint32 time; /**< last status change time in seconds */ | |
166 char *desc; /**< status description */ | |
167 }; | |
168 | |
169 | |
170 /* 8.2.4 ID Block */ | |
171 | |
172 struct mwIdBlock { | |
173 char *user; /**< user id (login id or empty for some services) */ | |
174 char *community; /**< community id (NULL for same community) */ | |
175 }; | |
176 | |
177 | |
178 /* 8.3.8.2 Awareness Presence Types */ | |
179 | |
180 /* @todo move mwAwareType, mwAwareIdBlock and mwAwareSnapshot into the | |
181 aware service and out of common */ | |
182 | |
183 /** type codes for mwAwareIdBlock */ | |
184 enum mwAwareType { | |
185 mwAware_USER = 0x0002, /**< a single user */ | |
186 mwAware_GROUP = 0x0003, /**< a group */ | |
187 mwAware_SERVER = 0x0008, /**< a server */ | |
188 }; | |
189 | |
190 | |
191 /* 8.4.2 Awareness Messages */ | |
192 /* 8.4.2.1 Awareness ID Block */ | |
193 | |
194 struct mwAwareIdBlock { | |
195 guint16 type; /**< @see mwAwareType */ | |
196 char *user; /**< user id */ | |
197 char *community; /**< community id (NULL for same community) */ | |
198 }; | |
199 | |
200 | |
201 /* 8.4.2.4 Snapshot */ | |
202 | |
203 struct mwAwareSnapshot { | |
204 struct mwAwareIdBlock id; | |
205 char *group; /**< group this id belongs to */ | |
206 gboolean online; /**< is this user online? */ | |
207 char *alt_id; /**< alternate ID, often same as id.user */ | |
208 struct mwUserStatus status; /**< status of this user */ | |
209 char *name; /**< Formatted version of ID */ | |
210 }; | |
211 | |
212 | |
213 /** encryption blocks */ | |
214 struct mwEncryptItem { | |
215 guint16 id; /**< cipher identifier */ | |
216 struct mwOpaque info; /**< cipher information */ | |
217 }; | |
218 | |
219 | |
220 /** @name buffer utility functions */ | |
221 /*@{*/ | |
222 | |
223 | |
224 /** allocate a new empty buffer */ | |
225 struct mwPutBuffer *mwPutBuffer_new(); | |
226 | |
227 | |
228 /** write raw data to the put buffer */ | |
229 void mwPutBuffer_write(struct mwPutBuffer *b, gpointer data, gsize len); | |
230 | |
231 | |
232 /** destroy the buffer */ | |
233 void mwPutBuffer_free(struct mwPutBuffer *b); | |
234 | |
235 | |
236 /** move the buffer's data into an opaque, destroy the buffer */ | |
237 void mwPutBuffer_finalize(struct mwOpaque *to, struct mwPutBuffer *from); | |
238 | |
239 | |
240 /** allocate a new buffer with a copy of the given data */ | |
241 struct mwGetBuffer *mwGetBuffer_new(struct mwOpaque *data); | |
242 | |
243 | |
244 /** read len bytes of raw data from the get buffer into mem. If len is | |
245 greater than the count of bytes remaining in the buffer, the | |
246 buffer's error flag will NOT be set. | |
247 | |
248 @returns count of bytes successfully copied to mem */ | |
249 gsize mwGetBuffer_read(struct mwGetBuffer *b, gpointer mem, gsize len); | |
250 | |
251 | |
252 /** skip len bytes in the get buffer. If len is greater than the count | |
253 of bytes remaining in the buffer, the buffer's error flag will NOT | |
254 be set. | |
255 | |
256 @returns count of bytes successfully skipped */ | |
257 gsize mwGetBuffer_advance(struct mwGetBuffer *b, gsize len); | |
258 | |
259 | |
260 /** allocate a new buffer backed by the given data. Calling | |
261 mwGetBuffer_free will not result in the underlying data being | |
262 freed */ | |
263 struct mwGetBuffer *mwGetBuffer_wrap(const struct mwOpaque *data); | |
264 | |
265 | |
266 /** destroy the buffer */ | |
267 void mwGetBuffer_free(struct mwGetBuffer *b); | |
268 | |
269 | |
270 /** reset the buffer to the very beginning. Also clears the buffer's | |
271 error flag. */ | |
272 void mwGetBuffer_reset(struct mwGetBuffer *b); | |
273 | |
274 | |
275 /** count of remaining available bytes */ | |
276 gsize mwGetBuffer_remaining(struct mwGetBuffer *b); | |
277 | |
278 | |
279 /** TRUE if an error occurred while reading a basic type from this | |
280 buffer */ | |
281 gboolean mwGetBuffer_error(struct mwGetBuffer *b); | |
282 | |
283 | |
284 /*@}*/ | |
285 | |
286 | |
287 /** provides a textual name for a given login type. If the type is not | |
288 known by name, returns NULL */ | |
289 const char *mwLoginType_getName(enum mwLoginType type); | |
290 | |
291 | |
292 /** @name Basic Data Type Marshalling | |
293 The basic types are combined to construct the complex types. | |
294 */ | |
295 /*@{*/ | |
296 | |
297 | |
298 void guint16_put(struct mwPutBuffer *b, guint16 val); | |
299 | |
300 void guint16_get(struct mwGetBuffer *b, guint16 *val); | |
301 | |
302 guint16 guint16_peek(struct mwGetBuffer *b); | |
303 | |
304 | |
305 void guint32_put(struct mwPutBuffer *b, guint32 val); | |
306 | |
307 void guint32_get(struct mwGetBuffer *b, guint32 *val); | |
308 | |
309 guint32 guint32_peek(struct mwGetBuffer *b); | |
310 | |
311 | |
312 void gboolean_put(struct mwPutBuffer *b, gboolean val); | |
313 | |
314 void gboolean_get(struct mwGetBuffer *b, gboolean *val); | |
315 | |
316 gboolean gboolean_peek(struct mwGetBuffer *b); | |
317 | |
318 | |
319 void mwString_put(struct mwPutBuffer *b, const char *str); | |
320 | |
321 void mwString_get(struct mwGetBuffer *b, char **str); | |
322 | |
323 | |
324 void mwOpaque_put(struct mwPutBuffer *b, const struct mwOpaque *o); | |
325 | |
326 void mwOpaque_get(struct mwGetBuffer *b, struct mwOpaque *o); | |
327 | |
328 void mwOpaque_clear(struct mwOpaque *o); | |
329 | |
330 void mwOpaque_free(struct mwOpaque *o); | |
331 | |
332 void mwOpaque_clone(struct mwOpaque *to, const struct mwOpaque *from); | |
333 | |
334 | |
335 /*@}*/ | |
336 | |
337 | |
338 /** @name Complex Data Type Marshalling */ | |
339 /*@{*/ | |
340 | |
341 | |
342 void mwLoginInfo_put(struct mwPutBuffer *b, const struct mwLoginInfo *info); | |
343 | |
344 void mwLoginInfo_get(struct mwGetBuffer *b, struct mwLoginInfo *info); | |
345 | |
346 void mwLoginInfo_clear(struct mwLoginInfo *info); | |
347 | |
348 void mwLoginInfo_clone(struct mwLoginInfo *to, const struct mwLoginInfo *from); | |
349 | |
350 | |
351 void mwUserItem_put(struct mwPutBuffer *b, const struct mwUserItem *user); | |
352 | |
353 void mwUserItem_get(struct mwGetBuffer *b, struct mwUserItem *user); | |
354 | |
355 void mwUserItem_clear(struct mwUserItem *user); | |
356 | |
357 void mwUserItem_clone(struct mwUserItem *to, const struct mwUserItem *from); | |
358 | |
359 | |
360 void mwPrivacyInfo_put(struct mwPutBuffer *b, | |
361 const struct mwPrivacyInfo *info); | |
362 | |
363 void mwPrivacyInfo_get(struct mwGetBuffer *b, struct mwPrivacyInfo *info); | |
364 | |
365 void mwPrivacyInfo_clear(struct mwPrivacyInfo *info); | |
366 | |
10982
dcc37a23f815
[gaim-migrate @ 12813]
Christopher O'Brien <siege@pidgin.im>
parents:
10969
diff
changeset
|
367 void mwPrivacyInfo_clone(struct mwPrivacyInfo *to, |
dcc37a23f815
[gaim-migrate @ 12813]
Christopher O'Brien <siege@pidgin.im>
parents:
10969
diff
changeset
|
368 const struct mwPrivacyInfo *from); |
dcc37a23f815
[gaim-migrate @ 12813]
Christopher O'Brien <siege@pidgin.im>
parents:
10969
diff
changeset
|
369 |
10969 | 370 |
371 void mwUserStatus_put(struct mwPutBuffer *b, | |
372 const struct mwUserStatus *stat); | |
373 | |
374 void mwUserStatus_get(struct mwGetBuffer *b, struct mwUserStatus *stat); | |
375 | |
376 void mwUserStatus_clear(struct mwUserStatus *stat); | |
377 | |
378 void mwUserStatus_clone(struct mwUserStatus *to, | |
379 const struct mwUserStatus *from); | |
380 | |
381 | |
382 void mwIdBlock_put(struct mwPutBuffer *b, const struct mwIdBlock *id); | |
383 | |
384 void mwIdBlock_get(struct mwGetBuffer *b, struct mwIdBlock *id); | |
385 | |
386 void mwIdBlock_clear(struct mwIdBlock *id); | |
387 | |
388 void mwIdBlock_clone(struct mwIdBlock *to, | |
389 const struct mwIdBlock *from); | |
390 | |
391 guint mwIdBlock_hash(const struct mwIdBlock *idb); | |
392 | |
393 gboolean mwIdBlock_equal(const struct mwIdBlock *a, | |
394 const struct mwIdBlock *b); | |
395 | |
396 | |
397 void mwAwareIdBlock_put(struct mwPutBuffer *b, | |
398 const struct mwAwareIdBlock *idb); | |
399 | |
400 void mwAwareIdBlock_get(struct mwGetBuffer *b, struct mwAwareIdBlock *idb); | |
401 | |
402 void mwAwareIdBlock_clear(struct mwAwareIdBlock *idb); | |
403 | |
404 void mwAwareIdBlock_clone(struct mwAwareIdBlock *to, | |
405 const struct mwAwareIdBlock *from); | |
406 | |
407 guint mwAwareIdBlock_hash(const struct mwAwareIdBlock *a); | |
408 | |
409 gboolean mwAwareIdBlock_equal(const struct mwAwareIdBlock *a, | |
410 const struct mwAwareIdBlock *b); | |
411 | |
412 | |
413 void mwAwareSnapshot_get(struct mwGetBuffer *b, | |
414 struct mwAwareSnapshot *idb); | |
415 | |
416 void mwAwareSnapshot_clear(struct mwAwareSnapshot *idb); | |
417 | |
418 void mwAwareSnapshot_clone(struct mwAwareSnapshot *to, | |
419 const struct mwAwareSnapshot *from); | |
420 | |
421 | |
422 void mwEncryptItem_put(struct mwPutBuffer *b, | |
423 const struct mwEncryptItem *item); | |
424 | |
425 void mwEncryptItem_get(struct mwGetBuffer *b, struct mwEncryptItem *item); | |
426 | |
427 void mwEncryptItem_clear(struct mwEncryptItem *item); | |
428 | |
11943
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
429 void mwEncryptItem_free(struct mwEncryptItem *item); |
0110fc7c6a8a
[gaim-migrate @ 14234]
Christopher O'Brien <siege@pidgin.im>
parents:
10982
diff
changeset
|
430 |
10969 | 431 |
432 /*@}*/ | |
433 | |
434 | |
435 #endif |