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_IM_H 22 #define _MW_SRVC_IM_H 23 24 25 /** @file mw_srvc_im.h 26 27 The IM service provides one-on-one communication between 28 users. Messages sent over conversations may relay different types 29 of information, in a variety of formats. The basic feature-set 30 provides plain-text chat with typing notification. More complex 31 features may be negotiated transparently by setting the IM Client 32 Type for a conversation, or for the service as a whole. 33 */ 34 35 36 #include <glib.h> 37 #include "mw_common.h" 38 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 45 /* identifier for the IM service */ 46 #define mwService_IM 0x00001000 47 48 49 /** @struct mwServiceIm 50 51 An instance of the IM service. This service provides simple 52 instant messaging functionality */ 53 struct mwServiceIm; 54 55 56 /** @struct mwConversation 57 58 A conversation between the local service and a single other user */ 59 struct mwConversation; 60 61 62 enum mwImClientType { 63 mwImClient_PLAIN = 0x00000001, /**< text, typing */ 64 mwImClient_NOTESBUDDY = 0x00033453, /**< adds html, subject, mime */ 65 mwImClient_PRECONF = 0x00000019, /**< pre-conference, legacy */ 66 mwImClient_UNKNOWN = 0xffffffff, /**< trouble determining type */ 67 }; 68 69 70 /** 71 Types of supported messages. When a conversation is created, the 72 least common denominator of features between either side of the 73 conversation (based on what features are available in the IM 74 service itself) becomes the set of supported features for that 75 conversation. At any point, the feature set for the service may 76 change, without affecting any existing conversations. 77 78 @see mwServiceIm_supports 79 @see mwServiceIm_setSupported 80 @see mwConversation_supports 81 @see mwConversation_send 82 @see mwServiceImHandler::conversation_recv 83 */ 84 enum mwImSendType { 85 mwImSend_PLAIN, /**< char *, plain-text message */ 86 mwImSend_TYPING, /**< gboolean, typing status */ 87 mwImSend_HTML, /**< char *, HTML formatted message (NOTESBUDDY) */ 88 mwImSend_SUBJECT, /**< char *, conversation subject (NOTESBUDDY) */ 89 mwImSend_MIME, /**< char *, MIME-encoded message (NOTESBUDDY) */ 90 mwImSend_TIMESTAMP, /**< char *, YYYY:MM:DD:HH:mm:SS format (NOTESBUDDY) */ 91 }; 92 93 94 95 /** @see mwConversation_getState */ 96 enum mwConversationState { 97 mwConversation_CLOSED, /**< conversation is not open */ 98 mwConversation_PENDING, /**< conversation is opening */ 99 mwConversation_OPEN, /**< conversation is open */ 100 mwConversation_UNKNOWN, /**< unknown state */ 101 }; 102 103 104 #define mwConversation_isState(conv, state) \ 105 (mwConversation_getState(conv) == (state)) 106 107 #define mwConversation_isClosed(conv) \ 108 mwConversation_isState((conv), mwConversation_CLOSED) 109 110 #define mwConversation_isPending(conv) \ 111 mwConversation_isState((conv), mwConversation_PENDING) 112 113 #define mwConversation_isOpen(conv) \ 114 mwConversation_isState((conv), mwConversation_OPEN) 115 116 117 118 /** IM Service Handler. Provides functions for events triggered from an 119 IM service instance. */ 120 struct mwImHandler { 121 122 /** A conversation has been successfully opened */ 123 void (*conversation_opened)(struct mwConversation *conv); 124 125 /** A conversation has been closed */ 126 void (*conversation_closed)(struct mwConversation *conv, guint32 err); 127 128 /** A message has been received on a conversation */ 129 void (*conversation_recv)(struct mwConversation *conv, 130 enum mwImSendType type, gconstpointer msg); 131 132 /** Handle a Place invitation. Set this to NULL and we should end up 133 receiving a conference invitation instead. */ 134 void (*place_invite)(struct mwConversation *conv, 135 const char *message, 136 const char *title, const char *name); 137 138 /** optional. called from mwService_free */ 139 void (*clear)(struct mwServiceIm *srvc); 140 }; 141 142 143 struct mwServiceIm *mwServiceIm_new(struct mwSession *session, 144 struct mwImHandler *handler); 145 146 147 struct mwImHandler *mwServiceIm_getHandler(struct mwServiceIm *srvc); 148 149 150 /** reference an existing conversation to target, or create a new 151 conversation to target if one does not already exist */ 152 struct mwConversation *mwServiceIm_getConversation(struct mwServiceIm *srvc, 153 struct mwIdBlock *target); 154 155 156 /** reference an existing conversation to target */ 157 struct mwConversation *mwServiceIm_findConversation(struct mwServiceIm *srvc, 158 struct mwIdBlock *target); 159 160 161 /** determine if the conversations created from this service will 162 support a given send type */ 163 gboolean mwServiceIm_supports(struct mwServiceIm *srvc, 164 enum mwImSendType type); 165 166 167 /** Set the default client type for the service. Newly created 168 conversations will attempt to meet this level of functionality 169 first. 170 171 @param srvc the IM service 172 @param type the send type to enable/disable 173 */ 174 void mwServiceIm_setClientType(struct mwServiceIm *srvc, 175 enum mwImClientType type); 176 177 178 enum mwImClientType mwServiceIm_getClientType(struct mwServiceIm *srvc); 179 180 181 /** attempt to open a conversation. If the conversation was not 182 already open and it is accepted, 183 mwServiceImHandler::conversation_opened will be triggered. Upon 184 failure, mwServiceImHandler::conversation_closed will be 185 triggered */ 186 void mwConversation_open(struct mwConversation *conv); 187 188 189 /** close a conversation. If the conversation was not already closed, 190 mwServiceImHandler::conversation_closed will be triggered */ 191 void mwConversation_close(struct mwConversation *conv, guint32 err); 192 193 194 /** determine whether a conversation supports the given message type */ 195 gboolean mwConversation_supports(struct mwConversation *conv, 196 enum mwImSendType type); 197 198 199 enum mwImClientType mwConversation_getClientType(struct mwConversation *conv); 200 201 202 /** get the state of a conversation 203 204 @see mwConversation_isOpen 205 @see mwConversation_isClosed 206 @see mwConversation_isPending 207 */ 208 enum mwConversationState mwConversation_getState(struct mwConversation *conv); 209 210 211 /** send a message over an open conversation */ 212 int mwConversation_send(struct mwConversation *conv, 213 enum mwImSendType type, gconstpointer send); 214 215 216 /** @returns owning service for a conversation */ 217 struct mwServiceIm *mwConversation_getService(struct mwConversation *conv); 218 219 220 /** login information for conversation partner. returns NULL if conversation 221 is not OPEN */ 222 struct mwLoginInfo *mwConversation_getTargetInfo(struct mwConversation *conv); 223 224 225 /** ID for conversation partner */ 226 struct mwIdBlock *mwConversation_getTarget(struct mwConversation *conv); 227 228 229 /** set whether outgoing messages should be encrypted using the 230 negotiated cipher, if any */ 231 void mwConversation_setEncrypted(struct mwConversation *conv, 232 gboolean useCipher); 233 234 235 /** determine whether outgoing messages are being encrypted */ 236 gboolean mwConversation_isEncrypted(struct mwConversation *conv); 237 238 239 /** Associates client data with a conversation. If there is existing data, 240 it will not have its cleanup function called. 241 242 @see mwConversation_getClientData 243 @see mwConversation_removeClientData 244 */ 245 void mwConversation_setClientData(struct mwConversation *conv, 246 gpointer data, GDestroyNotify clean); 247 248 249 /** Reference associated client data 250 251 @see mwConversation_setClientData 252 @see mwConversation_removeClientData 253 */ 254 gpointer mwConversation_getClientData(struct mwConversation *conv); 255 256 257 /** Remove any associated client data, calling the optional cleanup 258 function if one was provided 259 260 @see mwConversation_setClientData 261 @see mwConversation_getClientData 262 */ 263 void mwConversation_removeClientData(struct mwConversation *conv); 264 265 266 /** close and destroy the conversation and its backing channel, and 267 call the optional client data cleanup function */ 268 void mwConversation_free(struct mwConversation *conv); 269 270 271 #ifdef __cplusplus 272 } 273 #endif 274 275 276 #endif /* _MW_SRVC_IM_H */ 277