Mercurial > pidgin.yaz
annotate src/conversation.h @ 4438:2054d8429925
[gaim-migrate @ 4713]
Setting the font face in preferences works again. Thanks CmdrChalupa.
committer: Tailor Script <tailor@pidgin.im>
author | Christian Hammond <chipx86@chipx86.com> |
---|---|
date | Tue, 28 Jan 2003 02:45:34 +0000 |
parents | 194507c83612 |
children | 6e37eb000b7a |
rev | line source |
---|---|
4359 | 1 /** |
2 * @file conversation.h Conversation API | |
3 * | |
4 * gaim | |
5 * | |
6 * Copyright (C) 2002-2003, Christian Hammond <chipx86@gnupdate.org> | |
7 * | |
8 * This program is free software; you can redistribute it and/or modify | |
9 * it under the terms of the GNU General Public License as published by | |
10 * the Free Software Foundation; either version 2 of the License, or | |
11 * (at your option) any later version. | |
12 * | |
13 * This program is distributed in the hope that it will be useful, | |
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 * GNU General Public License for more details. | |
17 * | |
18 * You should have received a copy of the GNU General Public License | |
19 * along with this program; if not, write to the Free Software | |
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
21 * | |
22 */ | |
23 | |
24 #ifndef _CONVERSATION_H_ | |
25 #define _CONVERSATION_H_ | |
26 | |
27 /**************************************************************************/ | |
28 /** Data Structures */ | |
29 /**************************************************************************/ | |
30 | |
31 typedef enum _GaimConversationType GaimConversationType; | |
32 typedef enum _GaimUnseenState GaimUnseenState; | |
33 typedef enum _GaimConvUpdateType GaimConvUpdateType; | |
34 struct gaim_window_ops; | |
35 struct gaim_window; | |
36 struct gaim_conversation; | |
37 struct gaim_im; | |
38 struct gaim_chat; | |
39 | |
40 /** | |
41 * A type of conversation. | |
42 */ | |
43 enum _GaimConversationType | |
44 { | |
45 GAIM_CONV_UNKNOWN = 0, /**< Unknown conversation type. */ | |
46 GAIM_CONV_IM, /**< Instant Message. */ | |
4378
194507c83612
[gaim-migrate @ 4644]
Christian Hammond <chipx86@chipx86.com>
parents:
4359
diff
changeset
|
47 GAIM_CONV_CHAT, /**< Chat room. */ |
194507c83612
[gaim-migrate @ 4644]
Christian Hammond <chipx86@chipx86.com>
parents:
4359
diff
changeset
|
48 GAIM_CONV_MISC /**< A misc. conversation. */ |
4359 | 49 }; |
50 | |
51 /** | |
52 * Unseen text states. | |
53 */ | |
54 enum _GaimUnseenState | |
55 { | |
56 GAIM_UNSEEN_NONE = 0, /**< No unseen text in the conversation. */ | |
57 GAIM_UNSEEN_TEXT, /**< Unseen text in the conversation. */ | |
58 GAIM_UNSEEN_NICK, /**< Unseen text and the nick was said. */ | |
59 }; | |
60 | |
61 /** | |
62 * Conversation update type. | |
63 */ | |
64 enum _GaimConvUpdateType | |
65 { | |
66 GAIM_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation | |
67 was added. */ | |
68 GAIM_CONV_UPDATE_REMOVE, /**< The buddy associated with the conversation | |
69 was removed. */ | |
70 GAIM_CONV_UPDATE_USER, /**< The aim_user was changed. */ | |
71 GAIM_CONV_UPDATE_TYPING, /**< The typing state was updated. */ | |
72 GAIM_CONV_UPDATE_UNSEEN, /**< The unseen state was updated. */ | |
73 GAIM_CONV_UPDATE_LOGGING, /**< Logging for this conversation was | |
74 enabled or disabled. */ | |
75 GAIM_CONV_UPDATE_TOPIC, /**< The topic for a chat was updated. */ | |
76 | |
77 /* | |
78 * XXX These need to go when we implement a more generic core/UI event | |
79 * system. | |
80 */ | |
4378
194507c83612
[gaim-migrate @ 4644]
Christian Hammond <chipx86@chipx86.com>
parents:
4359
diff
changeset
|
81 GAIM_CONV_ACCOUNT_ONLINE, /**< One of the user's accounts went online. */ |
194507c83612
[gaim-migrate @ 4644]
Christian Hammond <chipx86@chipx86.com>
parents:
4359
diff
changeset
|
82 GAIM_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */ |
194507c83612
[gaim-migrate @ 4644]
Christian Hammond <chipx86@chipx86.com>
parents:
4359
diff
changeset
|
83 GAIM_CONV_UPDATE_AWAY /**< The other user went away. */ |
4359 | 84 }; |
85 | |
86 /* Yeah, this has to be included here. Ugh. */ | |
87 #include "gaim.h" | |
88 | |
89 /** | |
90 * Conversation window operations. | |
91 * | |
92 * Any UI representing a window must assign a filled-out gaim_window_ops | |
93 * structure to the gaim_window. | |
94 */ | |
95 struct gaim_window_ops | |
96 { | |
97 struct gaim_conversation_ops *(*get_conversation_ops)(void); | |
98 | |
99 void (*new_window)(struct gaim_window *win); | |
100 void (*destroy_window)(struct gaim_window *win); | |
101 | |
102 void (*show)(struct gaim_window *win); | |
103 void (*hide)(struct gaim_window *win); | |
104 void (*raise)(struct gaim_window *win); | |
105 void (*flash)(struct gaim_window *win); | |
106 | |
107 void (*switch_conversation)(struct gaim_window *win, unsigned int index); | |
108 void (*add_conversation)(struct gaim_window *win, | |
109 struct gaim_conversation *conv); | |
110 void (*remove_conversation)(struct gaim_window *win, | |
111 struct gaim_conversation *conv); | |
112 void (*move_conversation)(struct gaim_window *win, | |
113 struct gaim_conversation *conv, | |
114 unsigned int newIndex); | |
115 int (*get_active_index)(const struct gaim_window *win); | |
116 }; | |
117 | |
118 /** | |
119 * Conversation operations and events. | |
120 * | |
121 * Any UI representing a conversation must assign a filled-out | |
122 * gaim_conversation_ops structure to the gaim_conversation. | |
123 */ | |
124 struct gaim_conversation_ops | |
125 { | |
126 void (*destroy_conversation)(struct gaim_conversation *conv); | |
127 void (*write_chat)(struct gaim_conversation *conv, const char *who, | |
128 const char *message, int flags, time_t mtime); | |
129 void (*write_im)(struct gaim_conversation *conv, const char *who, | |
130 const char *message, size_t len, int flags, time_t mtime); | |
131 void (*write_conv)(struct gaim_conversation *conv, const char *who, | |
132 const char *message, size_t length, int flags, | |
133 time_t mtime); | |
134 | |
135 void (*chat_add_user)(struct gaim_conversation *conv, const char *user); | |
136 void (*chat_rename_user)(struct gaim_conversation *conv, | |
137 const char *old_name, const char *new_name); | |
138 void (*chat_remove_user)(struct gaim_conversation *conv, const char *user); | |
139 | |
140 void (*set_title)(struct gaim_conversation *conv, | |
141 const char *title); | |
142 void (*update_progress)(struct gaim_conversation *conv, float percent); | |
143 | |
144 /* Events */ | |
145 void (*updated)(struct gaim_conversation *conv, GaimConvUpdateType type); | |
146 }; | |
147 | |
148 /** | |
149 * A core representation of a graphical window containing one or more | |
150 * conversations. | |
151 */ | |
152 struct gaim_window | |
153 { | |
154 GList *conversations; /**< The conversations in the window. */ | |
155 size_t conversation_count; /**< The number of conversations. */ | |
156 | |
157 struct gaim_window_ops *ops; /**< UI-specific window operations. */ | |
158 | |
159 void *ui_data; /**< UI-specific data. */ | |
160 }; | |
161 | |
162 /** | |
163 * Data specific to Instant Messages. | |
164 */ | |
165 struct gaim_im | |
166 { | |
167 struct gaim_conversation *conv; | |
168 | |
169 int typing_state; | |
170 guint typing_timeout; | |
171 time_t type_again; | |
172 guint type_again_timeout; | |
173 | |
174 GSList *images; | |
175 }; | |
176 | |
177 /** | |
178 * Data specific to Chats. | |
179 */ | |
180 struct gaim_chat | |
181 { | |
182 struct gaim_conversation *conv; | |
183 | |
184 GList *in_room; | |
185 GList *ignored; | |
186 char *who; | |
187 char *topic; | |
188 int id; | |
189 }; | |
190 | |
191 /** | |
192 * A core representation of a conversation between two or more people. | |
193 * | |
194 * The conversation can be an IM or a chat. Each conversation is kept | |
195 * in a gaim_window and has a UI representation. | |
196 */ | |
197 struct gaim_conversation | |
198 { | |
199 GaimConversationType type; /**< The type of conversation. */ | |
200 | |
201 struct aim_user *user; /**< The user using this conversation. */ | |
202 struct gaim_window *window; /**< The parent window. */ | |
203 | |
204 /** UI-specific conversation operations.*/ | |
205 struct gaim_conversation_ops *ops; | |
206 | |
207 int conversation_pos; /**< The position in the window's list. */ | |
208 | |
209 char *name; /**< The name of the conversation. */ | |
210 char *title; /**< The window title. */ | |
211 | |
212 gboolean logging; /**< The status of logging. */ | |
213 | |
214 GList *send_history; /**< The send history. */ | |
215 GString *history; /**< The conversation history. */ | |
216 | |
217 GaimUnseenState unseen; /**< The unseen tab state. */ | |
218 | |
219 void *ui_data; /**< UI-specific data. */ | |
220 | |
221 union | |
222 { | |
223 struct gaim_im *im; /**< IM-specific data. */ | |
224 struct gaim_chat *chat; /**< Chat-specific data. */ | |
4378
194507c83612
[gaim-migrate @ 4644]
Christian Hammond <chipx86@chipx86.com>
parents:
4359
diff
changeset
|
225 void *misc; /**< Misc. data. */ |
4359 | 226 |
227 } u; | |
228 }; | |
229 | |
230 | |
231 /**************************************************************************/ | |
232 /** @name Conversation Window API */ | |
233 /**************************************************************************/ | |
234 /*@{*/ | |
235 | |
236 /** | |
237 * Creates a new conversation window. | |
238 * | |
239 * This window is added to the list of windows, but is not shown until | |
240 * gaim_window_show() is called. | |
241 * | |
242 * @return The new conversation window. | |
243 */ | |
244 struct gaim_window *gaim_window_new(void); | |
245 | |
246 /** | |
247 * Destroys the specified conversation window and all conversations in it. | |
248 * | |
249 * @param win The window to destroy. | |
250 */ | |
251 void gaim_window_destroy(struct gaim_window *win); | |
252 | |
253 /** | |
254 * Shows the specified conversation window. | |
255 * | |
256 * @param win The window. | |
257 */ | |
258 void gaim_window_show(struct gaim_window *win); | |
259 | |
260 /** | |
261 * Hides the specified conversation window. | |
262 * | |
263 * @param win The window. | |
264 */ | |
265 void gaim_window_hide(struct gaim_window *win); | |
266 | |
267 /** | |
268 * Raises the specified conversation window. | |
269 * | |
270 * @param win The window. | |
271 */ | |
272 void gaim_window_raise(struct gaim_window *win); | |
273 | |
274 /** | |
275 * Causes the window to flash for IM notification, if the UI supports this. | |
276 * | |
277 * @param win The window. | |
278 */ | |
279 void gaim_window_flash(struct gaim_window *win); | |
280 | |
281 /** | |
282 * Sets the specified window's UI window operations structure. | |
283 * | |
284 * @param win The window. | |
285 * @param ops The UI window operations structure. | |
286 */ | |
287 void gaim_window_set_ops(struct gaim_window *win, | |
288 struct gaim_window_ops *ops); | |
289 | |
290 /** | |
291 * Returns the specified window's UI window operations structure. | |
292 * | |
293 * @param win The window. | |
294 * | |
295 * @return The UI window operations structure. | |
296 */ | |
297 struct gaim_window_ops *gaim_window_get_ops(const struct gaim_window *win); | |
298 | |
299 /** | |
300 * Adds a conversation to this window. | |
301 * | |
302 * If the conversation already has a parent window, this will do nothing. | |
303 * | |
304 * @param win The window. | |
305 * @param conv The conversation. | |
306 * | |
307 * @return The new index of the conversation in the window. | |
308 */ | |
309 int gaim_window_add_conversation(struct gaim_window *win, | |
310 struct gaim_conversation *conv); | |
311 | |
312 /** | |
313 * Removes the conversation at the specified index from the window. | |
314 * | |
315 * If there is no conversation at this index, this will do nothing. | |
316 * | |
317 * @param win The window. | |
318 * @param index The index of the conversation. | |
319 * | |
320 * @return The conversation removed. | |
321 */ | |
322 struct gaim_conversation *gaim_window_remove_conversation( | |
323 struct gaim_window *win, unsigned int index); | |
324 | |
325 /** | |
326 * Moves the conversation at the specified index in a window to a new index. | |
327 * | |
328 * @param win The window. | |
329 * @param index The index of the conversation to move. | |
330 * @param new_index The new index. | |
331 */ | |
332 void gaim_window_move_conversation(struct gaim_window *win, | |
333 unsigned int index, unsigned int new_index); | |
334 | |
335 /** | |
336 * Returns the conversation in the window at the specified index. | |
337 * | |
338 * If the index is out of range, this returns @c NULL. | |
339 * | |
340 * @param win The window. | |
341 * @param index The index containing a conversation. | |
342 * | |
343 * @return The conversation at the specified index. | |
344 */ | |
345 struct gaim_conversation *gaim_window_get_conversation_at( | |
346 const struct gaim_window *win, unsigned int index); | |
347 | |
348 /** | |
349 * Returns the number of conversations in the window. | |
350 * | |
351 * @param win The window. | |
352 * | |
353 * @return The number of conversations. | |
354 */ | |
355 size_t gaim_window_get_conversation_count(const struct gaim_window *win); | |
356 | |
357 /** | |
358 * Switches the active conversation to the one at the specified index. | |
359 * | |
360 * If @a index is out of range, this does nothing. | |
361 * | |
362 * @param win The window. | |
363 * @param index The new index. | |
364 */ | |
365 void gaim_window_switch_conversation(struct gaim_window *win, | |
366 unsigned int index); | |
367 | |
368 /** | |
369 * Returns the active conversation in the window. | |
370 * | |
371 * @param win The window. | |
372 * | |
373 * @return The active conversation. | |
374 */ | |
375 struct gaim_conversation *gaim_window_get_active_conversation( | |
376 const struct gaim_window *win); | |
377 | |
378 /** | |
379 * Returns the list of conversations in the specified window. | |
380 * | |
381 * @param win The window. | |
382 * | |
383 * @return The list of conversations. | |
384 */ | |
385 GList *gaim_window_get_conversations(const struct gaim_window *win); | |
386 | |
387 /** | |
388 * Returns a list of all windows. | |
389 * | |
390 * @return A list of windows. | |
391 */ | |
392 GList *gaim_get_windows(void); | |
393 | |
394 /*@}*/ | |
395 | |
396 /**************************************************************************/ | |
397 /** @name Conversation API */ | |
398 /**************************************************************************/ | |
399 /*@{*/ | |
400 | |
401 /** | |
402 * Creates a new conversation of the specified type. | |
403 * | |
404 * @param type The type of conversation. | |
405 * @param name The name of the conversation. | |
406 * | |
407 * @return The new conversation. | |
408 */ | |
409 struct gaim_conversation *gaim_conversation_new(GaimConversationType type, | |
410 const char *name); | |
411 | |
412 /** | |
413 * Destroys the specified conversation and removes it from the parent | |
414 * window. | |
415 * | |
416 * If this conversation is the only one contained in the parent window, | |
417 * that window is also destroyed. | |
418 * | |
419 * @param conv The conversation to destroy. | |
420 */ | |
421 void gaim_conversation_destroy(struct gaim_conversation *conv); | |
422 | |
423 /** | |
424 * Returns the specified conversation's type. | |
425 * | |
426 * @param conv The conversation. | |
427 * | |
428 * @return The conversation's type. | |
429 */ | |
430 GaimConversationType gaim_conversation_get_type( | |
431 const struct gaim_conversation *conv); | |
432 | |
433 /** | |
434 * Sets the specified conversation's UI operations structure. | |
435 * | |
436 * @param conv The conversation. | |
437 * @param ops The UI conversation operations structure. | |
438 */ | |
439 void gaim_conversation_set_ops(struct gaim_conversation *conv, | |
440 struct gaim_conversation_ops *ops); | |
441 | |
442 /** | |
443 * Returns the specified conversation's UI operations structure. | |
444 * | |
445 * @param conv The conversation. | |
446 * | |
447 * @return The operations structure. | |
448 */ | |
449 struct gaim_conversation_ops *gaim_conversation_get_ops( | |
450 struct gaim_conversation *conv); | |
451 | |
452 /** | |
453 * Sets the specified conversation's aim_user. | |
454 * | |
455 * This aim_user represents the user using gaim, not the person the user | |
456 * is having a conversation/chat/flame with. | |
457 * | |
458 * @param conv The conversation. | |
459 * @param user The aim_user. | |
460 */ | |
461 void gaim_conversation_set_user(struct gaim_conversation *conv, | |
462 struct aim_user *user); | |
463 | |
464 /** | |
465 * Returns the specified conversation's aim_user. | |
466 * | |
467 * This aim_user represents the user using gaim, not the person the user | |
468 * is having a conversation/chat/flame with. | |
469 * | |
470 * @param conv The conversation. | |
471 * | |
472 * @return The conversation's aim_user. | |
473 */ | |
474 struct aim_user *gaim_conversation_get_user( | |
475 const struct gaim_conversation *conv); | |
476 | |
477 #if 0 | |
478 /** | |
479 * Sets the specified conversation's gaim_connection. | |
480 * | |
481 * @param conv The conversation. | |
482 * @param gc The gaim_connection. | |
483 */ | |
484 void gaim_conversation_set_gc(struct gaim_conversation *conv, | |
485 struct gaim_connection *gc); | |
486 #endif | |
487 | |
488 /** | |
489 * Returns the specified conversation's gaim_connection. | |
490 * | |
491 * This is the same as gaim_conversation_get_user(conv)->gc. | |
492 * | |
493 * @param conv The conversation. | |
494 * | |
495 * @return The conversation's gaim_connection. | |
496 */ | |
497 struct gaim_connection *gaim_conversation_get_gc( | |
498 const struct gaim_conversation *conv); | |
499 | |
500 /** | |
501 * Sets the specified conversation's title. | |
502 * | |
503 * @param conv The conversation. | |
504 * @param title The title. | |
505 */ | |
506 void gaim_conversation_set_title(struct gaim_conversation *conv, | |
507 const char *title); | |
508 | |
509 /** | |
510 * Returns the specified conversation's title. | |
511 * | |
512 * @param win The conversation. | |
513 * | |
514 * @return The title. | |
515 */ | |
516 const char *gaim_conversation_get_title(const struct gaim_conversation *conv); | |
517 | |
518 /** | |
519 * Automatically sets the specified conversation's title. | |
520 * | |
521 * This function takes OPT_IM_ALIAS_TAB into account, as well as the | |
522 * user's alias. | |
523 * | |
524 * @param conv The conversation. | |
525 */ | |
526 void gaim_conversation_autoset_title(struct gaim_conversation *conv); | |
527 | |
528 /** | |
529 * Returns the specified conversation's index in the parent window. | |
530 * | |
531 * @param conv The conversation. | |
532 * | |
533 * @return The current index in the parent window. | |
534 */ | |
535 int gaim_conversation_get_index(const struct gaim_conversation *conv); | |
536 | |
537 /** | |
538 * Sets the conversation's unseen state. | |
539 * | |
540 * @param conv The conversation. | |
541 * @param state The new unseen state. | |
542 */ | |
543 void gaim_conversation_set_unseen(struct gaim_conversation *conv, | |
544 GaimUnseenState state); | |
545 | |
546 /** | |
547 * Returns the conversation's unseen state. | |
548 * | |
549 * @param conv The conversation. | |
550 * | |
551 * @param The conversation's unseen state. | |
552 */ | |
553 GaimUnseenState gaim_conversation_get_unseen( | |
554 const struct gaim_conversation *conv); | |
555 | |
556 /** | |
557 * Returns the specified conversation's name. | |
558 * | |
559 * @param conv The conversation. | |
560 * | |
561 * @return The conversation's name. | |
562 */ | |
563 const char *gaim_conversation_get_name(const struct gaim_conversation *conv); | |
564 | |
565 /** | |
566 * Enables or disables logging for this conversation. | |
567 * | |
568 * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise. | |
569 */ | |
570 void gaim_conversation_set_logging(struct gaim_conversation *conv, | |
571 gboolean log); | |
572 | |
573 /** | |
574 * Returns whether or not logging is enabled for this conversation. | |
575 * | |
576 * @return @c TRUE if logging is enabled, or @c FALSE otherwise. | |
577 */ | |
578 gboolean gaim_conversation_is_logging(const struct gaim_conversation *conv); | |
579 | |
580 /** | |
581 * Returns the specified conversation's send history. | |
582 * | |
583 * @param conv The conversation. | |
584 * | |
585 * @return The conversation's send history. | |
586 */ | |
587 GList *gaim_conversation_get_send_history( | |
588 const struct gaim_conversation *conv); | |
589 | |
590 /** | |
591 * Sets the specified conversation's history. | |
592 * | |
593 * @param conv The conversation. | |
594 * @param history The history. | |
595 */ | |
596 void gaim_conversation_set_history(struct gaim_conversation *conv, | |
597 GString *history); | |
598 | |
599 /** | |
600 * Returns the specified conversation's history. | |
601 * | |
602 * @param conv The conversation. | |
603 * | |
604 * @return The conversation's history. | |
605 */ | |
606 GString *gaim_conversation_get_history(const struct gaim_conversation *conv); | |
607 | |
608 /** | |
609 * Returns the specified conversation's parent window. | |
610 * | |
611 * @param conv The conversation. | |
612 * | |
613 * @return The conversation's parent window. | |
614 */ | |
615 struct gaim_window *gaim_conversation_get_window( | |
616 const struct gaim_conversation *conv); | |
617 | |
618 /** | |
619 * Returns the specified conversation's IM-specific data. | |
620 * | |
621 * If the conversation type is not GAIM_CONV_IM, this will return @c NULL. | |
622 * | |
623 * @param conv The conversation. | |
624 * | |
625 * @return The IM-specific data. | |
626 */ | |
627 struct gaim_im *gaim_conversation_get_im_data( | |
628 const struct gaim_conversation *conv); | |
629 | |
630 #define GAIM_IM(c) (gaim_conversation_get_im_data(c)) | |
631 | |
632 /** | |
633 * Returns the specified conversation's chat-specific data. | |
634 * | |
635 * If the conversation type is not GAIM_CONV_CHAT, this will return @c NULL. | |
636 * | |
637 * @param conv The conversation. | |
638 * | |
639 * @return The chat-specific data. | |
640 */ | |
641 struct gaim_chat *gaim_conversation_get_chat_data( | |
642 const struct gaim_conversation *conv); | |
643 | |
644 #define GAIM_CHAT(c) (gaim_conversation_get_chat_data(c)) | |
645 | |
646 /** | |
647 * Returns a list of all conversations. | |
648 * | |
649 * This list includes both IMs and chats. | |
650 * | |
651 * @return A GList of all conversations. | |
652 */ | |
653 GList *gaim_get_conversations(void); | |
654 | |
655 /** | |
656 * Returns a list of all IMs. | |
657 * | |
658 * @return A GList of all IMs. | |
659 */ | |
660 GList *gaim_get_ims(void); | |
661 | |
662 /** | |
663 * Returns a list of all chats. | |
664 * | |
665 * @return A GList of all chats. | |
666 */ | |
667 GList *gaim_get_chats(void); | |
668 | |
669 /** | |
670 * Finds the conversation with the specified name. | |
671 * | |
672 * @param name The name of the conversation. | |
673 * | |
674 * @return The conversation if found, or @c NULL otherwise. | |
675 */ | |
676 struct gaim_conversation *gaim_find_conversation(const char *name); | |
677 | |
678 /** | |
679 * Finds a conversation with the specified name and user. | |
680 * | |
681 * @param name The name of the conversation. | |
682 * @param user The aim_user associated with the conversation. | |
683 * | |
684 * @return The conversation if found, or @c NULL otherwise. | |
685 */ | |
686 struct gaim_conversation *gaim_find_conversation_with_user( | |
687 const char *name, const struct aim_user *user); | |
688 | |
689 /** | |
690 * Writes to a conversation window. | |
691 * | |
692 * This function should not be used to write IM or chat messages. Use | |
693 * gaim_im_write() and gaim_chat_write() instead. Those functions will | |
694 * most likely call this anyway, but they may do their own formatting, | |
695 * sound playback, etc. | |
696 * | |
697 * This can be used to write generic messages, such as "so and so closed | |
698 * the conversation window." | |
699 * | |
700 * @param conv The conversation. | |
701 * @param who The user who sent the message. | |
702 * @param message The message. | |
703 * @param length The length of the message. | |
704 * @param flags The flags. | |
705 * @param mtime The time the message was sent. | |
706 * | |
707 * @see gaim_im_write() | |
708 * @see gaim_chat_write() | |
709 */ | |
710 void gaim_conversation_write(struct gaim_conversation *conv, const char *who, | |
711 const char *message, size_t length, int flags, | |
712 time_t mtime); | |
713 | |
714 /** | |
715 * Updates the progress bar on a conversation window | |
716 * (if one exists in the UI). | |
717 * | |
718 * This is used for loading images typically. | |
719 * | |
720 * @param conv The conversation. | |
721 * @param percent The percentage. | |
722 */ | |
723 void gaim_conversation_update_progress(struct gaim_conversation *conv, | |
724 float percent); | |
725 | |
726 /** | |
727 * Updates the visual status and UI of a conversation. | |
728 * | |
729 * @param conv The conversation. | |
730 * @param type The update type. | |
731 */ | |
732 void gaim_conversation_update(struct gaim_conversation *conv, | |
733 GaimConvUpdateType type); | |
734 | |
735 /** | |
736 * Calls a function on each conversation. | |
737 * | |
738 * @param func The function. | |
739 */ | |
740 void gaim_conversation_foreach(void (*func)(struct gaim_conversation *conv)); | |
741 | |
742 /*@}*/ | |
743 | |
744 | |
745 /**************************************************************************/ | |
746 /** @name IM Conversation API */ | |
747 /**************************************************************************/ | |
748 /*@{*/ | |
749 | |
750 /** | |
751 * Gets an IM's parent conversation. | |
752 * | |
753 * @param im The IM. | |
754 * | |
755 * @return The parent conversation. | |
756 */ | |
757 struct gaim_conversation *gaim_im_get_conversation(struct gaim_im *im); | |
758 | |
759 /** | |
760 * Sets the IM's typing state. | |
761 * | |
762 * @param im The IM. | |
763 * @param state The typing state. | |
764 */ | |
765 void gaim_im_set_typing_state(struct gaim_im *im, int state); | |
766 | |
767 /** | |
768 * Returns the IM's typing state. | |
769 * | |
770 * @param im The IM. | |
771 * | |
772 * @return The IM's typing state. | |
773 */ | |
774 int gaim_im_get_typing_state(const struct gaim_im *im); | |
775 | |
776 /** | |
777 * Starts the IM's typing timeout. | |
778 * | |
779 * @param im The IM. | |
780 * @param timeout The timeout. | |
781 */ | |
782 void gaim_im_start_typing_timeout(struct gaim_im *im, int timeout); | |
783 | |
784 /** | |
785 * Stops the IM's typing timeout. | |
786 * | |
787 * @param im The IM. | |
788 */ | |
789 void gaim_im_stop_typing_timeout(struct gaim_im *im); | |
790 | |
791 /** | |
792 * Returns the IM's typing timeout. | |
793 * | |
794 * @param im The IM. | |
795 * | |
796 * @return The timeout. | |
797 */ | |
798 guint gaim_im_get_typing_timeout(const struct gaim_im *im); | |
799 | |
800 /** | |
801 * Sets the IM's time until it should send another typing notification. | |
802 * | |
803 * @param im The IM. | |
804 * @param val The time. | |
805 */ | |
806 void gaim_im_set_type_again(struct gaim_im *im, time_t val); | |
807 | |
808 /** | |
809 * Returns the IM's time until it should send another typing notification. | |
810 * | |
811 * @param im The IM. | |
812 * | |
813 * @return The time. | |
814 */ | |
815 time_t gaim_im_get_type_again(const struct gaim_im *im); | |
816 | |
817 /** | |
818 * Starts the IM's type again timeout. | |
819 * | |
820 * @param im The IM. | |
821 */ | |
822 void gaim_im_start_type_again_timeout(struct gaim_im *im); | |
823 | |
824 /** | |
825 * Stops the IM's type again timeout. | |
826 * | |
827 * @param im The IM. | |
828 */ | |
829 void gaim_im_stop_type_again_timeout(struct gaim_im *im); | |
830 | |
831 /** | |
832 * Returns the IM's type again timeout interval. | |
833 * | |
834 * @param im The IM. | |
835 * | |
836 * @return The type again timeout interval. | |
837 */ | |
838 guint gaim_im_get_type_again_timeout(const struct gaim_im *im); | |
839 | |
840 /** | |
841 * Updates the visual typing notification for an IM conversation. | |
842 * | |
843 * @param im The IM. | |
844 */ | |
845 void gaim_im_update_typing(struct gaim_im *im); | |
846 | |
847 /** | |
848 * Writes to an IM. | |
849 * | |
850 * The @a len parameter is used for writing binary data, such as an | |
851 * image. If @c message is text, specify -1 for @a len. | |
852 * | |
853 * @param im The IM. | |
854 * @param who The user who sent the message. | |
855 * @param message The message to write. | |
856 * @param len The length of the message, or -1 to specify the length | |
857 * of @a message. | |
858 * @param flag The flags. | |
859 * @param mtime The time the message was sent. | |
860 */ | |
861 void gaim_im_write(struct gaim_im *im, const char *who, | |
862 const char *message, size_t len, int flag, time_t mtime); | |
863 | |
864 /** | |
865 * Sends a message to this IM conversation. | |
866 * | |
867 * @param im The IM. | |
868 * @param message The message to send. | |
869 */ | |
870 void gaim_im_send(struct gaim_im *im, const char *message); | |
871 | |
872 /*@}*/ | |
873 | |
874 | |
875 /**************************************************************************/ | |
876 /** @name Chat Conversation API */ | |
877 /**************************************************************************/ | |
878 /*@{*/ | |
879 | |
880 /** | |
881 * Gets a chat's parent conversation. | |
882 * | |
883 * @param chat The chat. | |
884 * | |
885 * @return The parent conversation. | |
886 */ | |
887 struct gaim_conversation *gaim_chat_get_conversation(struct gaim_chat *chat); | |
888 | |
889 /** | |
890 * Sets the list of users in the chat room. | |
891 * | |
892 * @param chat The chat. | |
893 * @param users The list of users. | |
894 * | |
895 * @return The list passed. | |
896 */ | |
897 GList *gaim_chat_set_users(struct gaim_chat *chat, GList *users); | |
898 | |
899 /** | |
900 * Returns a list of users in the chat room. | |
901 * | |
902 * @param chat The chat. | |
903 * | |
904 * @return The list of users. | |
905 */ | |
906 GList *gaim_chat_get_users(const struct gaim_chat *chat); | |
907 | |
908 /** | |
909 * Ignores a user in a chat room. | |
910 * | |
911 * @param chat The chat. | |
912 * @param name The name of the user. | |
913 */ | |
914 void gaim_chat_ignore(struct gaim_chat *chat, const char *name); | |
915 | |
916 /** | |
917 * Unignores a user in a chat room. | |
918 * | |
919 * @param chat The chat. | |
920 * @param name The name of the user. | |
921 */ | |
922 void gaim_chat_unignore(struct gaim_chat *chat, const char *name); | |
923 | |
924 /** | |
925 * Sets the list of ignored users in the chat room. | |
926 * | |
927 * @param chat The chat. | |
928 * @param ignored The list of ignored users. | |
929 * | |
930 * @return The list passed. | |
931 */ | |
932 GList *gaim_chat_set_ignored(struct gaim_chat *chat, GList *ignored); | |
933 | |
934 /** | |
935 * Returns the list of ignored users in the chat room. | |
936 * | |
937 * @param chat The chat. | |
938 * | |
939 * @return The list of ignored users. | |
940 */ | |
941 GList *gaim_chat_get_ignored(const struct gaim_chat *chat); | |
942 | |
943 /** | |
944 * Returns the actual name of the specified ignored user, if it exists in | |
945 * the ignore list. | |
946 * | |
947 * If the user found contains a prefix, such as '+' or '\@', this is also | |
948 * returned. The username passed to the function does not have to have this | |
949 * formatting. | |
950 * | |
951 * @param chat The chat. | |
952 * @param user The user to check in the ignore list. | |
953 * | |
954 * @return The ignored user if found, complete with prefixes, or @c NULL | |
955 * if not found. | |
956 */ | |
957 const char *gaim_chat_get_ignored_user(const struct gaim_chat *chat, | |
958 const char *user); | |
959 | |
960 /** | |
961 * Returns @c TRUE if the specified user is ignored. | |
962 * | |
963 * @param chat The chat. | |
964 * @param user The user. | |
965 * | |
966 * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise. | |
967 */ | |
968 gboolean gaim_chat_is_user_ignored(const struct gaim_chat *chat, | |
969 const char *user); | |
970 | |
971 /** | |
972 * Sets the chat room's topic. | |
973 * | |
974 * @param chat The chat. | |
975 * @param who The user that set the topic. | |
976 * @param topic The topic. | |
977 */ | |
978 void gaim_chat_set_topic(struct gaim_chat *chat, const char *who, | |
979 const char *topic); | |
980 | |
981 /** | |
982 * Returns the chat room's topic. | |
983 * | |
984 * @param chat The chat. | |
985 * | |
986 * @return The chat's topic. | |
987 */ | |
988 const char *gaim_chat_get_topic(const struct gaim_chat *chat); | |
989 | |
990 /** | |
991 * Sets the chat room's ID. | |
992 * | |
993 * @param chat The chat. | |
994 * @param id The ID. | |
995 */ | |
996 void gaim_chat_set_id(struct gaim_chat *chat, int id); | |
997 | |
998 /** | |
999 * Returns the chat room's ID. | |
1000 * | |
1001 * @param chat The chat. | |
1002 * | |
1003 * @return The ID. | |
1004 */ | |
1005 int gaim_chat_get_id(const struct gaim_chat *chat); | |
1006 | |
1007 /** | |
1008 * Writes to a chat. | |
1009 * | |
1010 * @param chat The chat. | |
1011 * @param who The user who sent the message. | |
1012 * @param message The message to write. | |
1013 * @param flag The flags. | |
1014 * @param mtime The time the message was sent. | |
1015 */ | |
1016 void gaim_chat_write(struct gaim_chat *chat, const char *who, | |
1017 const char *message, int flag, time_t mtime); | |
1018 | |
1019 /** | |
1020 * Sends a message to this chat conversation. | |
1021 * | |
1022 * @param chat The chat. | |
1023 * @param message The message to send. | |
1024 */ | |
1025 void gaim_chat_send(struct gaim_chat *chat, const char *message); | |
1026 | |
1027 /** | |
1028 * Adds a user to a chat. | |
1029 * | |
1030 * @param chat The chat. | |
1031 * @param user The user to add. | |
1032 * @param extra_msg An extra message to display with the join message. | |
1033 */ | |
1034 void gaim_chat_add_user(struct gaim_chat *chat, const char *user, | |
1035 const char *extra_msg); | |
1036 | |
1037 /** | |
1038 * Renames a user in a chat. | |
1039 * | |
1040 * @param chat The chat. | |
1041 * @param old_user The old username. | |
1042 * @param new_user The new username. | |
1043 */ | |
1044 void gaim_chat_rename_user(struct gaim_chat *chat, const char *old_user, | |
1045 const char *new_user); | |
1046 | |
1047 /** | |
1048 * Removes a user from a chat, optionally with a reason. | |
1049 * | |
1050 * @param chat The chat. | |
1051 * @param user The user that is being removed. | |
1052 * @param reason The optional reason given for the removal. Can be @c NULL. | |
1053 */ | |
1054 void gaim_chat_remove_user(struct gaim_chat *chat, const char *user, | |
1055 const char *reason); | |
1056 | |
1057 /** | |
1058 * Finds a chat with the specified chat ID. | |
1059 * | |
1060 * @param gc The gaim_connection. | |
1061 * @param id The chat ID. | |
1062 * | |
1063 * @return The chat conversation. | |
1064 */ | |
1065 struct gaim_conversation *gaim_find_chat(struct gaim_connection *gc, int id); | |
1066 | |
1067 /*@}*/ | |
1068 | |
1069 #endif /* _CONVERSATION_H_ */ |