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