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