Mercurial > pidgin
annotate libgaim/conversation.h @ 15122:c6978ee9ac4d
[gaim-migrate @ 17908]
maybe fix 1608655
committer: Tailor Script <tailor@pidgin.im>
author | Nathan Walp <nwalp@pidgin.im> |
---|---|
date | Thu, 07 Dec 2006 04:25:29 +0000 |
parents | 82b59abcaee4 |
children |
rev | line source |
---|---|
14192 | 1 /** |
2 * @file conversation.h Conversation API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 * | |
25 * @see @ref conversation-signals | |
26 */ | |
27 #ifndef _GAIM_CONVERSATION_H_ | |
28 #define _GAIM_CONVERSATION_H_ | |
29 | |
30 /**************************************************************************/ | |
31 /** Data Structures */ | |
32 /**************************************************************************/ | |
33 | |
34 | |
35 typedef struct _GaimConversationUiOps GaimConversationUiOps; | |
36 typedef struct _GaimConversation GaimConversation; | |
37 typedef struct _GaimConvIm GaimConvIm; | |
38 typedef struct _GaimConvChat GaimConvChat; | |
39 typedef struct _GaimConvChatBuddy GaimConvChatBuddy; | |
40 | |
41 /** | |
42 * A type of conversation. | |
43 */ | |
44 typedef enum | |
45 { | |
46 GAIM_CONV_TYPE_UNKNOWN = 0, /**< Unknown conversation type. */ | |
47 GAIM_CONV_TYPE_IM, /**< Instant Message. */ | |
48 GAIM_CONV_TYPE_CHAT, /**< Chat room. */ | |
49 GAIM_CONV_TYPE_MISC, /**< A misc. conversation. */ | |
50 GAIM_CONV_TYPE_ANY /**< Any type of conversation. */ | |
51 | |
52 } GaimConversationType; | |
53 | |
54 /** | |
55 * Conversation update type. | |
56 */ | |
57 typedef enum | |
58 { | |
59 GAIM_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation | |
60 was added. */ | |
61 GAIM_CONV_UPDATE_REMOVE, /**< The buddy associated with the conversation | |
62 was removed. */ | |
63 GAIM_CONV_UPDATE_ACCOUNT, /**< The gaim_account was changed. */ | |
64 GAIM_CONV_UPDATE_TYPING, /**< The typing state was updated. */ | |
65 GAIM_CONV_UPDATE_UNSEEN, /**< The unseen state was updated. */ | |
66 GAIM_CONV_UPDATE_LOGGING, /**< Logging for this conversation was | |
67 enabled or disabled. */ | |
68 GAIM_CONV_UPDATE_TOPIC, /**< The topic for a chat was updated. */ | |
69 /* | |
70 * XXX These need to go when we implement a more generic core/UI event | |
71 * system. | |
72 */ | |
73 GAIM_CONV_ACCOUNT_ONLINE, /**< One of the user's accounts went online. */ | |
74 GAIM_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */ | |
75 GAIM_CONV_UPDATE_AWAY, /**< The other user went away. */ | |
76 GAIM_CONV_UPDATE_ICON, /**< The other user's buddy icon changed. */ | |
77 GAIM_CONV_UPDATE_TITLE, | |
78 GAIM_CONV_UPDATE_CHATLEFT, | |
79 | |
80 GAIM_CONV_UPDATE_FEATURES, /**< The features for a chat have changed */ | |
81 | |
82 } GaimConvUpdateType; | |
83 | |
84 /** | |
85 * The typing state of a user. | |
86 */ | |
87 typedef enum | |
88 { | |
89 GAIM_NOT_TYPING = 0, /**< Not typing. */ | |
90 GAIM_TYPING, /**< Currently typing. */ | |
91 GAIM_TYPED /**< Stopped typing momentarily. */ | |
92 | |
93 } GaimTypingState; | |
94 | |
95 /** | |
96 * Flags applicable to a message. Most will have send, recv or system. | |
97 */ | |
98 typedef enum | |
99 { | |
100 GAIM_MESSAGE_SEND = 0x0001, /**< Outgoing message. */ | |
101 GAIM_MESSAGE_RECV = 0x0002, /**< Incoming message. */ | |
102 GAIM_MESSAGE_SYSTEM = 0x0004, /**< System message. */ | |
103 GAIM_MESSAGE_AUTO_RESP = 0x0008, /**< Auto response. */ | |
104 GAIM_MESSAGE_ACTIVE_ONLY = 0x0010, /**< Hint to the UI that this | |
105 message should not be | |
106 shown in conversations | |
107 which are only open for | |
108 internal UI purposes | |
109 (e.g. for contact-aware | |
110 conversions). */ | |
111 GAIM_MESSAGE_NICK = 0x0020, /**< Contains your nick. */ | |
112 GAIM_MESSAGE_NO_LOG = 0x0040, /**< Do not log. */ | |
113 GAIM_MESSAGE_WHISPER = 0x0080, /**< Whispered message. */ | |
114 GAIM_MESSAGE_ERROR = 0x0200, /**< Error message. */ | |
115 GAIM_MESSAGE_DELAYED = 0x0400, /**< Delayed message. */ | |
116 GAIM_MESSAGE_RAW = 0x0800, /**< "Raw" message - don't | |
117 apply formatting */ | |
118 GAIM_MESSAGE_IMAGES = 0x1000 /**< Message contains images */ | |
119 | |
120 } GaimMessageFlags; | |
121 | |
122 /** | |
123 * Flags applicable to users in Chats. | |
124 */ | |
125 typedef enum | |
126 { | |
127 GAIM_CBFLAGS_NONE = 0x0000, /**< No flags */ | |
128 GAIM_CBFLAGS_VOICE = 0x0001, /**< Voiced user or "Participant" */ | |
129 GAIM_CBFLAGS_HALFOP = 0x0002, /**< Half-op */ | |
130 GAIM_CBFLAGS_OP = 0x0004, /**< Channel Op or Moderator */ | |
131 GAIM_CBFLAGS_FOUNDER = 0x0008, /**< Channel Founder */ | |
132 GAIM_CBFLAGS_TYPING = 0x0010, /**< Currently typing */ | |
133 | |
134 } GaimConvChatBuddyFlags; | |
135 | |
136 #include "account.h" | |
137 #include "buddyicon.h" | |
138 #include "log.h" | |
139 #include "server.h" | |
140 | |
141 /** | |
142 * Conversation operations and events. | |
143 * | |
144 * Any UI representing a conversation must assign a filled-out | |
145 * GaimConversationUiOps structure to the GaimConversation. | |
146 */ | |
147 struct _GaimConversationUiOps | |
148 { | |
149 void (*create_conversation)(GaimConversation *conv); | |
150 void (*destroy_conversation)(GaimConversation *conv); | |
151 void (*write_chat)(GaimConversation *conv, const char *who, | |
152 const char *message, GaimMessageFlags flags, | |
153 time_t mtime); | |
154 void (*write_im)(GaimConversation *conv, const char *who, | |
155 const char *message, GaimMessageFlags flags, | |
156 time_t mtime); | |
157 void (*write_conv)(GaimConversation *conv, const char *name, const char *alias, | |
158 const char *message, GaimMessageFlags flags, | |
159 time_t mtime); | |
160 | |
161 void (*chat_add_users)(GaimConversation *conv, GList *cbuddies, gboolean new_arrivals); | |
162 | |
163 void (*chat_rename_user)(GaimConversation *conv, const char *old_name, | |
164 const char *new_name, const char *new_alias); | |
165 void (*chat_remove_users)(GaimConversation *conv, GList *users); | |
166 void (*chat_update_user)(GaimConversation *conv, const char *user); | |
167 | |
168 void (*present)(GaimConversation *conv); | |
169 | |
170 gboolean (*has_focus)(GaimConversation *conv); | |
171 | |
172 /* Custom Smileys */ | |
173 gboolean (*custom_smiley_add)(GaimConversation *conv, const char *smile, gboolean remote); | |
174 void (*custom_smiley_write)(GaimConversation *conv, const char *smile, | |
175 const guchar *data, gsize size); | |
176 void (*custom_smiley_close)(GaimConversation *conv, const char *smile); | |
14520
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
177 |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
178 void (*send_confirm)(GaimConversation *conv, const char *message); |
14192 | 179 }; |
180 | |
181 /** | |
182 * Data specific to Instant Messages. | |
183 */ | |
184 struct _GaimConvIm | |
185 { | |
186 GaimConversation *conv; /**< The parent conversation. */ | |
187 | |
188 GaimTypingState typing_state; /**< The current typing state. */ | |
189 guint typing_timeout; /**< The typing timer handle. */ | |
190 time_t type_again; /**< The type again time. */ | |
191 guint send_typed_timeout; /**< The type again timer handle. */ | |
192 | |
193 GaimBuddyIcon *icon; /**< The buddy icon. */ | |
194 }; | |
195 | |
196 /** | |
197 * Data specific to Chats. | |
198 */ | |
199 struct _GaimConvChat | |
200 { | |
201 GaimConversation *conv; /**< The parent conversation. */ | |
202 | |
203 GList *in_room; /**< The users in the room. */ | |
204 GList *ignored; /**< Ignored users. */ | |
205 char *who; /**< The person who set the topic. */ | |
206 char *topic; /**< The topic. */ | |
207 int id; /**< The chat ID. */ | |
208 char *nick; /**< Your nick in this chat. */ | |
209 | |
210 gboolean left; /**< We left the chat and kept the window open */ | |
211 }; | |
212 | |
213 /** | |
214 * Data for "Chat Buddies" | |
215 */ | |
216 struct _GaimConvChatBuddy | |
217 { | |
218 char *name; /**< The name */ | |
219 char *alias; /**< The alias */ | |
220 char *alias_key; /**< The alias key */ | |
221 gboolean buddy; /**< ChatBuddy is on the blist */ | |
222 GaimConvChatBuddyFlags flags; /**< Flags (ops, voice etc.) */ | |
223 }; | |
224 | |
225 /** | |
226 * A core representation of a conversation between two or more people. | |
227 * | |
228 * The conversation can be an IM or a chat. | |
229 */ | |
230 struct _GaimConversation | |
231 { | |
232 GaimConversationType type; /**< The type of conversation. */ | |
233 | |
234 GaimAccount *account; /**< The user using this conversation. */ | |
235 | |
236 | |
237 char *name; /**< The name of the conversation. */ | |
238 char *title; /**< The window title. */ | |
239 | |
240 gboolean logging; /**< The status of logging. */ | |
241 | |
242 GList *logs; /**< This conversation's logs */ | |
243 | |
244 union | |
245 { | |
246 GaimConvIm *im; /**< IM-specific data. */ | |
247 GaimConvChat *chat; /**< Chat-specific data. */ | |
248 void *misc; /**< Misc. data. */ | |
249 | |
250 } u; | |
251 | |
252 GaimConversationUiOps *ui_ops; /**< UI-specific operations. */ | |
253 void *ui_data; /**< UI-specific data. */ | |
254 | |
255 GHashTable *data; /**< Plugin-specific data. */ | |
256 | |
257 GaimConnectionFlags features; /**< The supported features */ | |
258 | |
259 }; | |
260 | |
261 #ifdef __cplusplus | |
262 extern "C" { | |
263 #endif | |
264 | |
265 /**************************************************************************/ | |
266 /** @name Conversation API */ | |
267 /**************************************************************************/ | |
268 /*@{*/ | |
269 | |
270 /** | |
271 * Creates a new conversation of the specified type. | |
272 * | |
273 * @param type The type of conversation. | |
274 * @param account The account opening the conversation window on the gaim | |
275 * user's end. | |
276 * @param name The name of the conversation. | |
277 * | |
278 * @return The new conversation. | |
279 */ | |
280 GaimConversation *gaim_conversation_new(GaimConversationType type, | |
281 GaimAccount *account, | |
282 const char *name); | |
283 | |
284 /** | |
285 * Destroys the specified conversation and removes it from the parent | |
286 * window. | |
287 * | |
288 * If this conversation is the only one contained in the parent window, | |
289 * that window is also destroyed. | |
290 * | |
291 * @param conv The conversation to destroy. | |
292 */ | |
293 void gaim_conversation_destroy(GaimConversation *conv); | |
294 | |
295 | |
296 /** | |
297 * Present a conversation to the user. This allows core code to initiate a | |
298 * conversation by displaying the IM dialog. | |
299 * @param conv The conversation to present | |
300 */ | |
301 void gaim_conversation_present(GaimConversation *conv); | |
302 | |
303 | |
304 /** | |
305 * Returns the specified conversation's type. | |
306 * | |
307 * @param conv The conversation. | |
308 * | |
309 * @return The conversation's type. | |
310 */ | |
311 GaimConversationType gaim_conversation_get_type(const GaimConversation *conv); | |
312 | |
313 /** | |
314 * Sets the specified conversation's UI operations structure. | |
315 * | |
316 * @param conv The conversation. | |
317 * @param ops The UI conversation operations structure. | |
318 */ | |
319 void gaim_conversation_set_ui_ops(GaimConversation *conv, | |
320 GaimConversationUiOps *ops); | |
321 | |
322 /** | |
323 * Sets the default conversation UI operations structure. | |
324 * | |
325 * @param ops The UI conversation operations structure. | |
326 */ | |
327 void gaim_conversations_set_ui_ops(GaimConversationUiOps *ops); | |
328 | |
329 /** | |
330 * Returns the specified conversation's UI operations structure. | |
331 * | |
332 * @param conv The conversation. | |
333 * | |
334 * @return The operations structure. | |
335 */ | |
336 GaimConversationUiOps *gaim_conversation_get_ui_ops( | |
337 const GaimConversation *conv); | |
338 | |
339 /** | |
340 * Sets the specified conversation's gaim_account. | |
341 * | |
342 * This gaim_account represents the user using gaim, not the person the user | |
343 * is having a conversation/chat/flame with. | |
344 * | |
345 * @param conv The conversation. | |
346 * @param account The gaim_account. | |
347 */ | |
348 void gaim_conversation_set_account(GaimConversation *conv, | |
349 GaimAccount *account); | |
350 | |
351 /** | |
352 * Returns the specified conversation's gaim_account. | |
353 * | |
354 * This gaim_account represents the user using gaim, not the person the user | |
355 * is having a conversation/chat/flame with. | |
356 * | |
357 * @param conv The conversation. | |
358 * | |
359 * @return The conversation's gaim_account. | |
360 */ | |
361 GaimAccount *gaim_conversation_get_account(const GaimConversation *conv); | |
362 | |
363 /** | |
364 * Returns the specified conversation's gaim_connection. | |
365 * | |
366 * This is the same as gaim_conversation_get_user(conv)->gc. | |
367 * | |
368 * @param conv The conversation. | |
369 * | |
370 * @return The conversation's gaim_connection. | |
371 */ | |
372 GaimConnection *gaim_conversation_get_gc(const GaimConversation *conv); | |
373 | |
374 /** | |
375 * Sets the specified conversation's title. | |
376 * | |
377 * @param conv The conversation. | |
378 * @param title The title. | |
379 */ | |
380 void gaim_conversation_set_title(GaimConversation *conv, const char *title); | |
381 | |
382 /** | |
383 * Returns the specified conversation's title. | |
384 * | |
385 * @param conv The conversation. | |
386 * | |
387 * @return The title. | |
388 */ | |
389 const char *gaim_conversation_get_title(const GaimConversation *conv); | |
390 | |
391 /** | |
392 * Automatically sets the specified conversation's title. | |
393 * | |
394 * This function takes OPT_IM_ALIAS_TAB into account, as well as the | |
395 * user's alias. | |
396 * | |
397 * @param conv The conversation. | |
398 */ | |
399 void gaim_conversation_autoset_title(GaimConversation *conv); | |
400 | |
401 /** | |
402 * Sets the specified conversation's name. | |
403 * | |
404 * @param conv The conversation. | |
405 * @param name The conversation's name. | |
406 */ | |
407 void gaim_conversation_set_name(GaimConversation *conv, const char *name); | |
408 | |
409 /** | |
410 * Returns the specified conversation's name. | |
411 * | |
412 * @param conv The conversation. | |
413 * | |
414 * @return The conversation's name. | |
415 */ | |
416 const char *gaim_conversation_get_name(const GaimConversation *conv); | |
417 | |
418 /** | |
419 * Enables or disables logging for this conversation. | |
420 * | |
421 * @param conv The conversation. | |
422 * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise. | |
423 */ | |
424 void gaim_conversation_set_logging(GaimConversation *conv, gboolean log); | |
425 | |
426 /** | |
427 * Returns whether or not logging is enabled for this conversation. | |
428 * | |
429 * @param conv The conversation. | |
430 * | |
431 * @return @c TRUE if logging is enabled, or @c FALSE otherwise. | |
432 */ | |
433 gboolean gaim_conversation_is_logging(const GaimConversation *conv); | |
434 | |
435 /** | |
436 * Closes any open logs for this conversation. | |
437 * | |
438 * Note that new logs will be opened as necessary (e.g. upon receipt of a | |
439 * message, if the conversation has logging enabled. To disable logging for | |
440 * the remainder of the conversation, use gaim_conversation_set_logging(). | |
441 * | |
442 * @param conv The conversation. | |
443 */ | |
444 void gaim_conversation_close_logs(GaimConversation *conv); | |
445 | |
446 /** | |
447 * Returns the specified conversation's IM-specific data. | |
448 * | |
449 * If the conversation type is not GAIM_CONV_TYPE_IM, this will return @c NULL. | |
450 * | |
451 * @param conv The conversation. | |
452 * | |
453 * @return The IM-specific data. | |
454 */ | |
455 GaimConvIm *gaim_conversation_get_im_data(const GaimConversation *conv); | |
456 | |
457 #define GAIM_CONV_IM(c) (gaim_conversation_get_im_data(c)) | |
458 | |
459 /** | |
460 * Returns the specified conversation's chat-specific data. | |
461 * | |
462 * If the conversation type is not GAIM_CONV_TYPE_CHAT, this will return @c NULL. | |
463 * | |
464 * @param conv The conversation. | |
465 * | |
466 * @return The chat-specific data. | |
467 */ | |
468 GaimConvChat *gaim_conversation_get_chat_data(const GaimConversation *conv); | |
469 | |
470 #define GAIM_CONV_CHAT(c) (gaim_conversation_get_chat_data(c)) | |
471 | |
472 /** | |
473 * Sets extra data for a conversation. | |
474 * | |
475 * @param conv The conversation. | |
476 * @param key The unique key. | |
477 * @param data The data to assign. | |
478 */ | |
479 void gaim_conversation_set_data(GaimConversation *conv, const char *key, | |
480 gpointer data); | |
481 | |
482 /** | |
483 * Returns extra data in a conversation. | |
484 * | |
485 * @param conv The conversation. | |
486 * @param key The unqiue key. | |
487 * | |
488 * @return The data associated with the key. | |
489 */ | |
490 gpointer gaim_conversation_get_data(GaimConversation *conv, const char *key); | |
491 | |
492 /** | |
493 * Returns a list of all conversations. | |
494 * | |
495 * This list includes both IMs and chats. | |
496 * | |
497 * @return A GList of all conversations. | |
498 */ | |
499 GList *gaim_get_conversations(void); | |
500 | |
501 /** | |
502 * Returns a list of all IMs. | |
503 * | |
504 * @return A GList of all IMs. | |
505 */ | |
506 GList *gaim_get_ims(void); | |
507 | |
508 /** | |
509 * Returns a list of all chats. | |
510 * | |
511 * @return A GList of all chats. | |
512 */ | |
513 GList *gaim_get_chats(void); | |
514 | |
515 /** | |
516 * Finds a conversation with the specified type, name, and Gaim account. | |
517 * | |
518 * @param type The type of the conversation. | |
519 * @param name The name of the conversation. | |
520 * @param account The gaim_account associated with the conversation. | |
521 * | |
522 * @return The conversation if found, or @c NULL otherwise. | |
523 */ | |
524 GaimConversation *gaim_find_conversation_with_account( | |
525 GaimConversationType type, const char *name, | |
526 const GaimAccount *account); | |
527 | |
528 /** | |
529 * Writes to a conversation window. | |
530 * | |
531 * This function should not be used to write IM or chat messages. Use | |
532 * gaim_conv_im_write() and gaim_conv_chat_write() instead. Those functions will | |
533 * most likely call this anyway, but they may do their own formatting, | |
534 * sound playback, etc. | |
535 * | |
536 * This can be used to write generic messages, such as "so and so closed | |
537 * the conversation window." | |
538 * | |
539 * @param conv The conversation. | |
540 * @param who The user who sent the message. | |
541 * @param message The message. | |
542 * @param flags The message flags. | |
543 * @param mtime The time the message was sent. | |
544 * | |
545 * @see gaim_conv_im_write() | |
546 * @see gaim_conv_chat_write() | |
547 */ | |
548 void gaim_conversation_write(GaimConversation *conv, const char *who, | |
549 const char *message, GaimMessageFlags flags, | |
550 time_t mtime); | |
551 | |
552 | |
553 /** | |
554 Set the features as supported for the given conversation. | |
555 @param conv The conversation | |
556 @param features Bitset defining supported features | |
557 */ | |
558 void gaim_conversation_set_features(GaimConversation *conv, | |
559 GaimConnectionFlags features); | |
560 | |
561 | |
562 /** | |
563 Get the features supported by the given conversation. | |
564 @param conv The conversation | |
565 */ | |
566 GaimConnectionFlags gaim_conversation_get_features(GaimConversation *conv); | |
567 | |
568 /** | |
569 * Determines if a conversation has focus | |
570 * | |
571 * @param conv The conversation. | |
572 * | |
573 * @return @c TRUE if the conversation has focus, @c FALSE if | |
574 * it does not or the UI does not have a concept of conversation focus | |
575 */ | |
576 gboolean gaim_conversation_has_focus(GaimConversation *conv); | |
577 | |
578 /** | |
579 * Updates the visual status and UI of a conversation. | |
580 * | |
581 * @param conv The conversation. | |
582 * @param type The update type. | |
583 */ | |
584 void gaim_conversation_update(GaimConversation *conv, GaimConvUpdateType type); | |
585 | |
586 /** | |
587 * Calls a function on each conversation. | |
588 * | |
589 * @param func The function. | |
590 */ | |
591 void gaim_conversation_foreach(void (*func)(GaimConversation *conv)); | |
592 | |
593 /*@}*/ | |
594 | |
595 | |
596 /**************************************************************************/ | |
597 /** @name IM Conversation API */ | |
598 /**************************************************************************/ | |
599 /*@{*/ | |
600 | |
601 /** | |
602 * Gets an IM's parent conversation. | |
603 * | |
604 * @param im The IM. | |
605 * | |
606 * @return The parent conversation. | |
607 */ | |
608 GaimConversation *gaim_conv_im_get_conversation(const GaimConvIm *im); | |
609 | |
610 /** | |
611 * Sets the IM's buddy icon. | |
612 * | |
613 * This should only be called from within Gaim. You probably want to | |
614 * call gaim_buddy_icon_set_data(). | |
615 * | |
616 * @param im The IM. | |
617 * @param icon The buddy icon. | |
618 * | |
619 * @see gaim_buddy_icon_set_data() | |
620 */ | |
621 void gaim_conv_im_set_icon(GaimConvIm *im, GaimBuddyIcon *icon); | |
622 | |
623 /** | |
624 * Returns the IM's buddy icon. | |
625 * | |
626 * @param im The IM. | |
627 * | |
628 * @return The buddy icon. | |
629 */ | |
630 GaimBuddyIcon *gaim_conv_im_get_icon(const GaimConvIm *im); | |
631 | |
632 /** | |
633 * Sets the IM's typing state. | |
634 * | |
635 * @param im The IM. | |
636 * @param state The typing state. | |
637 */ | |
638 void gaim_conv_im_set_typing_state(GaimConvIm *im, GaimTypingState state); | |
639 | |
640 /** | |
641 * Returns the IM's typing state. | |
642 * | |
643 * @param im The IM. | |
644 * | |
645 * @return The IM's typing state. | |
646 */ | |
647 GaimTypingState gaim_conv_im_get_typing_state(const GaimConvIm *im); | |
648 | |
649 /** | |
650 * Starts the IM's typing timeout. | |
651 * | |
652 * @param im The IM. | |
653 * @param timeout The timeout. | |
654 */ | |
655 void gaim_conv_im_start_typing_timeout(GaimConvIm *im, int timeout); | |
656 | |
657 /** | |
658 * Stops the IM's typing timeout. | |
659 * | |
660 * @param im The IM. | |
661 */ | |
662 void gaim_conv_im_stop_typing_timeout(GaimConvIm *im); | |
663 | |
664 /** | |
665 * Returns the IM's typing timeout. | |
666 * | |
667 * @param im The IM. | |
668 * | |
669 * @return The timeout. | |
670 */ | |
671 guint gaim_conv_im_get_typing_timeout(const GaimConvIm *im); | |
672 | |
673 /** | |
674 * Sets the quiet-time when no GAIM_TYPING messages will be sent. | |
675 * Few protocols need this (maybe only MSN). If the user is still | |
676 * typing after this quiet-period, then another GAIM_TYPING message | |
677 * will be sent. | |
678 * | |
679 * @param im The IM. | |
680 * @param val The number of seconds to wait before allowing another | |
681 * GAIM_TYPING message to be sent to the user. Or 0 to | |
682 * not send another GAIM_TYPING message. | |
683 */ | |
684 void gaim_conv_im_set_type_again(GaimConvIm *im, unsigned int val); | |
685 | |
686 /** | |
687 * Returns the time after which another GAIM_TYPING message should be sent. | |
688 * | |
689 * @param im The IM. | |
690 * | |
691 * @return The time in seconds since the epoch. Or 0 if no additional | |
692 * GAIM_TYPING message should be sent. | |
693 */ | |
694 time_t gaim_conv_im_get_type_again(const GaimConvIm *im); | |
695 | |
696 /** | |
697 * Starts the IM's type again timeout. | |
698 * | |
699 * @param im The IM. | |
700 */ | |
701 void gaim_conv_im_start_send_typed_timeout(GaimConvIm *im); | |
702 | |
703 /** | |
704 * Stops the IM's type again timeout. | |
705 * | |
706 * @param im The IM. | |
707 */ | |
708 void gaim_conv_im_stop_send_typed_timeout(GaimConvIm *im); | |
709 | |
710 /** | |
711 * Returns the IM's type again timeout interval. | |
712 * | |
713 * @param im The IM. | |
714 * | |
715 * @return The type again timeout interval. | |
716 */ | |
717 guint gaim_conv_im_get_send_typed_timeout(const GaimConvIm *im); | |
718 | |
719 /** | |
720 * Updates the visual typing notification for an IM conversation. | |
721 * | |
722 * @param im The IM. | |
723 */ | |
724 void gaim_conv_im_update_typing(GaimConvIm *im); | |
725 | |
726 /** | |
727 * Writes to an IM. | |
728 * | |
729 * @param im The IM. | |
730 * @param who The user who sent the message. | |
731 * @param message The message to write. | |
732 * @param flags The message flags. | |
733 * @param mtime The time the message was sent. | |
734 */ | |
735 void gaim_conv_im_write(GaimConvIm *im, const char *who, | |
736 const char *message, GaimMessageFlags flags, | |
737 time_t mtime); | |
738 | |
739 /** | |
740 * Presents an IM-error to the user | |
741 * | |
742 * This is a helper function to find a conversation, write an error to it, and | |
743 * raise the window. If a conversation with this user doesn't already exist, | |
744 * the function will return FALSE and the calling function can attempt to present | |
745 * the error another way (gaim_notify_error, most likely) | |
746 * | |
747 * @param who The user this error is about | |
748 * @param account The account this error is on | |
749 * @param what The error | |
750 * @return TRUE if the error was presented, else FALSE | |
751 */ | |
752 gboolean gaim_conv_present_error(const char *who, GaimAccount *account, const char *what); | |
753 | |
754 /** | |
755 * Sends a message to this IM conversation. | |
756 * | |
757 * @param im The IM. | |
758 * @param message The message to send. | |
759 */ | |
760 void gaim_conv_im_send(GaimConvIm *im, const char *message); | |
761 | |
762 /** | |
14520
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
763 * Sends a message to a conversation after confirming with |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
764 * the user. |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
765 * |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
766 * This function is intended for use in cases where the user |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
767 * hasn't explicitly and knowingly caused a message to be sent. |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
768 * The confirmation ensures that the user isn't sending a |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
769 * message by mistake. |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
770 * |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
771 * @param conv The conversation. |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
772 * @param message The message to send. |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
773 */ |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
774 void gaim_conv_send_confirm(GaimConversation *conv, const char *message); |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
775 |
82b59abcaee4
[gaim-migrate @ 17240]
Richard Laager <rlaager@wiktel.com>
parents:
14192
diff
changeset
|
776 /** |
14192 | 777 * Sends a message to this IM conversation with specified flags. |
778 * | |
779 * @param im The IM. | |
780 * @param message The message to send. | |
781 * @param flags The GaimMessageFlags flags to use in addition to GAIM_MESSAGE_SEND. | |
782 */ | |
783 void gaim_conv_im_send_with_flags(GaimConvIm *im, const char *message, GaimMessageFlags flags); | |
784 | |
785 /** | |
786 * Adds a smiley to the conversation's smiley tree. If this returns | |
787 * @c TRUE you should call gaim_conv_custom_smiley_write() one or more | |
788 * times, and then gaim_conv_custom_smiley_close(). If this returns | |
789 * @c FALSE, either the conv or smile were invalid, or the icon was | |
790 * found in the cache. In either case, calling write or close would | |
791 * be an error. | |
792 * | |
793 * @param conv The conversation to associate the smiley with. | |
794 * @param smile The text associated with the smiley | |
795 * @param cksum_type The type of checksum. | |
796 * @param chksum The checksum, as a NUL terminated base64 string. | |
797 * @param remote @c TRUE if the custom smiley is set by the remote user (buddy). | |
798 * @return @c TRUE if an icon is expected, else FALSE. Note that | |
799 * it is an error to never call gaim_conv_custom_smiley_close if | |
800 * this function returns @c TRUE, but an error to call it if | |
801 * @c FALSE is returned. | |
802 */ | |
803 | |
804 gboolean gaim_conv_custom_smiley_add(GaimConversation *conv, const char *smile, | |
805 const char *cksum_type, const char *chksum, | |
806 gboolean remote); | |
807 | |
808 | |
809 /** | |
810 * Updates the image associated with the current smiley. | |
811 * | |
812 * @param conv The conversation associated with the smiley. | |
813 * @param smile The text associated with the smiley. | |
814 * @param data The actual image data. | |
815 * @param size The length of the data. | |
816 */ | |
817 | |
818 void gaim_conv_custom_smiley_write(GaimConversation *conv, | |
819 const char *smile, | |
820 const guchar *data, | |
821 gsize size); | |
822 | |
823 /** | |
824 * Close the custom smiley, all data has been written with | |
825 * gaim_conv_custom_smiley_write, and it is no longer valid | |
826 * to call that function on that smiley. | |
827 * | |
828 * @param conv The gaim conversation associated with the smiley. | |
829 * @param smile The text associated with the smiley | |
830 */ | |
831 | |
832 void gaim_conv_custom_smiley_close(GaimConversation *conv, const char *smile); | |
833 | |
834 /*@}*/ | |
835 | |
836 | |
837 /**************************************************************************/ | |
838 /** @name Chat Conversation API */ | |
839 /**************************************************************************/ | |
840 /*@{*/ | |
841 | |
842 /** | |
843 * Gets a chat's parent conversation. | |
844 * | |
845 * @param chat The chat. | |
846 * | |
847 * @return The parent conversation. | |
848 */ | |
849 GaimConversation *gaim_conv_chat_get_conversation(const GaimConvChat *chat); | |
850 | |
851 /** | |
852 * Sets the list of users in the chat room. | |
853 * | |
854 * @note Calling this function will not update the display of the users. | |
855 * Please use gaim_conv_chat_add_user(), gaim_conv_chat_add_users(), | |
856 * gaim_conv_chat_remove_user(), and gaim_conv_chat_remove_users() instead. | |
857 * | |
858 * @param chat The chat. | |
859 * @param users The list of users. | |
860 * | |
861 * @return The list passed. | |
862 */ | |
863 GList *gaim_conv_chat_set_users(GaimConvChat *chat, GList *users); | |
864 | |
865 /** | |
866 * Returns a list of users in the chat room. | |
867 * | |
868 * @param chat The chat. | |
869 * | |
870 * @return The list of users. | |
871 */ | |
872 GList *gaim_conv_chat_get_users(const GaimConvChat *chat); | |
873 | |
874 /** | |
875 * Ignores a user in a chat room. | |
876 * | |
877 * @param chat The chat. | |
878 * @param name The name of the user. | |
879 */ | |
880 void gaim_conv_chat_ignore(GaimConvChat *chat, const char *name); | |
881 | |
882 /** | |
883 * Unignores a user in a chat room. | |
884 * | |
885 * @param chat The chat. | |
886 * @param name The name of the user. | |
887 */ | |
888 void gaim_conv_chat_unignore(GaimConvChat *chat, const char *name); | |
889 | |
890 /** | |
891 * Sets the list of ignored users in the chat room. | |
892 * | |
893 * @param chat The chat. | |
894 * @param ignored The list of ignored users. | |
895 * | |
896 * @return The list passed. | |
897 */ | |
898 GList *gaim_conv_chat_set_ignored(GaimConvChat *chat, GList *ignored); | |
899 | |
900 /** | |
901 * Returns the list of ignored users in the chat room. | |
902 * | |
903 * @param chat The chat. | |
904 * | |
905 * @return The list of ignored users. | |
906 */ | |
907 GList *gaim_conv_chat_get_ignored(const GaimConvChat *chat); | |
908 | |
909 /** | |
910 * Returns the actual name of the specified ignored user, if it exists in | |
911 * the ignore list. | |
912 * | |
913 * If the user found contains a prefix, such as '+' or '\@', this is also | |
914 * returned. The username passed to the function does not have to have this | |
915 * formatting. | |
916 * | |
917 * @param chat The chat. | |
918 * @param user The user to check in the ignore list. | |
919 * | |
920 * @return The ignored user if found, complete with prefixes, or @c NULL | |
921 * if not found. | |
922 */ | |
923 const char *gaim_conv_chat_get_ignored_user(const GaimConvChat *chat, | |
924 const char *user); | |
925 | |
926 /** | |
927 * Returns @c TRUE if the specified user is ignored. | |
928 * | |
929 * @param chat The chat. | |
930 * @param user The user. | |
931 * | |
932 * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise. | |
933 */ | |
934 gboolean gaim_conv_chat_is_user_ignored(const GaimConvChat *chat, | |
935 const char *user); | |
936 | |
937 /** | |
938 * Sets the chat room's topic. | |
939 * | |
940 * @param chat The chat. | |
941 * @param who The user that set the topic. | |
942 * @param topic The topic. | |
943 */ | |
944 void gaim_conv_chat_set_topic(GaimConvChat *chat, const char *who, | |
945 const char *topic); | |
946 | |
947 /** | |
948 * Returns the chat room's topic. | |
949 * | |
950 * @param chat The chat. | |
951 * | |
952 * @return The chat's topic. | |
953 */ | |
954 const char *gaim_conv_chat_get_topic(const GaimConvChat *chat); | |
955 | |
956 /** | |
957 * Sets the chat room's ID. | |
958 * | |
959 * @param chat The chat. | |
960 * @param id The ID. | |
961 */ | |
962 void gaim_conv_chat_set_id(GaimConvChat *chat, int id); | |
963 | |
964 /** | |
965 * Returns the chat room's ID. | |
966 * | |
967 * @param chat The chat. | |
968 * | |
969 * @return The ID. | |
970 */ | |
971 int gaim_conv_chat_get_id(const GaimConvChat *chat); | |
972 | |
973 /** | |
974 * Writes to a chat. | |
975 * | |
976 * @param chat The chat. | |
977 * @param who The user who sent the message. | |
978 * @param message The message to write. | |
979 * @param flags The flags. | |
980 * @param mtime The time the message was sent. | |
981 */ | |
982 void gaim_conv_chat_write(GaimConvChat *chat, const char *who, | |
983 const char *message, GaimMessageFlags flags, | |
984 time_t mtime); | |
985 | |
986 /** | |
987 * Sends a message to this chat conversation. | |
988 * | |
989 * @param chat The chat. | |
990 * @param message The message to send. | |
991 */ | |
992 void gaim_conv_chat_send(GaimConvChat *chat, const char *message); | |
993 | |
994 /** | |
995 * Sends a message to this chat conversation with specified flags. | |
996 * | |
997 * @param chat The chat. | |
998 * @param message The message to send. | |
999 * @param flags The GaimMessageFlags flags to use. | |
1000 */ | |
1001 void gaim_conv_chat_send_with_flags(GaimConvChat *chat, const char *message, GaimMessageFlags flags); | |
1002 | |
1003 /** | |
1004 * Adds a user to a chat. | |
1005 * | |
1006 * @param chat The chat. | |
1007 * @param user The user to add. | |
1008 * @param extra_msg An extra message to display with the join message. | |
1009 * @param flags The users flags | |
1010 * @param new_arrival Decides whether or not to show a join notice. | |
1011 */ | |
1012 void gaim_conv_chat_add_user(GaimConvChat *chat, const char *user, | |
1013 const char *extra_msg, GaimConvChatBuddyFlags flags, | |
1014 gboolean new_arrival); | |
1015 | |
1016 /** | |
1017 * Adds a list of users to a chat. | |
1018 * | |
1019 * The data is copied from @a users, @a extra_msgs, and @a flags, so it is up to | |
1020 * the caller to free this list after calling this function. | |
1021 * | |
1022 * @param chat The chat. | |
1023 * @param users The list of users to add. | |
1024 * @param extra_msgs An extra message to display with the join message for each | |
1025 * user. This list may be shorter than @a users, in which | |
1026 * case, the users after the end of extra_msgs will not have | |
1027 * an extra message. By extension, this means that extra_msgs | |
1028 * can simply be @c NULL and none of the users will have an | |
1029 * extra message. | |
1030 * @param flags The list of flags for each user. | |
1031 * @param new_arrivals Decides whether or not to show join notices. | |
1032 */ | |
1033 void gaim_conv_chat_add_users(GaimConvChat *chat, GList *users, GList *extra_msgs, | |
1034 GList *flags, gboolean new_arrivals); | |
1035 | |
1036 /** | |
1037 * Renames a user in a chat. | |
1038 * | |
1039 * @param chat The chat. | |
1040 * @param old_user The old username. | |
1041 * @param new_user The new username. | |
1042 */ | |
1043 void gaim_conv_chat_rename_user(GaimConvChat *chat, const char *old_user, | |
1044 const char *new_user); | |
1045 | |
1046 /** | |
1047 * Removes a user from a chat, optionally with a reason. | |
1048 * | |
1049 * It is up to the developer to free this list after calling this function. | |
1050 * | |
1051 * @param chat The chat. | |
1052 * @param user The user that is being removed. | |
1053 * @param reason The optional reason given for the removal. Can be @c NULL. | |
1054 */ | |
1055 void gaim_conv_chat_remove_user(GaimConvChat *chat, const char *user, | |
1056 const char *reason); | |
1057 | |
1058 /** | |
1059 * Removes a list of users from a chat, optionally with a single reason. | |
1060 * | |
1061 * @param chat The chat. | |
1062 * @param users The users that are being removed. | |
1063 * @param reason The optional reason given for the removal. Can be @c NULL. | |
1064 */ | |
1065 void gaim_conv_chat_remove_users(GaimConvChat *chat, GList *users, | |
1066 const char *reason); | |
1067 | |
1068 /** | |
1069 * Finds a user in a chat | |
1070 * | |
1071 * @param chat The chat. | |
1072 * @param user The user to look for. | |
1073 * | |
1074 * @return TRUE if the user is in the chat, FALSE if not | |
1075 */ | |
1076 gboolean gaim_conv_chat_find_user(GaimConvChat *chat, const char *user); | |
1077 | |
1078 /** | |
1079 * Set a users flags in a chat | |
1080 * | |
1081 * @param chat The chat. | |
1082 * @param user The user to update. | |
1083 * @param flags The new flags. | |
1084 */ | |
1085 void gaim_conv_chat_user_set_flags(GaimConvChat *chat, const char *user, | |
1086 GaimConvChatBuddyFlags flags); | |
1087 | |
1088 /** | |
1089 * Get the flags for a user in a chat | |
1090 * | |
1091 * @param chat The chat. | |
1092 * @param user The user to find the flags for | |
1093 * | |
1094 * @return The flags for the user | |
1095 */ | |
1096 GaimConvChatBuddyFlags gaim_conv_chat_user_get_flags(GaimConvChat *chat, | |
1097 const char *user); | |
1098 | |
1099 /** | |
1100 * Clears all users from a chat. | |
1101 * | |
1102 * @param chat The chat. | |
1103 */ | |
1104 void gaim_conv_chat_clear_users(GaimConvChat *chat); | |
1105 | |
1106 /** | |
1107 * Sets your nickname (used for hilighting) for a chat. | |
1108 * | |
1109 * @param chat The chat. | |
1110 * @param nick The nick. | |
1111 */ | |
1112 void gaim_conv_chat_set_nick(GaimConvChat *chat, const char *nick); | |
1113 | |
1114 /** | |
1115 * Gets your nickname (used for hilighting) for a chat. | |
1116 * | |
1117 * @param chat The chat. | |
1118 * @return The nick. | |
1119 */ | |
1120 const char *gaim_conv_chat_get_nick(GaimConvChat *chat); | |
1121 | |
1122 /** | |
1123 * Finds a chat with the specified chat ID. | |
1124 * | |
1125 * @param gc The gaim_connection. | |
1126 * @param id The chat ID. | |
1127 * | |
1128 * @return The chat conversation. | |
1129 */ | |
1130 GaimConversation *gaim_find_chat(const GaimConnection *gc, int id); | |
1131 | |
1132 /** | |
1133 * Lets the core know we left a chat, without destroying it. | |
1134 * Called from serv_got_chat_left(). | |
1135 * | |
1136 * @param chat The chat. | |
1137 */ | |
1138 void gaim_conv_chat_left(GaimConvChat *chat); | |
1139 | |
1140 /** | |
1141 * Returns true if we're no longer in this chat, | |
1142 * and just left the window open. | |
1143 * | |
1144 * @param chat The chat. | |
1145 * | |
1146 * @return @c TRUE if we left the chat already, @c FALSE if | |
1147 * we're still there. | |
1148 */ | |
1149 gboolean gaim_conv_chat_has_left(GaimConvChat *chat); | |
1150 | |
1151 /** | |
1152 * Creates a new chat buddy | |
1153 * | |
1154 * @param name The name. | |
1155 * @param alias The alias. | |
1156 * @param flags The flags. | |
1157 * | |
1158 * @return The new chat buddy | |
1159 */ | |
1160 GaimConvChatBuddy *gaim_conv_chat_cb_new(const char *name, const char *alias, | |
1161 GaimConvChatBuddyFlags flags); | |
1162 | |
1163 /** | |
1164 * Find a chat buddy in a chat | |
1165 * | |
1166 * @param chat The chat. | |
1167 * @param name The name of the chat buddy to find. | |
1168 */ | |
1169 GaimConvChatBuddy *gaim_conv_chat_cb_find(GaimConvChat *chat, const char *name); | |
1170 | |
1171 /** | |
1172 * Get the name of a chat buddy | |
1173 * | |
1174 * @param cb The chat buddy. | |
1175 * | |
1176 * @return The name of the chat buddy. | |
1177 */ | |
1178 const char *gaim_conv_chat_cb_get_name(GaimConvChatBuddy *cb); | |
1179 | |
1180 /** | |
1181 * Destroys a chat buddy | |
1182 * | |
1183 * @param cb The chat buddy to destroy | |
1184 */ | |
1185 void gaim_conv_chat_cb_destroy(GaimConvChatBuddy *cb); | |
1186 | |
1187 /*@}*/ | |
1188 | |
1189 /**************************************************************************/ | |
1190 /** @name Conversations Subsystem */ | |
1191 /**************************************************************************/ | |
1192 /*@{*/ | |
1193 | |
1194 /** | |
1195 * Returns the conversation subsystem handle. | |
1196 * | |
1197 * @return The conversation subsystem handle. | |
1198 */ | |
1199 void *gaim_conversations_get_handle(void); | |
1200 | |
1201 /** | |
1202 * Initializes the conversation subsystem. | |
1203 */ | |
1204 void gaim_conversations_init(void); | |
1205 | |
1206 /** | |
1207 * Uninitializes the conversation subsystem. | |
1208 */ | |
1209 void gaim_conversations_uninit(void); | |
1210 | |
1211 /*@}*/ | |
1212 | |
1213 #ifdef __cplusplus | |
1214 } | |
1215 #endif | |
1216 | |
1217 #endif /* _GAIM_CONVERSATION_H_ */ |