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