libpurple/conversation.h

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