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