Mercurial > pidgin3 / file comparison

comparison: src/conversation.h

src/conversation.h

branch
cpw.khc.msnp14
changeset 20472
6a6d2ef151e6
parent 13912
463b4fa9f067
parent 20469
b2836a24d81e
child 20473
91e1b3a49d10
equal deleted inserted replaced
13912:463b4fa9f067 20472:6a6d2ef151e6
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 *users,
162 GList *flags, GList *aliases, gboolean new_arrivals);
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);
177 };
178
179 /**
180 * Data specific to Instant Messages.
181 */
182 struct _GaimConvIm
183 {
184 GaimConversation *conv; /**< The parent conversation. */
185
186 GaimTypingState typing_state; /**< The current typing state. */
187 guint typing_timeout; /**< The typing timer handle. */
188 time_t type_again; /**< The type again time. */
189 guint send_typed_timeout; /**< The type again timer handle. */
190
191 GaimBuddyIcon *icon; /**< The buddy icon. */
192 };
193
194 /**
195 * Data specific to Chats.
196 */
197 struct _GaimConvChat
198 {
199 GaimConversation *conv; /**< The parent conversation. */
200
201 GList *in_room; /**< The users in the room. */
202 GList *ignored; /**< Ignored users. */
203 char *who; /**< The person who set the topic. */
204 char *topic; /**< The topic. */
205 int id; /**< The chat ID. */
206 char *nick; /**< Your nick in this chat. */
207
208 gboolean left; /**< We left the chat and kept the window open */
209 };
210
211 /**
212 * Data for "Chat Buddies"
213 */
214 struct _GaimConvChatBuddy
215 {
216 char *name; /**< The name */
217 GaimConvChatBuddyFlags flags; /**< Flags (ops, voice etc.) */
218 };
219
220 /**
221 * A core representation of a conversation between two or more people.
222 *
223 * The conversation can be an IM or a chat.
224 */
225 struct _GaimConversation
226 {
227 GaimConversationType type; /**< The type of conversation. */
228
229 GaimAccount *account; /**< The user using this conversation. */
230
231
232 char *name; /**< The name of the conversation. */
233 char *title; /**< The window title. */
234
235 gboolean logging; /**< The status of logging. */
236
237 GList *logs; /**< This conversation's logs */
238
239 union
240 {
241 GaimConvIm *im; /**< IM-specific data. */
242 GaimConvChat *chat; /**< Chat-specific data. */
243 void *misc; /**< Misc. data. */
244
245 } u;
246
247 GaimConversationUiOps *ui_ops; /**< UI-specific operations. */
248 void *ui_data; /**< UI-specific data. */
249
250 GHashTable *data; /**< Plugin-specific data. */
251
252 GaimConnectionFlags features; /**< The supported features */
253
254 };
255
256 #ifdef __cplusplus
257 extern "C" {
258 #endif
259
260 /**************************************************************************/
261 /** @name Conversation API */
262 /**************************************************************************/
263 /*@{*/
264
265 /**
266 * Creates a new conversation of the specified type.
267 *
268 * @param type The type of conversation.
269 * @param account The account opening the conversation window on the gaim
270 * user's end.
271 * @param name The name of the conversation.
272 *
273 * @return The new conversation.
274 */
275 GaimConversation *gaim_conversation_new(GaimConversationType type,
276 GaimAccount *account,
277 const char *name);
278
279 /**
280 * Destroys the specified conversation and removes it from the parent
281 * window.
282 *
283 * If this conversation is the only one contained in the parent window,
284 * that window is also destroyed.
285 *
286 * @param conv The conversation to destroy.
287 */
288 void gaim_conversation_destroy(GaimConversation *conv);
289
290
291 /**
292 * Present a conversation to the user. This allows core code to initiate a
293 * conversation by displaying the IM dialog.
294 * @param conv The conversation to present
295 */
296 void gaim_conversation_present(GaimConversation *conv);
297
298
299 /**
300 * Returns the specified conversation's type.
301 *
302 * @param conv The conversation.
303 *
304 * @return The conversation's type.
305 */
306 GaimConversationType gaim_conversation_get_type(const GaimConversation *conv);
307
308 /**
309 * Sets the specified conversation's UI operations structure.
310 *
311 * @param conv The conversation.
312 * @param ops The UI conversation operations structure.
313 */
314 void gaim_conversation_set_ui_ops(GaimConversation *conv,
315 GaimConversationUiOps *ops);
316
317 /**
318 * Sets the default conversation UI operations structure.
319 *
320 * @param ops The UI conversation operations structure.
321 */
322 void gaim_conversations_set_ui_ops(GaimConversationUiOps *ops);
323
324 /**
325 * Returns the specified conversation's UI operations structure.
326 *
327 * @param conv The conversation.
328 *
329 * @return The operations structure.
330 */
331 GaimConversationUiOps *gaim_conversation_get_ui_ops(
332 const GaimConversation *conv);
333
334 /**
335 * Sets the specified conversation's gaim_account.
336 *
337 * This gaim_account represents the user using gaim, not the person the user
338 * is having a conversation/chat/flame with.
339 *
340 * @param conv The conversation.
341 * @param account The gaim_account.
342 */
343 void gaim_conversation_set_account(GaimConversation *conv,
344 GaimAccount *account);
345
346 /**
347 * Returns the specified conversation's gaim_account.
348 *
349 * This gaim_account represents the user using gaim, not the person the user
350 * is having a conversation/chat/flame with.
351 *
352 * @param conv The conversation.
353 *
354 * @return The conversation's gaim_account.
355 */
356 GaimAccount *gaim_conversation_get_account(const GaimConversation *conv);
357
358 /**
359 * Returns the specified conversation's gaim_connection.
360 *
361 * This is the same as gaim_conversation_get_user(conv)->gc.
362 *
363 * @param conv The conversation.
364 *
365 * @return The conversation's gaim_connection.
366 */
367 GaimConnection *gaim_conversation_get_gc(const GaimConversation *conv);
368
369 /**
370 * Sets the specified conversation's title.
371 *
372 * @param conv The conversation.
373 * @param title The title.
374 */
375 void gaim_conversation_set_title(GaimConversation *conv, const char *title);
376
377 /**
378 * Returns the specified conversation's title.
379 *
380 * @param conv The conversation.
381 *
382 * @return The title.
383 */
384 const char *gaim_conversation_get_title(const GaimConversation *conv);
385
386 /**
387 * Automatically sets the specified conversation's title.
388 *
389 * This function takes OPT_IM_ALIAS_TAB into account, as well as the
390 * user's alias.
391 *
392 * @param conv The conversation.
393 */
394 void gaim_conversation_autoset_title(GaimConversation *conv);
395
396 /**
397 * Sets the specified conversation's name.
398 *
399 * @param conv The conversation.
400 * @param name The conversation's name.
401 */
402 void gaim_conversation_set_name(GaimConversation *conv, const char *name);
403
404 /**
405 * Returns the specified conversation's name.
406 *
407 * @param conv The conversation.
408 *
409 * @return The conversation's name.
410 */
411 const char *gaim_conversation_get_name(const GaimConversation *conv);
412
413 /**
414 * Enables or disables logging for this conversation.
415 *
416 * @param conv The conversation.
417 * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
418 */
419 void gaim_conversation_set_logging(GaimConversation *conv, gboolean log);
420
421 /**
422 * Returns whether or not logging is enabled for this conversation.
423 *
424 * @param conv The conversation.
425 *
426 * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
427 */
428 gboolean gaim_conversation_is_logging(const GaimConversation *conv);
429
430 /**
431 * Closes any open logs for this conversation.
432 *
433 * Note that new logs will be opened as necessary (e.g. upon receipt of a
434 * message, if the conversation has logging enabled. To disable logging for
435 * the remainder of the conversation, use gaim_conversation_set_logging().
436 *
437 * @param conv The conversation.
438 */
439 void gaim_conversation_close_logs(GaimConversation *conv);
440
441 /**
442 * Returns the specified conversation's IM-specific data.
443 *
444 * If the conversation type is not GAIM_CONV_TYPE_IM, this will return @c NULL.
445 *
446 * @param conv The conversation.
447 *
448 * @return The IM-specific data.
449 */
450 GaimConvIm *gaim_conversation_get_im_data(const GaimConversation *conv);
451
452 #define GAIM_CONV_IM(c) (gaim_conversation_get_im_data(c))
453
454 /**
455 * Returns the specified conversation's chat-specific data.
456 *
457 * If the conversation type is not GAIM_CONV_TYPE_CHAT, this will return @c NULL.
458 *
459 * @param conv The conversation.
460 *
461 * @return The chat-specific data.
462 */
463 GaimConvChat *gaim_conversation_get_chat_data(const GaimConversation *conv);
464
465 #define GAIM_CONV_CHAT(c) (gaim_conversation_get_chat_data(c))
466
467 /**
468 * Sets extra data for a conversation.
469 *
470 * @param conv The conversation.
471 * @param key The unique key.
472 * @param data The data to assign.
473 */
474 void gaim_conversation_set_data(GaimConversation *conv, const char *key,
475 gpointer data);
476
477 /**
478 * Returns extra data in a conversation.
479 *
480 * @param conv The conversation.
481 * @param key The unqiue key.
482 *
483 * @return The data associated with the key.
484 */
485 gpointer gaim_conversation_get_data(GaimConversation *conv, const char *key);
486
487 /**
488 * Returns a list of all conversations.
489 *
490 * This list includes both IMs and chats.
491 *
492 * @return A GList of all conversations.
493 */
494 GList *gaim_get_conversations(void);
495
496 /**
497 * Returns a list of all IMs.
498 *
499 * @return A GList of all IMs.
500 */
501 GList *gaim_get_ims(void);
502
503 /**
504 * Returns a list of all chats.
505 *
506 * @return A GList of all chats.
507 */
508 GList *gaim_get_chats(void);
509
510 /**
511 * Finds a conversation with the specified type, name, and Gaim account.
512 *
513 * @param type The type of the conversation.
514 * @param name The name of the conversation.
515 * @param account The gaim_account associated with the conversation.
516 *
517 * @return The conversation if found, or @c NULL otherwise.
518 */
519 GaimConversation *gaim_find_conversation_with_account(
520 GaimConversationType type, const char *name,
521 const GaimAccount *account);
522
523 /**
524 * Writes to a conversation window.
525 *
526 * This function should not be used to write IM or chat messages. Use
527 * gaim_conv_im_write() and gaim_conv_chat_write() instead. Those functions will
528 * most likely call this anyway, but they may do their own formatting,
529 * sound playback, etc.
530 *
531 * This can be used to write generic messages, such as "so and so closed
532 * the conversation window."
533 *
534 * @param conv The conversation.
535 * @param who The user who sent the message.
536 * @param message The message.
537 * @param flags The message flags.
538 * @param mtime The time the message was sent.
539 *
540 * @see gaim_conv_im_write()
541 * @see gaim_conv_chat_write()
542 */
543 void gaim_conversation_write(GaimConversation *conv, const char *who,
544 const char *message, GaimMessageFlags flags,
545 time_t mtime);
546
547
548 /**
549 Set the features as supported for the given conversation.
550 @param conv The conversation
551 @param features Bitset defining supported features
552 */
553 void gaim_conversation_set_features(GaimConversation *conv,
554 GaimConnectionFlags features);
555
556
557 /**
558 Get the features supported by the given conversation.
559 @param conv The conversation
560 */
561 GaimConnectionFlags gaim_conversation_get_features(GaimConversation *conv);
562
563 /**
564 * Determines if a conversation has focus
565 *
566 * @param conv The conversation.
567 *
568 * @return @c TRUE if the conversation has focus, @c FALSE if
569 * it does not or the UI does not have a concept of conversation focus
570 */
571 gboolean gaim_conversation_has_focus(GaimConversation *conv);
572
573 /**
574 * Updates the visual status and UI of a conversation.
575 *
576 * @param conv The conversation.
577 * @param type The update type.
578 */
579 void gaim_conversation_update(GaimConversation *conv, GaimConvUpdateType type);
580
581 /**
582 * Calls a function on each conversation.
583 *
584 * @param func The function.
585 */
586 void gaim_conversation_foreach(void (*func)(GaimConversation *conv));
587
588 /*@}*/
589
590
591 /**************************************************************************/
592 /** @name IM Conversation API */
593 /**************************************************************************/
594 /*@{*/
595
596 /**
597 * Gets an IM's parent conversation.
598 *
599 * @param im The IM.
600 *
601 * @return The parent conversation.
602 */
603 GaimConversation *gaim_conv_im_get_conversation(const GaimConvIm *im);
604
605 /**
606 * Sets the IM's buddy icon.
607 *
608 * This should only be called from within Gaim. You probably want to
609 * call gaim_buddy_icon_set_data().
610 *
611 * @param im The IM.
612 * @param icon The buddy icon.
613 *
614 * @see gaim_buddy_icon_set_data()
615 */
616 void gaim_conv_im_set_icon(GaimConvIm *im, GaimBuddyIcon *icon);
617
618 /**
619 * Returns the IM's buddy icon.
620 *
621 * @param im The IM.
622 *
623 * @return The buddy icon.
624 */
625 GaimBuddyIcon *gaim_conv_im_get_icon(const GaimConvIm *im);
626
627 /**
628 * Sets the IM's typing state.
629 *
630 * @param im The IM.
631 * @param state The typing state.
632 */
633 void gaim_conv_im_set_typing_state(GaimConvIm *im, GaimTypingState state);
634
635 /**
636 * Returns the IM's typing state.
637 *
638 * @param im The IM.
639 *
640 * @return The IM's typing state.
641 */
642 GaimTypingState gaim_conv_im_get_typing_state(const GaimConvIm *im);
643
644 /**
645 * Starts the IM's typing timeout.
646 *
647 * @param im The IM.
648 * @param timeout The timeout.
649 */
650 void gaim_conv_im_start_typing_timeout(GaimConvIm *im, int timeout);
651
652 /**
653 * Stops the IM's typing timeout.
654 *
655 * @param im The IM.
656 */
657 void gaim_conv_im_stop_typing_timeout(GaimConvIm *im);
658
659 /**
660 * Returns the IM's typing timeout.
661 *
662 * @param im The IM.
663 *
664 * @return The timeout.
665 */
666 guint gaim_conv_im_get_typing_timeout(const GaimConvIm *im);
667
668 /**
669 * Sets the quiet-time when no GAIM_TYPING messages will be sent.
670 * Few protocols need this (maybe only MSN). If the user is still
671 * typing after this quiet-period, then another GAIM_TYPING message
672 * will be sent.
673 *
674 * @param im The IM.
675 * @param val The number of seconds to wait before allowing another
676 * GAIM_TYPING message to be sent to the user. Or 0 to
677 * not send another GAIM_TYPING message.
678 */
679 void gaim_conv_im_set_type_again(GaimConvIm *im, unsigned int val);
680
681 /**
682 * Returns the time after which another GAIM_TYPING message should be sent.
683 *
684 * @param im The IM.
685 *
686 * @return The time in seconds since the epoch. Or 0 if no additional
687 * GAIM_TYPING message should be sent.
688 */
689 time_t gaim_conv_im_get_type_again(const GaimConvIm *im);
690
691 /**
692 * Starts the IM's type again timeout.
693 *
694 * @param im The IM.
695 */
696 void gaim_conv_im_start_send_typed_timeout(GaimConvIm *im);
697
698 /**
699 * Stops the IM's type again timeout.
700 *
701 * @param im The IM.
702 */
703 void gaim_conv_im_stop_send_typed_timeout(GaimConvIm *im);
704
705 /**
706 * Returns the IM's type again timeout interval.
707 *
708 * @param im The IM.
709 *
710 * @return The type again timeout interval.
711 */
712 guint gaim_conv_im_get_send_typed_timeout(const GaimConvIm *im);
713
714 /**
715 * Updates the visual typing notification for an IM conversation.
716 *
717 * @param im The IM.
718 */
719 void gaim_conv_im_update_typing(GaimConvIm *im);
720
721 /**
722 * Writes to an IM.
723 *
724 * @param im The IM.
725 * @param who The user who sent the message.
726 * @param message The message to write.
727 * @param flags The message flags.
728 * @param mtime The time the message was sent.
729 */
730 void gaim_conv_im_write(GaimConvIm *im, const char *who,
731 const char *message, GaimMessageFlags flags,
732 time_t mtime);
733
734 /**
735 * Presents an IM-error to the user
736 *
737 * This is a helper function to find a conversation, write an error to it, and
738 * raise the window. If a conversation with this user doesn't already exist,
739 * the function will return FALSE and the calling function can attempt to present
740 * the error another way (gaim_notify_error, most likely)
741 *
742 * @param who The user this error is about
743 * @param account The account this error is on
744 * @param what The error
745 * @return TRUE if the error was presented, else FALSE
746 */
747 gboolean gaim_conv_present_error(const char *who, GaimAccount *account, const char *what);
748
749 /**
750 * Sends a message to this IM conversation.
751 *
752 * @param im The IM.
753 * @param message The message to send.
754 */
755 void gaim_conv_im_send(GaimConvIm *im, const char *message);
756
757 /**
758 * Sends a message to this IM conversation with specified flags.
759 *
760 * @param im The IM.
761 * @param message The message to send.
762 * @param flags The GaimMessageFlags flags to use in addition to GAIM_MESSAGE_SEND.
763 */
764 void gaim_conv_im_send_with_flags(GaimConvIm *im, const char *message, GaimMessageFlags flags);
765
766 /**
767 * Adds a smiley to the conversation's smiley tree. If this returns
768 * @c TRUE you should call gaim_conv_custom_smiley_write() one or more
769 * times, and then gaim_conv_custom_smiley_close(). If this returns
770 * @c FALSE, either the conv or smile were invalid, or the icon was
771 * found in the cache. In either case, calling write or close would
772 * be an error.
773 *
774 * @param conv The conversation to associate the smiley with.
775 * @param smile The text associated with the smiley
776 * @param cksum_type The type of checksum.
777 * @param chksum The checksum, as a NUL terminated base64 string.
778 * @param remote @c TRUE if the custom smiley is set by the remote user (buddy).
779 * @return @c TRUE if an icon is expected, else FALSE. Note that
780 * it is an error to never call gaim_conv_custom_smiley_close if
781 * this function returns @c TRUE, but an error to call it if
782 * @c FALSE is returned.
783 */
784
785 gboolean gaim_conv_custom_smiley_add(GaimConversation *conv, const char *smile,
786 const char *cksum_type, const char *chksum,
787 gboolean remote);
788
789
790 /**
791 * Updates the image associated with the current smiley.
792 *
793 * @param conv The conversation associated with the smiley.
794 * @param smile The text associated with the smiley.
795 * @param data The actual image data.
796 * @param size The length of the data.
797 */
798
799 void gaim_conv_custom_smiley_write(GaimConversation *conv,
800 const char *smile,
801 const guchar *data,
802 gsize size);
803
804 /**
805 * Close the custom smiley, all data has been written with
806 * gaim_conv_custom_smiley_write, and it is no longer valid
807 * to call that function on that smiley.
808 *
809 * @param conv The gaim conversation associated with the smiley.
810 * @param smile The text associated with the smiley
811 */
812
813 void gaim_conv_custom_smiley_close(GaimConversation *conv, const char *smile);
814
815 /*@}*/
816
817
818 /**************************************************************************/
819 /** @name Chat Conversation API */
820 /**************************************************************************/
821 /*@{*/
822
823 /**
824 * Gets a chat's parent conversation.
825 *
826 * @param chat The chat.
827 *
828 * @return The parent conversation.
829 */
830 GaimConversation *gaim_conv_chat_get_conversation(const GaimConvChat *chat);
831
832 /**
833 * Sets the list of users in the chat room.
834 *
835 * @note Calling this function will not update the display of the users.
836 * Please use gaim_conv_chat_add_user(), gaim_conv_chat_add_users(),
837 * gaim_conv_chat_remove_user(), and gaim_conv_chat_remove_users() instead.
838 *
839 * @param chat The chat.
840 * @param users The list of users.
841 *
842 * @return The list passed.
843 */
844 GList *gaim_conv_chat_set_users(GaimConvChat *chat, GList *users);
845
846 /**
847 * Returns a list of users in the chat room.
848 *
849 * @param chat The chat.
850 *
851 * @return The list of users.
852 */
853 GList *gaim_conv_chat_get_users(const GaimConvChat *chat);
854
855 /**
856 * Ignores a user in a chat room.
857 *
858 * @param chat The chat.
859 * @param name The name of the user.
860 */
861 void gaim_conv_chat_ignore(GaimConvChat *chat, const char *name);
862
863 /**
864 * Unignores a user in a chat room.
865 *
866 * @param chat The chat.
867 * @param name The name of the user.
868 */
869 void gaim_conv_chat_unignore(GaimConvChat *chat, const char *name);
870
871 /**
872 * Sets the list of ignored users in the chat room.
873 *
874 * @param chat The chat.
875 * @param ignored The list of ignored users.
876 *
877 * @return The list passed.
878 */
879 GList *gaim_conv_chat_set_ignored(GaimConvChat *chat, GList *ignored);
880
881 /**
882 * Returns the list of ignored users in the chat room.
883 *
884 * @param chat The chat.
885 *
886 * @return The list of ignored users.
887 */
888 GList *gaim_conv_chat_get_ignored(const GaimConvChat *chat);
889
890 /**
891 * Returns the actual name of the specified ignored user, if it exists in
892 * the ignore list.
893 *
894 * If the user found contains a prefix, such as '+' or '\@', this is also
895 * returned. The username passed to the function does not have to have this
896 * formatting.
897 *
898 * @param chat The chat.
899 * @param user The user to check in the ignore list.
900 *
901 * @return The ignored user if found, complete with prefixes, or @c NULL
902 * if not found.
903 */
904 const char *gaim_conv_chat_get_ignored_user(const GaimConvChat *chat,
905 const char *user);
906
907 /**
908 * Returns @c TRUE if the specified user is ignored.
909 *
910 * @param chat The chat.
911 * @param user The user.
912 *
913 * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise.
914 */
915 gboolean gaim_conv_chat_is_user_ignored(const GaimConvChat *chat,
916 const char *user);
917
918 /**
919 * Sets the chat room's topic.
920 *
921 * @param chat The chat.
922 * @param who The user that set the topic.
923 * @param topic The topic.
924 */
925 void gaim_conv_chat_set_topic(GaimConvChat *chat, const char *who,
926 const char *topic);
927
928 /**
929 * Returns the chat room's topic.
930 *
931 * @param chat The chat.
932 *
933 * @return The chat's topic.
934 */
935 const char *gaim_conv_chat_get_topic(const GaimConvChat *chat);
936
937 /**
938 * Sets the chat room's ID.
939 *
940 * @param chat The chat.
941 * @param id The ID.
942 */
943 void gaim_conv_chat_set_id(GaimConvChat *chat, int id);
944
945 /**
946 * Returns the chat room's ID.
947 *
948 * @param chat The chat.
949 *
950 * @return The ID.
951 */
952 int gaim_conv_chat_get_id(const GaimConvChat *chat);
953
954 /**
955 * Writes to a chat.
956 *
957 * @param chat The chat.
958 * @param who The user who sent the message.
959 * @param message The message to write.
960 * @param flags The flags.
961 * @param mtime The time the message was sent.
962 */
963 void gaim_conv_chat_write(GaimConvChat *chat, const char *who,
964 const char *message, GaimMessageFlags flags,
965 time_t mtime);
966
967 /**
968 * Sends a message to this chat conversation.
969 *
970 * @param chat The chat.
971 * @param message The message to send.
972 */
973 void gaim_conv_chat_send(GaimConvChat *chat, const char *message);
974
975 /**
976 * Sends a message to this chat conversation with specified flags.
977 *
978 * @param chat The chat.
979 * @param message The message to send.
980 * @param flags The GaimMessageFlags flags to use.
981 */
982 void gaim_conv_chat_send_with_flags(GaimConvChat *chat, const char *message, GaimMessageFlags flags);
983
984 /**
985 * Adds a user to a chat.
986 *
987 * @param chat The chat.
988 * @param user The user to add.
989 * @param extra_msg An extra message to display with the join message.
990 * @param flags The users flags
991 * @param new_arrival Decides whether or not to show a join notice.
992 */
993 void gaim_conv_chat_add_user(GaimConvChat *chat, const char *user,
994 const char *extra_msg, GaimConvChatBuddyFlags flags,
995 gboolean new_arrival);
996
997 /**
998 * Adds a list of users to a chat.
999 *
1000 * The data is copied from @a users, @a extra_msgs, and @a flags, so it is up to
1001 * the caller to free this list after calling this function.
1002 *
1003 * @param chat The chat.
1004 * @param users The list of users to add.
1005 * @param extra_msgs An extra message to display with the join message for each
1006 * user. This list may be shorter than @a users, in which
1007 * case, the users after the end of extra_msgs will not have
1008 * an extra message. By extension, this means that extra_msgs
1009 * can simply be @c NULL and none of the users will have an
1010 * extra message.
1011 * @param flags The list of flags for each user.
1012 * @param new_arrivals Decides whether or not to show join notices.
1013 */
1014 void gaim_conv_chat_add_users(GaimConvChat *chat, GList *users, GList *extra_msgs,
1015 GList *flags, gboolean new_arrivals);
1016
1017 /**
1018 * Renames a user in a chat.
1019 *
1020 * @param chat The chat.
1021 * @param old_user The old username.
1022 * @param new_user The new username.
1023 */
1024 void gaim_conv_chat_rename_user(GaimConvChat *chat, const char *old_user,
1025 const char *new_user);
1026
1027 /**
1028 * Removes a user from a chat, optionally with a reason.
1029 *
1030 * It is up to the developer to free this list after calling this function.
1031 *
1032 * @param chat The chat.
1033 * @param user The user that is being removed.
1034 * @param reason The optional reason given for the removal. Can be @c NULL.
1035 */
1036 void gaim_conv_chat_remove_user(GaimConvChat *chat, const char *user,
1037 const char *reason);
1038
1039 /**
1040 * Removes a list of users from a chat, optionally with a single reason.
1041 *
1042 * @param chat The chat.
1043 * @param users The users that are being removed.
1044 * @param reason The optional reason given for the removal. Can be @c NULL.
1045 */
1046 void gaim_conv_chat_remove_users(GaimConvChat *chat, GList *users,
1047 const char *reason);
1048
1049 /**
1050 * Finds a user in a chat
1051 *
1052 * @param chat The chat.
1053 * @param user The user to look for.
1054 *
1055 * @return TRUE if the user is in the chat, FALSE if not
1056 */
1057 gboolean gaim_conv_chat_find_user(GaimConvChat *chat, const char *user);
1058
1059 /**
1060 * Set a users flags in a chat
1061 *
1062 * @param chat The chat.
1063 * @param user The user to update.
1064 * @param flags The new flags.
1065 */
1066 void gaim_conv_chat_user_set_flags(GaimConvChat *chat, const char *user,
1067 GaimConvChatBuddyFlags flags);
1068
1069 /**
1070 * Get the flags for a user in a chat
1071 *
1072 * @param chat The chat.
1073 * @param user The user to find the flags for
1074 *
1075 * @return The flags for the user
1076 */
1077 GaimConvChatBuddyFlags gaim_conv_chat_user_get_flags(GaimConvChat *chat,
1078 const char *user);
1079
1080 /**
1081 * Clears all users from a chat.
1082 *
1083 * @param chat The chat.
1084 */
1085 void gaim_conv_chat_clear_users(GaimConvChat *chat);
1086
1087 /**
1088 * Sets your nickname (used for hilighting) for a chat.
1089 *
1090 * @param chat The chat.
1091 * @param nick The nick.
1092 */
1093 void gaim_conv_chat_set_nick(GaimConvChat *chat, const char *nick);
1094
1095 /**
1096 * Gets your nickname (used for hilighting) for a chat.
1097 *
1098 * @param chat The chat.
1099 * @return The nick.
1100 */
1101 const char *gaim_conv_chat_get_nick(GaimConvChat *chat);
1102
1103 /**
1104 * Finds a chat with the specified chat ID.
1105 *
1106 * @param gc The gaim_connection.
1107 * @param id The chat ID.
1108 *
1109 * @return The chat conversation.
1110 */
1111 GaimConversation *gaim_find_chat(const GaimConnection *gc, int id);
1112
1113 /**
1114 * Lets the core know we left a chat, without destroying it.
1115 * Called from serv_got_chat_left().
1116 *
1117 * @param chat The chat.
1118 */
1119 void gaim_conv_chat_left(GaimConvChat *chat);
1120
1121 /**
1122 * Returns true if we're no longer in this chat,
1123 * and just left the window open.
1124 *
1125 * @param chat The chat.
1126 *
1127 * @return @c TRUE if we left the chat already, @c FALSE if
1128 * we're still there.
1129 */
1130 gboolean gaim_conv_chat_has_left(GaimConvChat *chat);
1131
1132 /**
1133 * Creates a new chat buddy
1134 *
1135 * @param name The name.
1136 * @param flags The flags.
1137 *
1138 * @return The new chat buddy
1139 */
1140 GaimConvChatBuddy *gaim_conv_chat_cb_new(const char *name,
1141 GaimConvChatBuddyFlags flags);
1142
1143 /**
1144 * Find a chat buddy in a chat
1145 *
1146 * @param chat The chat.
1147 * @param name The name of the chat buddy to find.
1148 */
1149 GaimConvChatBuddy *gaim_conv_chat_cb_find(GaimConvChat *chat, const char *name);
1150
1151 /**
1152 * Get the name of a chat buddy
1153 *
1154 * @param cb The chat buddy.
1155 *
1156 * @return The name of the chat buddy.
1157 */
1158 const char *gaim_conv_chat_cb_get_name(GaimConvChatBuddy *cb);
1159
1160 /**
1161 * Destroys a chat buddy
1162 *
1163 * @param cb The chat buddy to destroy
1164 */
1165 void gaim_conv_chat_cb_destroy(GaimConvChatBuddy *cb);
1166
1167 /*@}*/
1168
1169 /**************************************************************************/
1170 /** @name Conversations Subsystem */
1171 /**************************************************************************/
1172 /*@{*/
1173
1174 /**
1175 * Returns the conversation subsystem handle.
1176 *
1177 * @return The conversation subsystem handle.
1178 */
1179 void *gaim_conversations_get_handle(void);
1180
1181 /**
1182 * Initializes the conversation subsystem.
1183 */
1184 void gaim_conversations_init(void);
1185
1186 /**
1187 * Uninitializes the conversation subsystem.
1188 */
1189 void gaim_conversations_uninit(void);
1190
1191 /*@}*/
1192
1193 #ifdef __cplusplus
1194 }
1195 #endif
1196
1197 #endif /* _GAIM_CONVERSATION_H_ */

Mercurial Repository: pidgin3

mercurial