home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / conversation.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  35.8 KB  |  1,224 lines
  1. /**
  2.  * @file conversation.h Conversation API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple 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 _PURPLE_CONVERSATION_H_
  28. #define _PURPLE_CONVERSATION_H_
  29.  
  30. /**************************************************************************/
  31. /** Data Structures                                                       */
  32. /**************************************************************************/
  33.  
  34.  
  35. typedef struct _PurpleConversationUiOps PurpleConversationUiOps;
  36. typedef struct _PurpleConversation      PurpleConversation;
  37. typedef struct _PurpleConvIm            PurpleConvIm;
  38. typedef struct _PurpleConvChat          PurpleConvChat;
  39. typedef struct _PurpleConvChatBuddy     PurpleConvChatBuddy;
  40.  
  41. /**
  42.  * A type of conversation.
  43.  */
  44. typedef enum
  45. {
  46.     PURPLE_CONV_TYPE_UNKNOWN = 0, /**< Unknown conversation type. */
  47.     PURPLE_CONV_TYPE_IM,          /**< Instant Message.           */
  48.     PURPLE_CONV_TYPE_CHAT,        /**< Chat room.                 */
  49.     PURPLE_CONV_TYPE_MISC,        /**< A misc. conversation.      */
  50.     PURPLE_CONV_TYPE_ANY          /**< Any type of conversation.  */
  51.  
  52. } PurpleConversationType;
  53.  
  54. /**
  55.  * Conversation update type.
  56.  */
  57. typedef enum
  58. {
  59.     PURPLE_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation
  60.                                    was added.   */
  61.     PURPLE_CONV_UPDATE_REMOVE,  /**< The buddy associated with the conversation
  62.                                    was removed. */
  63.     PURPLE_CONV_UPDATE_ACCOUNT, /**< The purple_account was changed. */
  64.     PURPLE_CONV_UPDATE_TYPING,  /**< The typing state was updated. */
  65.     PURPLE_CONV_UPDATE_UNSEEN,  /**< The unseen state was updated. */
  66.     PURPLE_CONV_UPDATE_LOGGING, /**< Logging for this conversation was
  67.                                    enabled or disabled. */
  68.     PURPLE_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.     PURPLE_CONV_ACCOUNT_ONLINE,  /**< One of the user's accounts went online.  */
  74.     PURPLE_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */
  75.     PURPLE_CONV_UPDATE_AWAY,     /**< The other user went away.                */
  76.     PURPLE_CONV_UPDATE_ICON,     /**< The other user's buddy icon changed.     */
  77.     PURPLE_CONV_UPDATE_TITLE,
  78.     PURPLE_CONV_UPDATE_CHATLEFT,
  79.  
  80.     PURPLE_CONV_UPDATE_FEATURES, /**< The features for a chat have changed */
  81.  
  82. } PurpleConvUpdateType;
  83.  
  84. /**
  85.  * The typing state of a user.
  86.  */
  87. typedef enum
  88. {
  89.     PURPLE_NOT_TYPING = 0,  /**< Not typing.                 */
  90.     PURPLE_TYPING,          /**< Currently typing.           */
  91.     PURPLE_TYPED            /**< Stopped typing momentarily. */
  92.  
  93. } PurpleTypingState;
  94.  
  95. /**
  96.  * Flags applicable to a message. Most will have send, recv or system.
  97.  */
  98. typedef enum
  99. {
  100.     PURPLE_MESSAGE_SEND        = 0x0001, /**< Outgoing message.        */
  101.     PURPLE_MESSAGE_RECV        = 0x0002, /**< Incoming message.        */
  102.     PURPLE_MESSAGE_SYSTEM      = 0x0004, /**< System message.          */
  103.     PURPLE_MESSAGE_AUTO_RESP   = 0x0008, /**< Auto response.           */
  104.     PURPLE_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.     PURPLE_MESSAGE_NICK        = 0x0020, /**< Contains your nick.      */
  112.     PURPLE_MESSAGE_NO_LOG      = 0x0040, /**< Do not log.              */
  113.     PURPLE_MESSAGE_WHISPER     = 0x0080, /**< Whispered message.       */
  114.     PURPLE_MESSAGE_ERROR       = 0x0200, /**< Error message.           */
  115.     PURPLE_MESSAGE_DELAYED     = 0x0400, /**< Delayed message.         */
  116.     PURPLE_MESSAGE_RAW         = 0x0800, /**< "Raw" message - don't
  117.                                             apply formatting         */
  118.     PURPLE_MESSAGE_IMAGES      = 0x1000, /**< Message contains images  */
  119.     PURPLE_MESSAGE_NOTIFY      = 0x2000  /**< Message is a notification */
  120.  
  121. } PurpleMessageFlags;
  122.  
  123. /**
  124.  * Flags applicable to users in Chats.
  125.  */
  126. typedef enum
  127. {
  128.     PURPLE_CBFLAGS_NONE          = 0x0000, /**< No flags                     */
  129.     PURPLE_CBFLAGS_VOICE         = 0x0001, /**< Voiced user or "Participant" */
  130.     PURPLE_CBFLAGS_HALFOP        = 0x0002, /**< Half-op                      */
  131.     PURPLE_CBFLAGS_OP            = 0x0004, /**< Channel Op or Moderator      */
  132.     PURPLE_CBFLAGS_FOUNDER       = 0x0008, /**< Channel Founder              */
  133.     PURPLE_CBFLAGS_TYPING        = 0x0010, /**< Currently typing             */
  134.  
  135. } PurpleConvChatBuddyFlags;
  136.  
  137. #include "account.h"
  138. #include "buddyicon.h"
  139. #include "log.h"
  140. #include "server.h"
  141.  
  142. /**
  143.  * Conversation operations and events.
  144.  *
  145.  * Any UI representing a conversation must assign a filled-out
  146.  * PurpleConversationUiOps structure to the PurpleConversation.
  147.  */
  148. struct _PurpleConversationUiOps
  149. {
  150.     void (*create_conversation)(PurpleConversation *conv);
  151.     void (*destroy_conversation)(PurpleConversation *conv);
  152.     void (*write_chat)(PurpleConversation *conv, const char *who,
  153.                        const char *message, PurpleMessageFlags flags,
  154.                        time_t mtime);
  155.     void (*write_im)(PurpleConversation *conv, const char *who,
  156.                      const char *message, PurpleMessageFlags flags,
  157.                      time_t mtime);
  158.     void (*write_conv)(PurpleConversation *conv, const char *name, const char *alias,
  159.                        const char *message, PurpleMessageFlags flags,
  160.                        time_t mtime);
  161.  
  162.     void (*chat_add_users)(PurpleConversation *conv, GList *cbuddies, gboolean new_arrivals);    
  163.     
  164.     void (*chat_rename_user)(PurpleConversation *conv, const char *old_name,
  165.                              const char *new_name, const char *new_alias);
  166.     void (*chat_remove_users)(PurpleConversation *conv, GList *users);
  167.     void (*chat_update_user)(PurpleConversation *conv, const char *user);
  168.  
  169.     void (*present)(PurpleConversation *conv);
  170.  
  171.     gboolean (*has_focus)(PurpleConversation *conv);
  172.  
  173.     /* Custom Smileys */
  174.     gboolean (*custom_smiley_add)(PurpleConversation *conv, const char *smile, gboolean remote);
  175.     void (*custom_smiley_write)(PurpleConversation *conv, const char *smile,
  176.                                 const guchar *data, gsize size);
  177.     void (*custom_smiley_close)(PurpleConversation *conv, const char *smile);
  178.  
  179.     void (*send_confirm)(PurpleConversation *conv, const char *message);
  180.  
  181.     void (*_purple_reserved1)(void);
  182.     void (*_purple_reserved2)(void);
  183.     void (*_purple_reserved3)(void);
  184.     void (*_purple_reserved4)(void);
  185. };
  186.  
  187. /**
  188.  * Data specific to Instant Messages.
  189.  */
  190. struct _PurpleConvIm
  191. {
  192.     PurpleConversation *conv;            /**< The parent conversation.     */
  193.  
  194.     PurpleTypingState typing_state;      /**< The current typing state.    */
  195.     guint  typing_timeout;             /**< The typing timer handle.     */
  196.     time_t type_again;                 /**< The type again time.         */
  197.     guint  send_typed_timeout;         /**< The type again timer handle. */
  198.  
  199.     PurpleBuddyIcon *icon;               /**< The buddy icon.              */
  200. };
  201.  
  202. /**
  203.  * Data specific to Chats.
  204.  */
  205. struct _PurpleConvChat
  206. {
  207.     PurpleConversation *conv;          /**< The parent conversation.      */
  208.  
  209.     GList *in_room;                  /**< The users in the room.        */
  210.     GList *ignored;                  /**< Ignored users.                */
  211.     char  *who;                      /**< The person who set the topic. */
  212.     char  *topic;                    /**< The topic.                    */
  213.     int    id;                       /**< The chat ID.                  */
  214.     char *nick;                      /**< Your nick in this chat.       */
  215.  
  216.     gboolean left;                   /**< We left the chat and kept the window open */
  217. };
  218.  
  219. /**
  220.  * Data for "Chat Buddies"
  221.  */
  222. struct _PurpleConvChatBuddy
  223. {
  224.     char *name;                      /**< The name                      */
  225.     char *alias;                     /**< The alias                     */
  226.     char *alias_key;                 /**< The alias key                    */
  227.     gboolean buddy;                     /**< ChatBuddy is on the blist        */
  228.     PurpleConvChatBuddyFlags flags;    /**< Flags (ops, voice etc.)       */
  229. };
  230.  
  231. /**
  232.  * A core representation of a conversation between two or more people.
  233.  *
  234.  * The conversation can be an IM or a chat.
  235.  */
  236. struct _PurpleConversation
  237. {
  238.     PurpleConversationType type;  /**< The type of conversation.          */
  239.  
  240.     PurpleAccount *account;       /**< The user using this conversation.  */
  241.  
  242.  
  243.     char *name;                 /**< The name of the conversation.      */
  244.     char *title;                /**< The window title.                  */
  245.  
  246.     gboolean logging;           /**< The status of logging.             */
  247.  
  248.     GList *logs;                /**< This conversation's logs           */
  249.  
  250.     union
  251.     {
  252.         PurpleConvIm   *im;       /**< IM-specific data.                  */
  253.         PurpleConvChat *chat;     /**< Chat-specific data.                */
  254.         void *misc;             /**< Misc. data.                        */
  255.  
  256.     } u;
  257.  
  258.     PurpleConversationUiOps *ui_ops;           /**< UI-specific operations. */
  259.     void *ui_data;                           /**< UI-specific data.       */
  260.  
  261.     GHashTable *data;                        /**< Plugin-specific data.   */
  262.  
  263.     PurpleConnectionFlags features; /**< The supported features */
  264.  
  265. };
  266.  
  267. #ifdef __cplusplus
  268. extern "C" {
  269. #endif
  270.  
  271. /**************************************************************************/
  272. /** @name Conversation API                                                */
  273. /**************************************************************************/
  274. /*@{*/
  275.  
  276. /**
  277.  * Creates a new conversation of the specified type.
  278.  *
  279.  * @param type    The type of conversation.
  280.  * @param account The account opening the conversation window on the purple
  281.  *                user's end.
  282.  * @param name    The name of the conversation.
  283.  *
  284.  * @return The new conversation.
  285.  */
  286. PurpleConversation *purple_conversation_new(PurpleConversationType type,
  287.                                         PurpleAccount *account,
  288.                                         const char *name);
  289.  
  290. /**
  291.  * Destroys the specified conversation and removes it from the parent
  292.  * window.
  293.  *
  294.  * If this conversation is the only one contained in the parent window,
  295.  * that window is also destroyed.
  296.  *
  297.  * @param conv The conversation to destroy.
  298.  */
  299. void purple_conversation_destroy(PurpleConversation *conv);
  300.  
  301.  
  302. /**
  303.  * Present a conversation to the user. This allows core code to initiate a
  304.  * conversation by displaying the IM dialog.
  305.  * @param conv The conversation to present
  306.  */
  307. void purple_conversation_present(PurpleConversation *conv);
  308.  
  309.  
  310. /**
  311.  * Returns the specified conversation's type.
  312.  *
  313.  * @param conv The conversation.
  314.  *
  315.  * @return The conversation's type.
  316.  */
  317. PurpleConversationType purple_conversation_get_type(const PurpleConversation *conv);
  318.  
  319. /**
  320.  * Sets the specified conversation's UI operations structure.
  321.  *
  322.  * @param conv The conversation.
  323.  * @param ops  The UI conversation operations structure.
  324.  */
  325. void purple_conversation_set_ui_ops(PurpleConversation *conv,
  326.                                   PurpleConversationUiOps *ops);
  327.  
  328. /**
  329.  * Sets the default conversation UI operations structure.
  330.  *
  331.  * @param ops  The UI conversation operations structure.
  332.  */
  333. void purple_conversations_set_ui_ops(PurpleConversationUiOps *ops);
  334.  
  335. /**
  336.  * Returns the specified conversation's UI operations structure.
  337.  *
  338.  * @param conv The conversation.
  339.  *
  340.  * @return The operations structure.
  341.  */
  342. PurpleConversationUiOps *purple_conversation_get_ui_ops(
  343.         const PurpleConversation *conv);
  344.  
  345. /**
  346.  * Sets the specified conversation's purple_account.
  347.  *
  348.  * This purple_account represents the user using purple, not the person the user
  349.  * is having a conversation/chat/flame with.
  350.  *
  351.  * @param conv The conversation.
  352.  * @param account The purple_account.
  353.  */
  354. void purple_conversation_set_account(PurpleConversation *conv,
  355.                                    PurpleAccount *account);
  356.  
  357. /**
  358.  * Returns the specified conversation's purple_account.
  359.  *
  360.  * This purple_account represents the user using purple, not the person the user
  361.  * is having a conversation/chat/flame with.
  362.  *
  363.  * @param conv The conversation.
  364.  *
  365.  * @return The conversation's purple_account.
  366.  */
  367. PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv);
  368.  
  369. /**
  370.  * Returns the specified conversation's purple_connection.
  371.  *
  372.  * This is the same as purple_conversation_get_user(conv)->gc.
  373.  *
  374.  * @param conv The conversation.
  375.  *
  376.  * @return The conversation's purple_connection.
  377.  */
  378. PurpleConnection *purple_conversation_get_gc(const PurpleConversation *conv);
  379.  
  380. /**
  381.  * Sets the specified conversation's title.
  382.  *
  383.  * @param conv  The conversation.
  384.  * @param title The title.
  385.  */
  386. void purple_conversation_set_title(PurpleConversation *conv, const char *title);
  387.  
  388. /**
  389.  * Returns the specified conversation's title.
  390.  *
  391.  * @param conv The conversation.
  392.  *
  393.  * @return The title.
  394.  */
  395. const char *purple_conversation_get_title(const PurpleConversation *conv);
  396.  
  397. /**
  398.  * Automatically sets the specified conversation's title.
  399.  *
  400.  * This function takes OPT_IM_ALIAS_TAB into account, as well as the
  401.  * user's alias.
  402.  *
  403.  * @param conv The conversation.
  404.  */
  405. void purple_conversation_autoset_title(PurpleConversation *conv);
  406.  
  407. /**
  408.  * Sets the specified conversation's name.
  409.  *
  410.  * @param conv The conversation.
  411.  * @param name The conversation's name.
  412.  */
  413. void purple_conversation_set_name(PurpleConversation *conv, const char *name);
  414.  
  415. /**
  416.  * Returns the specified conversation's name.
  417.  *
  418.  * @param conv The conversation.
  419.  *
  420.  * @return The conversation's name.
  421.  */
  422. const char *purple_conversation_get_name(const PurpleConversation *conv);
  423.  
  424. /**
  425.  * Enables or disables logging for this conversation.
  426.  *
  427.  * @param conv The conversation.
  428.  * @param log  @c TRUE if logging should be enabled, or @c FALSE otherwise.
  429.  */
  430. void purple_conversation_set_logging(PurpleConversation *conv, gboolean log);
  431.  
  432. /**
  433.  * Returns whether or not logging is enabled for this conversation.
  434.  *
  435.  * @param conv The conversation.
  436.  *
  437.  * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
  438.  */
  439. gboolean purple_conversation_is_logging(const PurpleConversation *conv);
  440.  
  441. /**
  442.  * Closes any open logs for this conversation.
  443.  *
  444.  * Note that new logs will be opened as necessary (e.g. upon receipt of a
  445.  * message, if the conversation has logging enabled. To disable logging for
  446.  * the remainder of the conversation, use purple_conversation_set_logging().
  447.  *
  448.  * @param conv The conversation.
  449.  */
  450. void purple_conversation_close_logs(PurpleConversation *conv);
  451.  
  452. /**
  453.  * Returns the specified conversation's IM-specific data.
  454.  *
  455.  * If the conversation type is not PURPLE_CONV_TYPE_IM, this will return @c NULL.
  456.  *
  457.  * @param conv The conversation.
  458.  *
  459.  * @return The IM-specific data.
  460.  */
  461. PurpleConvIm *purple_conversation_get_im_data(const PurpleConversation *conv);
  462.  
  463. #define PURPLE_CONV_IM(c) (purple_conversation_get_im_data(c))
  464.  
  465. /**
  466.  * Returns the specified conversation's chat-specific data.
  467.  *
  468.  * If the conversation type is not PURPLE_CONV_TYPE_CHAT, this will return @c NULL.
  469.  *
  470.  * @param conv The conversation.
  471.  *
  472.  * @return The chat-specific data.
  473.  */
  474. PurpleConvChat *purple_conversation_get_chat_data(const PurpleConversation *conv);
  475.  
  476. #define PURPLE_CONV_CHAT(c) (purple_conversation_get_chat_data(c))
  477.  
  478. /**
  479.  * Sets extra data for a conversation.
  480.  *
  481.  * @param conv The conversation.
  482.  * @param key  The unique key.
  483.  * @param data The data to assign.
  484.  */
  485. void purple_conversation_set_data(PurpleConversation *conv, const char *key,
  486.                                 gpointer data);
  487.  
  488. /**
  489.  * Returns extra data in a conversation.
  490.  *
  491.  * @param conv The conversation.
  492.  * @param key  The unqiue key.
  493.  *
  494.  * @return The data associated with the key.
  495.  */
  496. gpointer purple_conversation_get_data(PurpleConversation *conv, const char *key);
  497.  
  498. /**
  499.  * Returns a list of all conversations.
  500.  *
  501.  * This list includes both IMs and chats.
  502.  *
  503.  * @return A GList of all conversations.
  504.  */
  505. GList *purple_get_conversations(void);
  506.  
  507. /**
  508.  * Returns a list of all IMs.
  509.  *
  510.  * @return A GList of all IMs.
  511.  */
  512. GList *purple_get_ims(void);
  513.  
  514. /**
  515.  * Returns a list of all chats.
  516.  *
  517.  * @return A GList of all chats.
  518.  */
  519. GList *purple_get_chats(void);
  520.  
  521. /**
  522.  * Finds a conversation with the specified type, name, and Purple account.
  523.  *
  524.  * @param type The type of the conversation.
  525.  * @param name The name of the conversation.
  526.  * @param account The purple_account associated with the conversation.
  527.  *
  528.  * @return The conversation if found, or @c NULL otherwise.
  529.  */
  530. PurpleConversation *purple_find_conversation_with_account(
  531.         PurpleConversationType type, const char *name,
  532.         const PurpleAccount *account);
  533.  
  534. /**
  535.  * Writes to a conversation window.
  536.  *
  537.  * This function should not be used to write IM or chat messages. Use
  538.  * purple_conv_im_write() and purple_conv_chat_write() instead. Those functions will
  539.  * most likely call this anyway, but they may do their own formatting,
  540.  * sound playback, etc.
  541.  *
  542.  * This can be used to write generic messages, such as "so and so closed
  543.  * the conversation window."
  544.  *
  545.  * @param conv    The conversation.
  546.  * @param who     The user who sent the message.
  547.  * @param message The message.
  548.  * @param flags   The message flags.
  549.  * @param mtime   The time the message was sent.
  550.  *
  551.  * @see purple_conv_im_write()
  552.  * @see purple_conv_chat_write()
  553.  */
  554. void purple_conversation_write(PurpleConversation *conv, const char *who,
  555.         const char *message, PurpleMessageFlags flags,
  556.         time_t mtime);
  557.  
  558.  
  559. /**
  560.     Set the features as supported for the given conversation.
  561.     @param conv      The conversation
  562.     @param features  Bitset defining supported features
  563. */
  564. void purple_conversation_set_features(PurpleConversation *conv,
  565.         PurpleConnectionFlags features);
  566.  
  567.  
  568. /**
  569.     Get the features supported by the given conversation.
  570.     @param conv  The conversation
  571. */
  572. PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv);
  573.  
  574. /**
  575.  * Determines if a conversation has focus
  576.  *
  577.  * @param conv    The conversation.
  578.  *
  579.  * @return @c TRUE if the conversation has focus, @c FALSE if
  580.  * it does not or the UI does not have a concept of conversation focus
  581.  */
  582. gboolean purple_conversation_has_focus(PurpleConversation *conv);
  583.  
  584. /**
  585.  * Updates the visual status and UI of a conversation.
  586.  *
  587.  * @param conv The conversation.
  588.  * @param type The update type.
  589.  */
  590. void purple_conversation_update(PurpleConversation *conv, PurpleConvUpdateType type);
  591.  
  592. /**
  593.  * Calls a function on each conversation.
  594.  *
  595.  * @param func The function.
  596.  */
  597. void purple_conversation_foreach(void (*func)(PurpleConversation *conv));
  598.  
  599. /*@}*/
  600.  
  601.  
  602. /**************************************************************************/
  603. /** @name IM Conversation API                                             */
  604. /**************************************************************************/
  605. /*@{*/
  606.  
  607. /**
  608.  * Gets an IM's parent conversation.
  609.  *
  610.  * @param im The IM.
  611.  *
  612.  * @return The parent conversation.
  613.  */
  614. PurpleConversation *purple_conv_im_get_conversation(const PurpleConvIm *im);
  615.  
  616. /**
  617.  * Sets the IM's buddy icon.
  618.  *
  619.  * This should only be called from within Purple. You probably want to
  620.  * call purple_buddy_icon_set_data().
  621.  *
  622.  * @param im   The IM.
  623.  * @param icon The buddy icon.
  624.  *
  625.  * @see purple_buddy_icon_set_data()
  626.  */
  627. void purple_conv_im_set_icon(PurpleConvIm *im, PurpleBuddyIcon *icon);
  628.  
  629. /**
  630.  * Returns the IM's buddy icon.
  631.  *
  632.  * @param im The IM.
  633.  *
  634.  * @return The buddy icon.
  635.  */
  636. PurpleBuddyIcon *purple_conv_im_get_icon(const PurpleConvIm *im);
  637.  
  638. /**
  639.  * Sets the IM's typing state.
  640.  *
  641.  * @param im    The IM.
  642.  * @param state The typing state.
  643.  */
  644. void purple_conv_im_set_typing_state(PurpleConvIm *im, PurpleTypingState state);
  645.  
  646. /**
  647.  * Returns the IM's typing state.
  648.  *
  649.  * @param im The IM.
  650.  *
  651.  * @return The IM's typing state.
  652.  */
  653. PurpleTypingState purple_conv_im_get_typing_state(const PurpleConvIm *im);
  654.  
  655. /**
  656.  * Starts the IM's typing timeout.
  657.  *
  658.  * @param im      The IM.
  659.  * @param timeout The timeout.
  660.  */
  661. void purple_conv_im_start_typing_timeout(PurpleConvIm *im, int timeout);
  662.  
  663. /**
  664.  * Stops the IM's typing timeout.
  665.  *
  666.  * @param im The IM.
  667.  */
  668. void purple_conv_im_stop_typing_timeout(PurpleConvIm *im);
  669.  
  670. /**
  671.  * Returns the IM's typing timeout.
  672.  *
  673.  * @param im The IM.
  674.  *
  675.  * @return The timeout.
  676.  */
  677. guint purple_conv_im_get_typing_timeout(const PurpleConvIm *im);
  678.  
  679. /**
  680.  * Sets the quiet-time when no PURPLE_TYPING messages will be sent.
  681.  * Few protocols need this (maybe only MSN).  If the user is still
  682.  * typing after this quiet-period, then another PURPLE_TYPING message
  683.  * will be sent.
  684.  *
  685.  * @param im  The IM.
  686.  * @param val The number of seconds to wait before allowing another
  687.  *            PURPLE_TYPING message to be sent to the user.  Or 0 to
  688.  *            not send another PURPLE_TYPING message.
  689.  */
  690. void purple_conv_im_set_type_again(PurpleConvIm *im, unsigned int val);
  691.  
  692. /**
  693.  * Returns the time after which another PURPLE_TYPING message should be sent.
  694.  *
  695.  * @param im The IM.
  696.  *
  697.  * @return The time in seconds since the epoch.  Or 0 if no additional
  698.  *         PURPLE_TYPING message should be sent.
  699.  */
  700. time_t purple_conv_im_get_type_again(const PurpleConvIm *im);
  701.  
  702. /**
  703.  * Starts the IM's type again timeout.
  704.  *
  705.  * @param im      The IM.
  706.  */
  707. void purple_conv_im_start_send_typed_timeout(PurpleConvIm *im);
  708.  
  709. /**
  710.  * Stops the IM's type again timeout.
  711.  *
  712.  * @param im The IM.
  713.  */
  714. void purple_conv_im_stop_send_typed_timeout(PurpleConvIm *im);
  715.  
  716. /**
  717.  * Returns the IM's type again timeout interval.
  718.  *
  719.  * @param im The IM.
  720.  *
  721.  * @return The type again timeout interval.
  722.  */
  723. guint purple_conv_im_get_send_typed_timeout(const PurpleConvIm *im);
  724.  
  725. /**
  726.  * Updates the visual typing notification for an IM conversation.
  727.  *
  728.  * @param im The IM.
  729.  */
  730. void purple_conv_im_update_typing(PurpleConvIm *im);
  731.  
  732. /**
  733.  * Writes to an IM.
  734.  *
  735.  * @param im      The IM.
  736.  * @param who     The user who sent the message.
  737.  * @param message The message to write.
  738.  * @param flags   The message flags.
  739.  * @param mtime   The time the message was sent.
  740.  */
  741. void purple_conv_im_write(PurpleConvIm *im, const char *who,
  742.                         const char *message, PurpleMessageFlags flags,
  743.                         time_t mtime);
  744.  
  745. /**
  746.  * Presents an IM-error to the user
  747.  *
  748.  * This is a helper function to find a conversation, write an error to it, and
  749.  * raise the window.  If a conversation with this user doesn't already exist,
  750.  * the function will return FALSE and the calling function can attempt to present
  751.  * the error another way (purple_notify_error, most likely)
  752.  *
  753.  * @param who     The user this error is about
  754.  * @param account The account this error is on
  755.  * @param what    The error
  756.  * @return        TRUE if the error was presented, else FALSE
  757.  */
  758. gboolean purple_conv_present_error(const char *who, PurpleAccount *account, const char *what);
  759.  
  760. /**
  761.  * Sends a message to this IM conversation.
  762.  *
  763.  * @param im      The IM.
  764.  * @param message The message to send.
  765.  */
  766. void purple_conv_im_send(PurpleConvIm *im, const char *message);
  767.  
  768. /**
  769.  * Sends a message to a conversation after confirming with
  770.  * the user.
  771.  *
  772.  * This function is intended for use in cases where the user
  773.  * hasn't explicitly and knowingly caused a message to be sent.
  774.  * The confirmation ensures that the user isn't sending a
  775.  * message by mistake.
  776.  *
  777.  * @param conv    The conversation.
  778.  * @param message The message to send.
  779.  */
  780. void purple_conv_send_confirm(PurpleConversation *conv, const char *message);
  781.  
  782. /**
  783.  * Sends a message to this IM conversation with specified flags.
  784.  *
  785.  * @param im      The IM.
  786.  * @param message The message to send.
  787.  * @param flags   The PurpleMessageFlags flags to use in addition to PURPLE_MESSAGE_SEND.
  788.  */
  789. void purple_conv_im_send_with_flags(PurpleConvIm *im, const char *message, PurpleMessageFlags flags);
  790.  
  791. /**
  792.  * Adds a smiley to the conversation's smiley tree. If this returns
  793.  * @c TRUE you should call purple_conv_custom_smiley_write() one or more
  794.  * times, and then purple_conv_custom_smiley_close(). If this returns
  795.  * @c FALSE, either the conv or smile were invalid, or the icon was
  796.  * found in the cache. In either case, calling write or close would
  797.  * be an error.
  798.  *
  799.  * @param conv The conversation to associate the smiley with.
  800.  * @param smile The text associated with the smiley
  801.  * @param cksum_type The type of checksum.
  802.  * @param chksum The checksum, as a NUL terminated base64 string.
  803.  * @param remote @c TRUE if the custom smiley is set by the remote user (buddy).
  804.  * @return      @c TRUE if an icon is expected, else FALSE. Note that
  805.  *              it is an error to never call purple_conv_custom_smiley_close if
  806.  *              this function returns @c TRUE, but an error to call it if
  807.  *              @c FALSE is returned.
  808.  */
  809.  
  810. gboolean purple_conv_custom_smiley_add(PurpleConversation *conv, const char *smile,
  811.                                       const char *cksum_type, const char *chksum,
  812.                                       gboolean remote);
  813.  
  814.  
  815. /**
  816.  * Updates the image associated with the current smiley.
  817.  *
  818.  * @param conv The conversation associated with the smiley.
  819.  * @param smile The text associated with the smiley.
  820.  * @param data The actual image data.
  821.  * @param size The length of the data.
  822.  */
  823.  
  824. void purple_conv_custom_smiley_write(PurpleConversation *conv,
  825.                                    const char *smile,
  826.                                    const guchar *data,
  827.                                    gsize size);
  828.  
  829. /**
  830.  * Close the custom smiley, all data has been written with
  831.  * purple_conv_custom_smiley_write, and it is no longer valid
  832.  * to call that function on that smiley.
  833.  *
  834.  * @param conv The purple conversation associated with the smiley.
  835.  * @param smile The text associated with the smiley
  836.  */
  837.  
  838. void purple_conv_custom_smiley_close(PurpleConversation *conv, const char *smile);
  839.  
  840. /*@}*/
  841.  
  842.  
  843. /**************************************************************************/
  844. /** @name Chat Conversation API                                           */
  845. /**************************************************************************/
  846. /*@{*/
  847.  
  848. /**
  849.  * Gets a chat's parent conversation.
  850.  *
  851.  * @param chat The chat.
  852.  *
  853.  * @return The parent conversation.
  854.  */
  855. PurpleConversation *purple_conv_chat_get_conversation(const PurpleConvChat *chat);
  856.  
  857. /**
  858.  * Sets the list of users in the chat room.
  859.  *
  860.  * @note Calling this function will not update the display of the users.
  861.  *       Please use purple_conv_chat_add_user(), purple_conv_chat_add_users(),
  862.  *       purple_conv_chat_remove_user(), and purple_conv_chat_remove_users() instead.
  863.  *
  864.  * @param chat  The chat.
  865.  * @param users The list of users.
  866.  *
  867.  * @return The list passed.
  868.  */
  869. GList *purple_conv_chat_set_users(PurpleConvChat *chat, GList *users);
  870.  
  871. /**
  872.  * Returns a list of users in the chat room.
  873.  *
  874.  * @param chat The chat.
  875.  *
  876.  * @return The list of users.
  877.  */
  878. GList *purple_conv_chat_get_users(const PurpleConvChat *chat);
  879.  
  880. /**
  881.  * Ignores a user in a chat room.
  882.  *
  883.  * @param chat The chat.
  884.  * @param name The name of the user.
  885.  */
  886. void purple_conv_chat_ignore(PurpleConvChat *chat, const char *name);
  887.  
  888. /**
  889.  * Unignores a user in a chat room.
  890.  *
  891.  * @param chat The chat.
  892.  * @param name The name of the user.
  893.  */
  894. void purple_conv_chat_unignore(PurpleConvChat *chat, const char *name);
  895.  
  896. /**
  897.  * Sets the list of ignored users in the chat room.
  898.  *
  899.  * @param chat    The chat.
  900.  * @param ignored The list of ignored users.
  901.  *
  902.  * @return The list passed.
  903.  */
  904. GList *purple_conv_chat_set_ignored(PurpleConvChat *chat, GList *ignored);
  905.  
  906. /**
  907.  * Returns the list of ignored users in the chat room.
  908.  *
  909.  * @param chat The chat.
  910.  *
  911.  * @return The list of ignored users.
  912.  */
  913. GList *purple_conv_chat_get_ignored(const PurpleConvChat *chat);
  914.  
  915. /**
  916.  * Returns the actual name of the specified ignored user, if it exists in
  917.  * the ignore list.
  918.  *
  919.  * If the user found contains a prefix, such as '+' or '\@', this is also
  920.  * returned. The username passed to the function does not have to have this
  921.  * formatting.
  922.  *
  923.  * @param chat The chat.
  924.  * @param user The user to check in the ignore list.
  925.  *
  926.  * @return The ignored user if found, complete with prefixes, or @c NULL
  927.  *         if not found.
  928.  */
  929. const char *purple_conv_chat_get_ignored_user(const PurpleConvChat *chat,
  930.                                             const char *user);
  931.  
  932. /**
  933.  * Returns @c TRUE if the specified user is ignored.
  934.  *
  935.  * @param chat The chat.
  936.  * @param user The user.
  937.  *
  938.  * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise.
  939.  */
  940. gboolean purple_conv_chat_is_user_ignored(const PurpleConvChat *chat,
  941.                                         const char *user);
  942.  
  943. /**
  944.  * Sets the chat room's topic.
  945.  *
  946.  * @param chat  The chat.
  947.  * @param who   The user that set the topic.
  948.  * @param topic The topic.
  949.  */
  950. void purple_conv_chat_set_topic(PurpleConvChat *chat, const char *who,
  951.                               const char *topic);
  952.  
  953. /**
  954.  * Returns the chat room's topic.
  955.  *
  956.  * @param chat The chat.
  957.  *
  958.  * @return The chat's topic.
  959.  */
  960. const char *purple_conv_chat_get_topic(const PurpleConvChat *chat);
  961.  
  962. /**
  963.  * Sets the chat room's ID.
  964.  *
  965.  * @param chat The chat.
  966.  * @param id   The ID.
  967.  */
  968. void purple_conv_chat_set_id(PurpleConvChat *chat, int id);
  969.  
  970. /**
  971.  * Returns the chat room's ID.
  972.  *
  973.  * @param chat The chat.
  974.  *
  975.  * @return The ID.
  976.  */
  977. int purple_conv_chat_get_id(const PurpleConvChat *chat);
  978.  
  979. /**
  980.  * Writes to a chat.
  981.  *
  982.  * @param chat    The chat.
  983.  * @param who     The user who sent the message.
  984.  * @param message The message to write.
  985.  * @param flags   The flags.
  986.  * @param mtime   The time the message was sent.
  987.  */
  988. void purple_conv_chat_write(PurpleConvChat *chat, const char *who,
  989.                           const char *message, PurpleMessageFlags flags,
  990.                           time_t mtime);
  991.  
  992. /**
  993.  * Sends a message to this chat conversation.
  994.  *
  995.  * @param chat    The chat.
  996.  * @param message The message to send.
  997.  */
  998. void purple_conv_chat_send(PurpleConvChat *chat, const char *message);
  999.  
  1000. /**
  1001.  * Sends a message to this chat conversation with specified flags.
  1002.  *
  1003.  * @param chat    The chat.
  1004.  * @param message The message to send.
  1005.  * @param flags   The PurpleMessageFlags flags to use.
  1006.  */
  1007. void purple_conv_chat_send_with_flags(PurpleConvChat *chat, const char *message, PurpleMessageFlags flags);
  1008.  
  1009. /**
  1010.  * Adds a user to a chat.
  1011.  *
  1012.  * @param chat        The chat.
  1013.  * @param user        The user to add.
  1014.  * @param extra_msg   An extra message to display with the join message.
  1015.  * @param flags       The users flags
  1016.  * @param new_arrival Decides whether or not to show a join notice.
  1017.  */
  1018. void purple_conv_chat_add_user(PurpleConvChat *chat, const char *user,
  1019.                              const char *extra_msg, PurpleConvChatBuddyFlags flags,
  1020.                              gboolean new_arrival);
  1021.  
  1022. /**
  1023.  * Adds a list of users to a chat.
  1024.  *
  1025.  * The data is copied from @a users, @a extra_msgs, and @a flags, so it is up to
  1026.  * the caller to free this list after calling this function.
  1027.  *
  1028.  * @param chat         The chat.
  1029.  * @param users        The list of users to add.
  1030.  * @param extra_msgs   An extra message to display with the join message for each
  1031.  *                     user.  This list may be shorter than @a users, in which
  1032.  *                     case, the users after the end of extra_msgs will not have
  1033.  *                     an extra message.  By extension, this means that extra_msgs
  1034.  *                     can simply be @c NULL and none of the users will have an
  1035.  *                     extra message.
  1036.  * @param flags        The list of flags for each user.
  1037.  * @param new_arrivals Decides whether or not to show join notices.
  1038.  */
  1039. void purple_conv_chat_add_users(PurpleConvChat *chat, GList *users, GList *extra_msgs,
  1040.                               GList *flags, gboolean new_arrivals);
  1041.  
  1042. /**
  1043.  * Renames a user in a chat.
  1044.  *
  1045.  * @param chat     The chat.
  1046.  * @param old_user The old username.
  1047.  * @param new_user The new username.
  1048.  */
  1049. void purple_conv_chat_rename_user(PurpleConvChat *chat, const char *old_user,
  1050.                                 const char *new_user);
  1051.  
  1052. /**
  1053.  * Removes a user from a chat, optionally with a reason.
  1054.  *
  1055.  * It is up to the developer to free this list after calling this function.
  1056.  *
  1057.  * @param chat   The chat.
  1058.  * @param user   The user that is being removed.
  1059.  * @param reason The optional reason given for the removal. Can be @c NULL.
  1060.  */
  1061. void purple_conv_chat_remove_user(PurpleConvChat *chat, const char *user,
  1062.                                 const char *reason);
  1063.  
  1064. /**
  1065.  * Removes a list of users from a chat, optionally with a single reason.
  1066.  *
  1067.  * @param chat   The chat.
  1068.  * @param users  The users that are being removed.
  1069.  * @param reason The optional reason given for the removal. Can be @c NULL.
  1070.  */
  1071. void purple_conv_chat_remove_users(PurpleConvChat *chat, GList *users,
  1072.                                  const char *reason);
  1073.  
  1074. /**
  1075.  * Finds a user in a chat
  1076.  *
  1077.  * @param chat   The chat.
  1078.  * @param user   The user to look for.
  1079.  *
  1080.  * @return TRUE if the user is in the chat, FALSE if not
  1081.  */
  1082. gboolean purple_conv_chat_find_user(PurpleConvChat *chat, const char *user);
  1083.  
  1084. /**
  1085.  * Set a users flags in a chat
  1086.  *
  1087.  * @param chat   The chat.
  1088.  * @param user   The user to update.
  1089.  * @param flags  The new flags.
  1090.  */
  1091. void purple_conv_chat_user_set_flags(PurpleConvChat *chat, const char *user,
  1092.                                    PurpleConvChatBuddyFlags flags);
  1093.  
  1094. /**
  1095.  * Get the flags for a user in a chat
  1096.  *
  1097.  * @param chat   The chat.
  1098.  * @param user   The user to find the flags for
  1099.  *
  1100.  * @return The flags for the user
  1101.  */
  1102. PurpleConvChatBuddyFlags purple_conv_chat_user_get_flags(PurpleConvChat *chat,
  1103.                                                      const char *user);
  1104.  
  1105. /**
  1106.  * Clears all users from a chat.
  1107.  *
  1108.  * @param chat The chat.
  1109.  */
  1110. void purple_conv_chat_clear_users(PurpleConvChat *chat);
  1111.  
  1112. /**
  1113.  * Sets your nickname (used for hilighting) for a chat.
  1114.  *
  1115.  * @param chat The chat.
  1116.  * @param nick The nick.
  1117.  */
  1118. void purple_conv_chat_set_nick(PurpleConvChat *chat, const char *nick);
  1119.  
  1120. /**
  1121.  * Gets your nickname (used for hilighting) for a chat.
  1122.  *
  1123.  * @param chat The chat.
  1124.  * @return  The nick.
  1125.  */
  1126. const char *purple_conv_chat_get_nick(PurpleConvChat *chat);
  1127.  
  1128. /**
  1129.  * Finds a chat with the specified chat ID.
  1130.  *
  1131.  * @param gc The purple_connection.
  1132.  * @param id The chat ID.
  1133.  *
  1134.  * @return The chat conversation.
  1135.  */
  1136. PurpleConversation *purple_find_chat(const PurpleConnection *gc, int id);
  1137.  
  1138. /**
  1139.  * Lets the core know we left a chat, without destroying it.
  1140.  * Called from serv_got_chat_left().
  1141.  *
  1142.  * @param chat The chat.
  1143.  */
  1144. void purple_conv_chat_left(PurpleConvChat *chat);
  1145.  
  1146. /**
  1147.  * Returns true if we're no longer in this chat,
  1148.  * and just left the window open.
  1149.  *
  1150.  * @param chat The chat.
  1151.  *
  1152.  * @return @c TRUE if we left the chat already, @c FALSE if
  1153.  * we're still there.
  1154.  */
  1155. gboolean purple_conv_chat_has_left(PurpleConvChat *chat);
  1156.  
  1157. /**
  1158.  * Creates a new chat buddy
  1159.  *
  1160.  * @param name The name.
  1161.  * @param alias The alias.
  1162.  * @param flags The flags.
  1163.  *
  1164.  * @return The new chat buddy
  1165.  */
  1166. PurpleConvChatBuddy *purple_conv_chat_cb_new(const char *name, const char *alias,
  1167.                                         PurpleConvChatBuddyFlags flags);
  1168.  
  1169. /**
  1170.  * Find a chat buddy in a chat
  1171.  *
  1172.  * @param chat The chat.
  1173.  * @param name The name of the chat buddy to find.
  1174.  */
  1175. PurpleConvChatBuddy *purple_conv_chat_cb_find(PurpleConvChat *chat, const char *name);
  1176.  
  1177. /**
  1178.  * Get the name of a chat buddy
  1179.  *
  1180.  * @param cb    The chat buddy.
  1181.  *
  1182.  * @return The name of the chat buddy.
  1183.  */
  1184. const char *purple_conv_chat_cb_get_name(PurpleConvChatBuddy *cb);
  1185.  
  1186. /**
  1187.  * Destroys a chat buddy
  1188.  *
  1189.  * @param cb The chat buddy to destroy
  1190.  */
  1191. void purple_conv_chat_cb_destroy(PurpleConvChatBuddy *cb);
  1192.  
  1193. /*@}*/
  1194.  
  1195. /**************************************************************************/
  1196. /** @name Conversations Subsystem                                         */
  1197. /**************************************************************************/
  1198. /*@{*/
  1199.  
  1200. /**
  1201.  * Returns the conversation subsystem handle.
  1202.  *
  1203.  * @return The conversation subsystem handle.
  1204.  */
  1205. void *purple_conversations_get_handle(void);
  1206.  
  1207. /**
  1208.  * Initializes the conversation subsystem.
  1209.  */
  1210. void purple_conversations_init(void);
  1211.  
  1212. /**
  1213.  * Uninitializes the conversation subsystem.
  1214.  */
  1215. void purple_conversations_uninit(void);
  1216.  
  1217. /*@}*/
  1218.  
  1219. #ifdef __cplusplus
  1220. }
  1221. #endif
  1222.  
  1223. #endif /* _PURPLE_CONVERSATION_H_ */
  1224.