src/conversation.h

   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 _GAIM_CONVERSATION_H_
  25 #define _GAIM_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_ui_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.           */
  47         GAIM_CONV_CHAT,        /**< Chat room.                 */
  48         GAIM_CONV_MISC         /**< A misc. conversation.      */
  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_ACCOUNT, /**< The gaim_account 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          */
  81         GAIM_CONV_ACCOUNT_ONLINE,  /**< One of the user's accounts went online.  */
  82         GAIM_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */
  83         GAIM_CONV_UPDATE_AWAY      /**< The other user went away.                */
  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_ui_ops
  96 {
  97         struct gaim_conversation_ui_ops *(*get_conversation_ui_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_ui_ops structure to the gaim_conversation.
 123  */
 124 struct gaim_conversation_ui_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_ui_ops *ui_ops; /**< UI-specific window operations.   */
 158         void *ui_data;                     /**< UI-specific data.                */
 159 };
 160
 161 /**
 162  * Data specific to Instant Messages.
 163  */
 164 struct gaim_im
 165 {
 166         struct gaim_conversation *conv;    /**< The parent conversation.     */
 167
 168         int    typing_state;               /**< The current typing state.    */
 169         guint  typing_timeout;             /**< The typing timer handle.     */
 170         time_t type_again;                 /**< The type again time.         */
 171         guint  type_again_timeout;         /**< The type again timer handle. */
 172
 173         GSList *images;                    /**< A list of images in the IM.  */
 174 };
 175
 176 /**
 177  * Data specific to Chats.
 178  */
 179 struct gaim_chat
 180 {
 181         struct gaim_conversation *conv;  /**< The parent conversation.      */
 182
 183         GList *in_room;                  /**< The users in the room.        */
 184         GList *ignored;                  /**< Ignored users.                */
 185         char  *who;                      /**< The person who set the topic. */
 186         char  *topic;                    /**< The topic.                    */
 187         int    id;                       /**< The chat ID.                  */
 188 };
 189
 190 /**
 191  * A core representation of a conversation between two or more people.
 192  *
 193  * The conversation can be an IM or a chat. Each conversation is kept
 194  * in a gaim_window and has a UI representation.
 195  */
 196 struct gaim_conversation
 197 {
 198         GaimConversationType type;  /**< The type of conversation.          */
 199
 200         struct gaim_account *account;  /**< The user using this conversation.  */
 201         struct gaim_window *window; /**< The parent window.                 */
 202
 203         int conversation_pos;       /**< The position in the window's list. */
 204
 205         char *name;                 /**< The name of the conversation.      */
 206         char *title;                /**< The window title.                  */
 207
 208         gboolean logging;           /**< The status of logging.             */
 209
 210         GList *send_history;        /**< The send history.                  */
 211         GString *history;           /**< The conversation history.          */
 212
 213         GaimUnseenState unseen;     /**< The unseen tab state.              */
 214
 215         union
 216         {
 217                 struct gaim_im   *im;   /**< IM-specific data.                  */
 218                 struct gaim_chat *chat; /**< Chat-specific data.                */
 219                 void *misc;             /**< Misc. data.                        */
 220
 221         } u;
 222
 223         struct gaim_conversation_ui_ops *ui_ops; /**< UI-specific operations. */
 224         void *ui_data;                           /**< UI-specific data.       */
 225
 226         GHashTable *data;                 /**< Plugin-specific data.   */
 227 };
 228
 229 typedef void (*gaim_conv_placement_fnc)(struct gaim_conversation *);
 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_ui_ops(struct gaim_window *win,
 288                                                         struct gaim_window_ui_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_ui_ops *gaim_window_get_ui_ops(
 298                 const struct gaim_window *win);
 299
 300 /**
 301  * Adds a conversation to this window.
 302  *
 303  * If the conversation already has a parent window, this will do nothing.
 304  *
 305  * @param win  The window.
 306  * @param conv The conversation.
 307  *
 308  * @return The new index of the conversation in the window.
 309  */
 310 int gaim_window_add_conversation(struct gaim_window *win,
 311                                                                  struct gaim_conversation *conv);
 312
 313 /**
 314  * Removes the conversation at the specified index from the window.
 315  *
 316  * If there is no conversation at this index, this will do nothing.
 317  *
 318  * @param win   The window.
 319  * @param index The index of the conversation.
 320  *
 321  * @return The conversation removed.
 322  */
 323 struct gaim_conversation *gaim_window_remove_conversation(
 324                 struct gaim_window *win, unsigned int index);
 325
 326 /**
 327  * Moves the conversation at the specified index in a window to a new index.
 328  *
 329  * @param win      The window.
 330  * @param index     The index of the conversation to move.
 331  * @param new_index The new index.
 332  */
 333 void gaim_window_move_conversation(struct gaim_window *win,
 334                                                                    unsigned int index, unsigned int new_index);
 335
 336 /**
 337  * Returns the conversation in the window at the specified index.
 338  *
 339  * If the index is out of range, this returns @c NULL.
 340  *
 341  * @param win   The window.
 342  * @param index The index containing a conversation.
 343  *
 344  * @return The conversation at the specified index.
 345  */
 346 struct gaim_conversation *gaim_window_get_conversation_at(
 347                 const struct gaim_window *win, unsigned int index);
 348
 349 /**
 350  * Returns the number of conversations in the window.
 351  *
 352  * @param win The window.
 353  *
 354  * @return The number of conversations.
 355  */
 356 size_t gaim_window_get_conversation_count(const struct gaim_window *win);
 357
 358 /**
 359  * Switches the active conversation to the one at the specified index.
 360  *
 361  * If @a index is out of range, this does nothing.
 362  *
 363  * @param win   The window.
 364  * @param index The new index.
 365  */
 366 void gaim_window_switch_conversation(struct gaim_window *win,
 367                                                                          unsigned int index);
 368
 369 /**
 370  * Returns the active conversation in the window.
 371  *
 372  * @param win The window.
 373  *
 374  * @return The active conversation.
 375  */
 376 struct gaim_conversation *gaim_window_get_active_conversation(
 377                 const struct gaim_window *win);
 378
 379 /**
 380  * Returns the list of conversations in the specified window.
 381  *
 382  * @param win The window.
 383  *
 384  * @return The list of conversations.
 385  */
 386 GList *gaim_window_get_conversations(const struct gaim_window *win);
 387
 388 /**
 389  * Returns a list of all windows.
 390  *
 391  * @return A list of windows.
 392  */
 393 GList *gaim_get_windows(void);
 394
 395 /**
 396  * Returns the first window containing a conversation of the specified type.
 397  *
 398  * @param type The conversation type.
 399  *
 400  * @return The window if found, or @c NULL if not found.
 401  */
 402 struct gaim_window *gaim_get_first_window_with_type(GaimConversationType type);
 403
 404 /**
 405  * Returns the last window containing a conversation of the specified type.
 406  *
 407  * @param type The conversation type.
 408  *
 409  * @return The window if found, or @c NULL if not found.
 410  */
 411 struct gaim_window *gaim_get_last_window_with_type(GaimConversationType type);
 412
 413 /*@}*/
 414
 415 /**************************************************************************/
 416 /** @name Conversation API                                                */
 417 /**************************************************************************/
 418 /*@{*/
 419
 420 /**
 421  * Creates a new conversation of the specified type.
 422  *
 423  * @param type The type of conversation.
 424  * @param user The account opening the conversation window on the gaim
 425  *             user's end.
 426  * @param name The name of the conversation.
 427  *
 428  * @return The new conversation.
 429  */
 430 struct gaim_conversation *gaim_conversation_new(GaimConversationType type,
 431                                                                                                 struct gaim_account *account,
 432                                                                                                 const char *name);
 433
 434 /**
 435  * Destroys the specified conversation and removes it from the parent
 436  * window.
 437  *
 438  * If this conversation is the only one contained in the parent window,
 439  * that window is also destroyed.
 440  *
 441  * @param conv The conversation to destroy.
 442  */
 443 void gaim_conversation_destroy(struct gaim_conversation *conv);
 444
 445 /**
 446  * Returns the specified conversation's type.
 447  *
 448  * @param conv The conversation.
 449  *
 450  * @return The conversation's type.
 451  */
 452 GaimConversationType gaim_conversation_get_type(
 453                 const struct gaim_conversation *conv);
 454
 455 /**
 456  * Sets the specified conversation's UI operations structure.
 457  *
 458  * @param conv The conversation.
 459  * @param ops  The UI conversation operations structure.
 460  */
 461 void gaim_conversation_set_ui_ops(struct gaim_conversation *conv,
 462                                                                   struct gaim_conversation_ui_ops *ops);
 463
 464 /**
 465  * Returns the specified conversation's UI operations structure.
 466  *
 467  * @param conv The conversation.
 468  *
 469  * @return The operations structure.
 470  */
 471 struct gaim_conversation_ui_ops *gaim_conversation_get_ui_ops(
 472                 struct gaim_conversation *conv);
 473
 474 /**
 475  * Sets the specified conversation's gaim_account.
 476  *
 477  * This gaim_account represents the user using gaim, not the person the user
 478  * is having a conversation/chat/flame with.
 479  *
 480  * @param conv The conversation.
 481  * @param account The gaim_account.
 482  */
 483 void gaim_conversation_set_account(struct gaim_conversation *conv,
 484                                                                 struct gaim_account *account);
 485
 486 /**
 487  * Returns the specified conversation's gaim_account.
 488  *
 489  * This gaim_account represents the user using gaim, not the person the user
 490  * is having a conversation/chat/flame with.
 491  *
 492  * @param conv The conversation.
 493  *
 494  * @return The conversation's gaim_account.
 495  */
 496 struct gaim_account *gaim_conversation_get_account(
 497                 const struct gaim_conversation *conv);
 498
 499 /**
 500  * Returns the specified conversation's gaim_connection.
 501  *
 502  * This is the same as gaim_conversation_get_user(conv)->gc.
 503  *
 504  * @param conv The conversation.
 505  *
 506  * @return The conversation's gaim_connection.
 507  */
 508 struct gaim_connection *gaim_conversation_get_gc(
 509                 const struct gaim_conversation *conv);
 510
 511 /**
 512  * Sets the specified conversation's title.
 513  *
 514  * @param conv  The conversation.
 515  * @param title The title.
 516  */
 517 void gaim_conversation_set_title(struct gaim_conversation *conv,
 518                                                                  const char *title);
 519
 520 /**
 521  * Returns the specified conversation's title.
 522  *
 523  * @param win The conversation.
 524  *
 525  * @return The title.
 526  */
 527 const char *gaim_conversation_get_title(const struct gaim_conversation *conv);
 528
 529 /**
 530  * Automatically sets the specified conversation's title.
 531  *
 532  * This function takes OPT_IM_ALIAS_TAB into account, as well as the
 533  * user's alias.
 534  *
 535  * @param conv The conversation.
 536  */
 537 void gaim_conversation_autoset_title(struct gaim_conversation *conv);
 538
 539 /**
 540  * Returns the specified conversation's index in the parent window.
 541  *
 542  * @param conv The conversation.
 543  *
 544  * @return The current index in the parent window.
 545  */
 546 int gaim_conversation_get_index(const struct gaim_conversation *conv);
 547
 548 /**
 549  * Sets the conversation's unseen state.
 550  *
 551  * @param conv  The conversation.
 552  * @param state The new unseen state.
 553  */
 554 void gaim_conversation_set_unseen(struct gaim_conversation *conv,
 555                                                                   GaimUnseenState state);
 556
 557 /**
 558  * Returns the conversation's unseen state.
 559  *
 560  * @param conv The conversation.
 561  *
 562  * @param The conversation's unseen state.
 563  */
 564 GaimUnseenState gaim_conversation_get_unseen(
 565                 const struct gaim_conversation *conv);
 566
 567 /**
 568  * Returns the specified conversation's name.
 569  *
 570  * @param conv The conversation.
 571  *
 572  * @return The conversation's name.
 573  */
 574 const char *gaim_conversation_get_name(const struct gaim_conversation *conv);
 575
 576 /**
 577  * Enables or disables logging for this conversation.
 578  *
 579  * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
 580  */
 581 void gaim_conversation_set_logging(struct gaim_conversation *conv,
 582                                                                    gboolean log);
 583
 584 /**
 585  * Returns whether or not logging is enabled for this conversation.
 586  *
 587  * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
 588  */
 589 gboolean gaim_conversation_is_logging(const struct gaim_conversation *conv);
 590
 591 /**
 592  * Returns the specified conversation's send history.
 593  *
 594  * @param conv The conversation.
 595  *
 596  * @return The conversation's send history.
 597  */
 598 GList *gaim_conversation_get_send_history(
 599                 const struct gaim_conversation *conv);
 600
 601 /**
 602  * Sets the specified conversation's history.
 603  *
 604  * @param conv    The conversation.
 605  * @param history The history.
 606  */
 607 void gaim_conversation_set_history(struct gaim_conversation *conv,
 608                                                                    GString *history);
 609
 610 /**
 611  * Returns the specified conversation's history.
 612  *
 613  * @param conv The conversation.
 614  *
 615  * @return The conversation's history.
 616  */
 617 GString *gaim_conversation_get_history(const struct gaim_conversation *conv);
 618
 619 /**
 620  * Returns the specified conversation's parent window.
 621  *
 622  * @param conv The conversation.
 623  *
 624  * @return The conversation's parent window.
 625  */
 626 struct gaim_window *gaim_conversation_get_window(
 627                 const struct gaim_conversation *conv);
 628
 629 /**
 630  * Returns the specified conversation's IM-specific data.
 631  *
 632  * If the conversation type is not GAIM_CONV_IM, this will return @c NULL.
 633  *
 634  * @param conv The conversation.
 635  *
 636  * @return The IM-specific data.
 637  */
 638 struct gaim_im *gaim_conversation_get_im_data(
 639                 const struct gaim_conversation *conv);
 640
 641 #define GAIM_IM(c) (gaim_conversation_get_im_data(c))
 642
 643 /**
 644  * Returns the specified conversation's chat-specific data.
 645  *
 646  * If the conversation type is not GAIM_CONV_CHAT, this will return @c NULL.
 647  *
 648  * @param conv The conversation.
 649  *
 650  * @return The chat-specific data.
 651  */
 652 struct gaim_chat *gaim_conversation_get_chat_data(
 653                 const struct gaim_conversation *conv);
 654
 655 #define GAIM_CHAT(c) (gaim_conversation_get_chat_data(c))
 656
 657 /**
 658  * Sets extra data for a conversation.
 659  *
 660  * @param conv The conversation.
 661  * @param key  The unique key.
 662  * @param data The data to assign.
 663  */
 664 void gaim_conversation_set_data(struct gaim_conversation *conv,
 665                                                                 const char *key, gpointer data);
 666
 667 /**
 668  * Returns extra data in a conversation.
 669  *
 670  * @param conv The conversation.
 671  * @param key  The unqiue key.
 672  *
 673  * @return The data associated with the key.
 674  */
 675 gpointer gaim_conversation_get_data(struct gaim_conversation *conv,
 676                                                                         const char *key);
 677
 678 /**
 679  * Returns a list of all conversations.
 680  *
 681  * This list includes both IMs and chats.
 682  *
 683  * @return A GList of all conversations.
 684  */
 685 GList *gaim_get_conversations(void);
 686
 687 /**
 688  * Returns a list of all IMs.
 689  *
 690  * @return A GList of all IMs.
 691  */
 692 GList *gaim_get_ims(void);
 693
 694 /**
 695  * Returns a list of all chats.
 696  *
 697  * @return A GList of all chats.
 698  */
 699 GList *gaim_get_chats(void);
 700
 701 /**
 702  * Finds the conversation with the specified name.
 703  *
 704  * @param name The name of the conversation.
 705  *
 706  * @return The conversation if found, or @c NULL otherwise.
 707  */
 708 struct gaim_conversation *gaim_find_conversation(const char *name);
 709
 710 /**
 711  * Finds a conversation with the specified name and user.
 712  *
 713  * @param name The name of the conversation.
 714  * @param account The gaim_account associated with the conversation.
 715  *
 716  * @return The conversation if found, or @c NULL otherwise.
 717  */
 718 struct gaim_conversation *gaim_find_conversation_with_account(
 719                 const char *name, const struct gaim_account *account);
 720
 721 /**
 722  * Writes to a conversation window.
 723  *
 724  * This function should not be used to write IM or chat messages. Use
 725  * gaim_im_write() and gaim_chat_write() instead. Those functions will
 726  * most likely call this anyway, but they may do their own formatting,
 727  * sound playback, etc.
 728  *
 729  * This can be used to write generic messages, such as "so and so closed
 730  * the conversation window."
 731  *
 732  * @param conv    The conversation.
 733  * @param who     The user who sent the message.
 734  * @param message The message.
 735  * @param length  The length of the message.
 736  * @param flags   The flags.
 737  * @param mtime   The time the message was sent.
 738  *
 739  * @see gaim_im_write()
 740  * @see gaim_chat_write()
 741  */
 742 void gaim_conversation_write(struct gaim_conversation *conv, const char *who,
 743                                                          const char *message, size_t length, int flags,
 744                                                          time_t mtime);
 745
 746 /**
 747  * Updates the progress bar on a conversation window
 748  * (if one exists in the UI).
 749  *
 750  * This is used for loading images typically.
 751  *
 752  * @param conv    The conversation.
 753  * @param percent The percentage.
 754  */
 755 void gaim_conversation_update_progress(struct gaim_conversation *conv,
 756                                                                            float percent);
 757
 758 /**
 759  * Updates the visual status and UI of a conversation.
 760  *
 761  * @param conv The conversation.
 762  * @param type The update type.
 763  */
 764 void gaim_conversation_update(struct gaim_conversation *conv,
 765                                                           GaimConvUpdateType type);
 766
 767 /**
 768  * Calls a function on each conversation.
 769  *
 770  * @param func The function.
 771  */
 772 void gaim_conversation_foreach(void (*func)(struct gaim_conversation *conv));
 773
 774 /*@}*/
 775
 776
 777 /**************************************************************************/
 778 /** @name IM Conversation API                                             */
 779 /**************************************************************************/
 780 /*@{*/
 781
 782 /**
 783  * Gets an IM's parent conversation.
 784  *
 785  * @param im The IM.
 786  *
 787  * @return The parent conversation.
 788  */
 789 struct gaim_conversation *gaim_im_get_conversation(struct gaim_im *im);
 790
 791 /**
 792  * Sets the IM's typing state.
 793  *
 794  * @param im    The IM.
 795  * @param state The typing state.
 796  */
 797 void gaim_im_set_typing_state(struct gaim_im *im, int state);
 798
 799 /**
 800  * Returns the IM's typing state.
 801  *
 802  * @param im The IM.
 803  *
 804  * @return The IM's typing state.
 805  */
 806 int gaim_im_get_typing_state(const struct gaim_im *im);
 807
 808 /**
 809  * Starts the IM's typing timeout.
 810  *
 811  * @param im      The IM.
 812  * @param timeout The timeout.
 813  */
 814 void gaim_im_start_typing_timeout(struct gaim_im *im, int timeout);
 815
 816 /**
 817  * Stops the IM's typing timeout.
 818  *
 819  * @param im The IM.
 820  */
 821 void gaim_im_stop_typing_timeout(struct gaim_im *im);
 822
 823 /**
 824  * Returns the IM's typing timeout.
 825  *
 826  * @param im The IM.
 827  *
 828  * @return The timeout.
 829  */
 830 guint gaim_im_get_typing_timeout(const struct gaim_im *im);
 831
 832 /**
 833  * Sets the IM's time until it should send another typing notification.
 834  *
 835  * @param im  The IM.
 836  * @param val The time.
 837  */
 838 void gaim_im_set_type_again(struct gaim_im *im, time_t val);
 839
 840 /**
 841  * Returns the IM's time until it should send another typing notification.
 842  *
 843  * @param im The IM.
 844  *
 845  * @return The time.
 846  */
 847 time_t gaim_im_get_type_again(const struct gaim_im *im);
 848
 849 /**
 850  * Starts the IM's type again timeout.
 851  *
 852  * @param im      The IM.
 853  */
 854 void gaim_im_start_type_again_timeout(struct gaim_im *im);
 855
 856 /**
 857  * Stops the IM's type again timeout.
 858  *
 859  * @param im The IM.
 860  */
 861 void gaim_im_stop_type_again_timeout(struct gaim_im *im);
 862
 863 /**
 864  * Returns the IM's type again timeout interval.
 865  *
 866  * @param im The IM.
 867  *
 868  * @return The type again timeout interval.
 869  */
 870 guint gaim_im_get_type_again_timeout(const struct gaim_im *im);
 871
 872 /**
 873  * Updates the visual typing notification for an IM conversation.
 874  *
 875  * @param im The IM.
 876  */
 877 void gaim_im_update_typing(struct gaim_im *im);
 878
 879 /**
 880  * Writes to an IM.
 881  *
 882  * The @a len parameter is used for writing binary data, such as an
 883  * image. If @c message is text, specify -1 for @a len.
 884  *
 885  * @param im      The IM.
 886  * @param who     The user who sent the message.
 887  * @param message The message to write.
 888  * @param len     The length of the message, or -1 to specify the length
 889  *                of @a message.
 890  * @param flag    The flags.
 891  * @param mtime   The time the message was sent.
 892  */
 893 void gaim_im_write(struct gaim_im *im, const char *who,
 894                                    const char *message, size_t len, int flag, time_t mtime);
 895
 896 /**
 897  * Sends a message to this IM conversation.
 898  *
 899  * @param im      The IM.
 900  * @param message The message to send.
 901  */
 902 void gaim_im_send(struct gaim_im *im, const char *message);
 903
 904 /*@}*/
 905
 906
 907 /**************************************************************************/
 908 /** @name Chat Conversation API                                           */
 909 /**************************************************************************/
 910 /*@{*/
 911
 912 /**
 913  * Gets a chat's parent conversation.
 914  *
 915  * @param chat The chat.
 916  *
 917  * @return The parent conversation.
 918  */
 919 struct gaim_conversation *gaim_chat_get_conversation(struct gaim_chat *chat);
 920
 921 /**
 922  * Sets the list of users in the chat room.
 923  *
 924  * @param chat  The chat.
 925  * @param users The list of users.
 926  *
 927  * @return The list passed.
 928  */
 929 GList *gaim_chat_set_users(struct gaim_chat *chat, GList *users);
 930
 931 /**
 932  * Returns a list of users in the chat room.
 933  *
 934  * @param chat The chat.
 935  *
 936  * @return The list of users.
 937  */
 938 GList *gaim_chat_get_users(const struct gaim_chat *chat);
 939
 940 /**
 941  * Ignores a user in a chat room.
 942  *
 943  * @param chat The chat.
 944  * @param name The name of the user.
 945  */
 946 void gaim_chat_ignore(struct gaim_chat *chat, const char *name);
 947
 948 /**
 949  * Unignores a user in a chat room.
 950  *
 951  * @param chat The chat.
 952  * @param name The name of the user.
 953  */
 954 void gaim_chat_unignore(struct gaim_chat *chat, const char *name);
 955
 956 /**
 957  * Sets the list of ignored users in the chat room.
 958  *
 959  * @param chat    The chat.
 960  * @param ignored The list of ignored users.
 961  *
 962  * @return The list passed.
 963  */
 964 GList *gaim_chat_set_ignored(struct gaim_chat *chat, GList *ignored);
 965
 966 /**
 967  * Returns the list of ignored users in the chat room.
 968  *
 969  * @param chat The chat.
 970  *
 971  * @return The list of ignored users.
 972  */
 973 GList *gaim_chat_get_ignored(const struct gaim_chat *chat);
 974
 975 /**
 976  * Returns the actual name of the specified ignored user, if it exists in
 977  * the ignore list.
 978  *
 979  * If the user found contains a prefix, such as '+' or '\@', this is also
 980  * returned. The username passed to the function does not have to have this
 981  * formatting.
 982  *
 983  * @param chat The chat.
 984  * @param user The user to check in the ignore list.
 985  *
 986  * @return The ignored user if found, complete with prefixes, or @c NULL
 987  *         if not found.
 988  */
 989 const char *gaim_chat_get_ignored_user(const struct gaim_chat *chat,
 990                                                                            const char *user);
 991
 992 /**
 993  * Returns @c TRUE if the specified user is ignored.
 994  *
 995  * @param chat The chat.
 996  * @param user The user.
 997  *
 998  * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise.
 999  */
1000 gboolean gaim_chat_is_user_ignored(const struct gaim_chat *chat,
1001                                                                    const char *user);
1002
1003 /**
1004  * Sets the chat room's topic.
1005  *
1006  * @param chat  The chat.
1007  * @param who   The user that set the topic.
1008  * @param topic The topic.
1009  */
1010 void gaim_chat_set_topic(struct gaim_chat *chat, const char *who,
1011                                                  const char *topic);
1012
1013 /**
1014  * Returns the chat room's topic.
1015  *
1016  * @param chat The chat.
1017  *
1018  * @return The chat's topic.
1019  */
1020 const char *gaim_chat_get_topic(const struct gaim_chat *chat);
1021
1022 /**
1023  * Sets the chat room's ID.
1024  *
1025  * @param chat The chat.
1026  * @param id   The ID.
1027  */
1028 void gaim_chat_set_id(struct gaim_chat *chat, int id);
1029
1030 /**
1031  * Returns the chat room's ID.
1032  *
1033  * @param chat The chat.
1034  *
1035  * @return The ID.
1036  */
1037 int gaim_chat_get_id(const struct gaim_chat *chat);
1038
1039 /**
1040  * Writes to a chat.
1041  *
1042  * @param chat    The chat.
1043  * @param who     The user who sent the message.
1044  * @param message The message to write.
1045  * @param flag    The flags.
1046  * @param mtime   The time the message was sent.
1047  */
1048 void gaim_chat_write(struct gaim_chat *chat, const char *who,
1049                                          const char *message, int flag, time_t mtime);
1050
1051 /**
1052  * Sends a message to this chat conversation.
1053  *
1054  * @param chat    The chat.
1055  * @param message The message to send.
1056  */
1057 void gaim_chat_send(struct gaim_chat *chat, const char *message);
1058
1059 /**
1060  * Adds a user to a chat.
1061  *
1062  * @param chat      The chat.
1063  * @param user      The user to add.
1064  * @param extra_msg An extra message to display with the join message.
1065  */
1066 void gaim_chat_add_user(struct gaim_chat *chat, const char *user,
1067                                                 const char *extra_msg);
1068
1069 /**
1070  * Renames a user in a chat.
1071  *
1072  * @param chat     The chat.
1073  * @param old_user The old username.
1074  * @param new_user The new username.
1075  */
1076 void gaim_chat_rename_user(struct gaim_chat *chat, const char *old_user,
1077                                                    const char *new_user);
1078
1079 /**
1080  * Removes a user from a chat, optionally with a reason.
1081  *
1082  * @param chat   The chat.
1083  * @param user   The user that is being removed.
1084  * @param reason The optional reason given for the removal. Can be @c NULL.
1085  */
1086 void gaim_chat_remove_user(struct gaim_chat *chat, const char *user,
1087                                                    const char *reason);
1088
1089 /**
1090  * Finds a chat with the specified chat ID.
1091  *
1092  * @param gc The gaim_connection.
1093  * @param id The chat ID.
1094  *
1095  * @return The chat conversation.
1096  */
1097 struct gaim_conversation *gaim_find_chat(struct gaim_connection *gc, int id);
1098
1099 /*@}*/
1100
1101 /**************************************************************************/
1102 /** @name Conversation Placement Functions                                */
1103 /**************************************************************************/
1104 /*@{*/
1105
1106 /**
1107  * Adds a conversation placement function to the list of possible functions.
1108  *
1109  * @param name The name of the function.
1110  * @param fnc  A pointer to the function.
1111  *
1112  * @return The index of this entry.
1113  */
1114 int gaim_conv_placement_add_fnc(const char *name, gaim_conv_placement_fnc fnc);
1115
1116 /**
1117  * Removes a conversation placement function from the list of possible
1118  * functions.
1119  *
1120  * @param index The index of the function.
1121  */
1122 void gaim_conv_placement_remove_fnc(int index);
1123
1124 /**
1125  * Returns the number of conversation placement functions.
1126  *
1127  * @return The number of registered functions.
1128  */
1129 int gaim_conv_placement_get_fnc_count(void);
1130
1131 /**
1132  * Returns the name of the conversation placement function at the
1133  * specified index.
1134  *
1135  * @param index The index.
1136  *
1137  * @return The name of the function, or @c NULL if this index is out of
1138  *         range.
1139  */
1140 const char *gaim_conv_placement_get_name(int index);
1141
1142 /**
1143  * Returns a pointer to the conversation placement function at the
1144  * specified index.
1145  *
1146  * @param index The index.
1147  *
1148  * @return A pointer to the function.
1149  */
1150 gaim_conv_placement_fnc gaim_conv_placement_get_fnc(int index);
1151
1152 /**
1153  * Returns the index of the specified conversation placement function.
1154  *
1155  * @param fnc A pointer to the registered function.
1156  *
1157  * @return The index of the conversation, or -1 if the function is not
1158  *         registered.
1159  */
1160 int gaim_conv_placement_get_fnc_index(gaim_conv_placement_fnc fnc);
1161
1162 /**
1163  * Returns the index of the active conversation placement function.
1164  *
1165  * @param index The index of the active function.
1166  */
1167 int gaim_conv_placement_get_active(void);
1168
1169 /**
1170  * Sets the active conversation placement function.
1171  *
1172  * @param index The index of the function.
1173  */
1174 void gaim_conv_placement_set_active(int index);
1175
1176 /*@}*/
1177
1178 /**************************************************************************/
1179 /** @name UI Registration Functions                                       */
1180 /**************************************************************************/
1181 /*@{*/
1182
1183 /**
1184  * Sets the UI operations structure to be used in all gaim conversation
1185  * windows.
1186  *
1187  * @param fnc The function.
1188  */
1189 void gaim_set_win_ui_ops(struct gaim_window_ui_ops *ops);
1190
1191 /**
1192  * Returns the gaim window UI operations structure to be used in
1193  * new windows.
1194  *
1195  * @return A filled-out gaim_window_ui_ops structure.
1196  */
1197 struct gaim_window_ui_ops *gaim_get_win_ui_ops(void);
1198
1199 /*@}*/
1200
1201 #endif /* _GAIM_CONVERSATION_H_ */