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_SRVC_AWARE_H 22 #define _MW_SRVC_AWARE_H 23 24 25 /** @file mw_srvc_aware.h 26 27 The aware service... 28 29 @todo remove the whole idea of an instantiated mwAwareList and 30 instead use arbitrary pointers (including NULL) as keys to 31 internally stored lists. This removes the problem of the service 32 free'ing its lists and invalidating mwAwareList references from 33 client code. 34 */ 35 36 37 #include "mw_common.h" 38 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 45 /** Type identifier for the aware service */ 46 #define mwService_AWARE 0x00000011 47 48 49 /** @struct mwServiceAware 50 51 Instance of an Aware Service. The members of this structure are 52 not made available. Accessing the parts of an aware service should 53 be performed through the appropriate functions. Note that 54 instances of this structure can be safely cast to a mwService. 55 */ 56 struct mwServiceAware; 57 58 59 /** @struct mwAwareList 60 61 Instance of an Aware List. The members of this structure are not 62 made available. Access to the parts of an aware list should be 63 handled through the appropriate functions. 64 65 Any references to an aware list are rendered invalid when the 66 parent service is free'd 67 */ 68 struct mwAwareList; 69 70 71 /** @struct mwAwareAttribute 72 73 Key/Opaque pair indicating an identity's attribute. 74 */ 75 struct mwAwareAttribute; 76 77 78 /** Predefined keys appropriate for a mwAwareAttribute 79 */ 80 enum mwAwareAttributeKeys { 81 mwAttribute_AV_PREFS_SET = 0x01, /**< A/V prefs specified, gboolean */ 82 mwAttribute_MICROPHONE = 0x02, /**< has a microphone, gboolean */ 83 mwAttribute_SPEAKERS = 0x03, /**< has speakers, gboolean */ 84 mwAttribute_VIDEO_CAMERA = 0x04, /**< has a video camera, gboolean */ 85 mwAttribute_FILE_TRANSFER = 0x06, /**< supports file transfers, gboolean */ 86 }; 87 88 89 typedef void (*mwAwareAttributeHandler) 90 (struct mwServiceAware *srvc, 91 struct mwAwareAttribute *attrib); 92 93 94 struct mwAwareHandler { 95 mwAwareAttributeHandler on_attrib; 96 void (*clear)(struct mwServiceAware *srvc); 97 }; 98 99 100 /** Appropriate function type for the on-aware signal 101 102 @param list mwAwareList emiting the signal 103 @param id awareness status information 104 @param data user-specified data 105 */ 106 typedef void (*mwAwareSnapshotHandler) 107 (struct mwAwareList *list, 108 struct mwAwareSnapshot *id); 109 110 111 /** Appropriate function type for the on-option signal. The option's 112 value may need to be explicitly loaded in some instances, 113 resulting in this handler being triggered again. 114 115 @param list mwAwareList emiting the signal 116 @param id awareness the attribute belongs to 117 @param attrib attribute 118 */ 119 typedef void (*mwAwareIdAttributeHandler) 120 (struct mwAwareList *list, 121 struct mwAwareIdBlock *id, 122 struct mwAwareAttribute *attrib); 123 124 125 struct mwAwareListHandler { 126 /** handle aware updates */ 127 mwAwareSnapshotHandler on_aware; 128 129 /** handle attribute updates */ 130 mwAwareIdAttributeHandler on_attrib; 131 132 /** optional. Called from mwAwareList_free */ 133 void (*clear)(struct mwAwareList *list); 134 }; 135 136 137 struct mwServiceAware * 138 mwServiceAware_new(struct mwSession *session, 139 struct mwAwareHandler *handler); 140 141 142 /** Set an attribute value for this session */ 143 int mwServiceAware_setAttribute(struct mwServiceAware *srvc, 144 guint32 key, struct mwOpaque *opaque); 145 146 147 int mwServiceAware_setAttributeBoolean(struct mwServiceAware *srvc, 148 guint32 key, gboolean val); 149 150 151 int mwServiceAware_setAttributeInteger(struct mwServiceAware *srvc, 152 guint32 key, guint32 val); 153 154 155 int mwServiceAware_setAttributeString(struct mwServiceAware *srvc, 156 guint32 key, const char *str); 157 158 159 /** Unset an attribute for this session */ 160 int mwServiceAware_unsetAttribute(struct mwServiceAware *srvc, 161 guint32 key); 162 163 164 guint32 mwAwareAttribute_getKey(const struct mwAwareAttribute *attrib); 165 166 167 gboolean mwAwareAttribute_asBoolean(const struct mwAwareAttribute *attrib); 168 169 170 guint32 mwAwareAttribute_asInteger(const struct mwAwareAttribute *attrib); 171 172 173 /** Copy of attribute string, must be g_free'd. If the attribute's 174 content cannot be loaded as a string, returns NULL */ 175 char *mwAwareAttribute_asString(const struct mwAwareAttribute *attrib); 176 177 178 /** Direct access to an attribute's underlying opaque */ 179 const struct mwOpaque * 180 mwAwareAttribute_asOpaque(const struct mwAwareAttribute *attrib); 181 182 183 /** Allocate and initialize an aware list */ 184 struct mwAwareList * 185 mwAwareList_new(struct mwServiceAware *srvc, 186 struct mwAwareListHandler *handler); 187 188 189 /** Clean and free an aware list */ 190 void mwAwareList_free(struct mwAwareList *list); 191 192 193 struct mwAwareListHandler *mwAwareList_getHandler(struct mwAwareList *list); 194 195 196 /** Add a collection of user IDs to an aware list. 197 @param list mwAwareList to add user ID to 198 @param id_list mwAwareIdBlock list of user IDs to add 199 @return 0 for success, non-zero to indicate an error. 200 */ 201 int mwAwareList_addAware(struct mwAwareList *list, GList *id_list); 202 203 204 /** Remove a collection of user IDs from an aware list. 205 @param list mwAwareList to remove user ID from 206 @param id_list mwAwareIdBlock list of user IDs to remove 207 @return 0 for success, non-zero to indicate an error. 208 */ 209 int mwAwareList_removeAware(struct mwAwareList *list, GList *id_list); 210 211 212 int mwAwareList_removeAllAware(struct mwAwareList *list); 213 214 215 /** watch an NULL terminated array of keys */ 216 int mwAwareList_watchAttributeArray(struct mwAwareList *list, 217 guint32 *keys); 218 219 220 /** watch a NULL terminated list of keys */ 221 int mwAwareList_watchAttributes(struct mwAwareList *list, 222 guint32 key, ...); 223 224 225 /** stop watching a NULL terminated array of keys */ 226 int mwAwareList_unwatchAttributeArray(struct mwAwareList *list, 227 guint32 *keys); 228 229 230 /** stop watching a NULL terminated list of keys */ 231 int mwAwareList_unwatchAttributes(struct mwAwareList *list, 232 guint32 key, ...); 233 234 235 /** remove all watched attributes */ 236 int mwAwareList_unwatchAllAttributes(struct mwAwareList *list); 237 238 239 guint32 *mwAwareList_getWatchedAttributes(struct mwAwareList *list); 240 241 242 void mwAwareList_setClientData(struct mwAwareList *list, 243 gpointer data, GDestroyNotify cleanup); 244 245 246 void mwAwareList_removeClientData(struct mwAwareList *list); 247 248 249 gpointer mwAwareList_getClientData(struct mwAwareList *list); 250 251 252 /** trigger a got_aware event constructed from the passed user and 253 status information. Useful for adding false users and having the 254 getText function work for them */ 255 void mwServiceAware_setStatus(struct mwServiceAware *srvc, 256 struct mwAwareIdBlock *user, 257 struct mwUserStatus *stat); 258 259 260 /** look up the status description for a user */ 261 const char *mwServiceAware_getText(struct mwServiceAware *srvc, 262 struct mwAwareIdBlock *user); 263 264 265 /** look up the last known copy of an attribute for a user by the 266 attribute's key */ 267 const struct mwAwareAttribute * 268 mwServiceAware_getAttribute(struct mwServiceAware *srvc, 269 struct mwAwareIdBlock *user, 270 guint32 key); 271 272 273 #ifdef __cplusplus 274 } 275 #endif 276 277 278 #endif /* _MW_SRVC_AWARE_H */ 279 280