/**

 * @file conversation.h Conversation API

 * @ingroup core

 * @see @ref conversation-signals

 */

/* purple

 *

 * Purple is the legal property of its developers, whose names are too numerous

 * to list here.  Please refer to the COPYRIGHT file distributed with this

 * source distribution.

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA

 */

#ifndef _PURPLE_CONVERSATION_H_

#define _PURPLE_CONVERSATION_H_

/**************************************************************************/

/** Data Structures                                                       */

/**************************************************************************/

/** @copydoc _PurpleConversationUiOps */

typedef struct _PurpleConversationUiOps PurpleConversationUiOps;

/** @copydoc _PurpleConversation */

typedef struct _PurpleConversation      PurpleConversation;

/** @copydoc _PurpleConvIm */

typedef struct _PurpleConvIm            PurpleConvIm;

/** @copydoc _PurpleConvChat */

typedef struct _PurpleConvChat          PurpleConvChat;

/** @copydoc _PurpleConvChatBuddy */

typedef struct _PurpleConvChatBuddy     PurpleConvChatBuddy;

/** @copydoc _PurpleConvMessage */

typedef struct _PurpleConvMessage       PurpleConvMessage;

/**

 * A type of conversation.

 */

typedef enum

{

	PURPLE_CONV_TYPE_UNKNOWN = 0, /**< Unknown conversation type. */

	PURPLE_CONV_TYPE_IM,          /**< Instant Message.           */

	PURPLE_CONV_TYPE_CHAT,        /**< Chat room.                 */

	PURPLE_CONV_TYPE_MISC,        /**< A misc. conversation.      */

	PURPLE_CONV_TYPE_ANY          /**< Any type of conversation.  */

} PurpleConversationType;

/**

 * Conversation update type.

 */

typedef enum

{

	PURPLE_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation

	                               was added.   */

	PURPLE_CONV_UPDATE_REMOVE,  /**< The buddy associated with the conversation

	                               was removed. */

	PURPLE_CONV_UPDATE_ACCOUNT, /**< The purple_account was changed. */

	PURPLE_CONV_UPDATE_TYPING,  /**< The typing state was updated. */

	PURPLE_CONV_UPDATE_UNSEEN,  /**< The unseen state was updated. */

	PURPLE_CONV_UPDATE_LOGGING, /**< Logging for this conversation was

	                               enabled or disabled. */

	PURPLE_CONV_UPDATE_TOPIC,   /**< The topic for a chat was updated. */

	/*

	 * XXX These need to go when we implement a more generic core/UI event

	 * system.

	 */

	PURPLE_CONV_ACCOUNT_ONLINE,  /**< One of the user's accounts went online.  */

	PURPLE_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */

	PURPLE_CONV_UPDATE_AWAY,     /**< The other user went away.                */

	PURPLE_CONV_UPDATE_ICON,     /**< The other user's buddy icon changed.     */

	PURPLE_CONV_UPDATE_TITLE,

	PURPLE_CONV_UPDATE_CHATLEFT,

	PURPLE_CONV_UPDATE_FEATURES  /**< The features for a chat have changed */

} PurpleConvUpdateType;

/**

 * The typing state of a user.

 */

typedef enum

{

	PURPLE_NOT_TYPING = 0,  /**< Not typing.                 */

	PURPLE_TYPING,          /**< Currently typing.           */

	PURPLE_TYPED            /**< Stopped typing momentarily. */

} PurpleTypingState;

/**

 * Flags applicable to a message. Most will have send, recv or system.

 */

typedef enum

{

	PURPLE_MESSAGE_SEND        = 0x0001, /**< Outgoing message.        */

	PURPLE_MESSAGE_RECV        = 0x0002, /**< Incoming message.        */

	PURPLE_MESSAGE_SYSTEM      = 0x0004, /**< System message.          */

	PURPLE_MESSAGE_AUTO_RESP   = 0x0008, /**< Auto response.           */

	PURPLE_MESSAGE_ACTIVE_ONLY = 0x0010,  /**< Hint to the UI that this

	                                        message should not be

	                                        shown in conversations

	                                        which are only open for

	                                        internal UI purposes

	                                        (e.g. for contact-aware

	                                         conversations).           */

	PURPLE_MESSAGE_NICK        = 0x0020, /**< Contains your nick.      */

	PURPLE_MESSAGE_NO_LOG      = 0x0040, /**< Do not log.              */

	PURPLE_MESSAGE_WHISPER     = 0x0080, /**< Whispered message.       */

	PURPLE_MESSAGE_ERROR       = 0x0200, /**< Error message.           */

	PURPLE_MESSAGE_DELAYED     = 0x0400, /**< Delayed message.         */

	PURPLE_MESSAGE_RAW         = 0x0800, /**< "Raw" message - don't

	                                        apply formatting         */

	PURPLE_MESSAGE_IMAGES      = 0x1000, /**< Message contains images  */

	PURPLE_MESSAGE_NOTIFY      = 0x2000, /**< Message is a notification */

	PURPLE_MESSAGE_NO_LINKIFY  = 0x4000, /**< Message should not be auto-

										   linkified @since 2.1.0 */

	PURPLE_MESSAGE_INVISIBLE   = 0x8000  /**< Message should not be displayed */

} PurpleMessageFlags;

/**

 * Flags applicable to users in Chats.

 */

typedef enum

{

	PURPLE_CBFLAGS_NONE          = 0x0000, /**< No flags                     */

	PURPLE_CBFLAGS_VOICE         = 0x0001, /**< Voiced user or "Participant" */

	PURPLE_CBFLAGS_HALFOP        = 0x0002, /**< Half-op                      */

	PURPLE_CBFLAGS_OP            = 0x0004, /**< Channel Op or Moderator      */

	PURPLE_CBFLAGS_FOUNDER       = 0x0008, /**< Channel Founder              */

	PURPLE_CBFLAGS_TYPING        = 0x0010, /**< Currently typing             */

	PURPLE_CBFLAGS_AWAY			 = 0x0020  /**< Currently away				 */

} PurpleConvChatBuddyFlags;

#include "account.h"

#include "buddyicon.h"

#include "log.h"

#include "server.h"

/**

 * Conversation operations and events.

 *

 * Any UI representing a conversation must assign a filled-out

 * PurpleConversationUiOps structure to the PurpleConversation.

 */

struct _PurpleConversationUiOps

{

	/** Called when @a conv is created (but before the @ref

	 *  conversation-created signal is emitted).

	 */

	void (*create_conversation)(PurpleConversation *conv);

	/** Called just before @a conv is freed. */

	void (*destroy_conversation)(PurpleConversation *conv);

	/** Write a message to a chat.  If this field is @c NULL, libpurple will

	 *  fall back to using #write_conv.

	 *  @see purple_conv_chat_write()

	 */

	void (*write_chat)(PurpleConversation *conv, const char *who,

	                   const char *message, PurpleMessageFlags flags,

	                   time_t mtime);

	/** Write a message to an IM conversation.  If this field is @c NULL,

	 *  libpurple will fall back to using #write_conv.

	 *  @see purple_conv_im_write()

	 */

	void (*write_im)(PurpleConversation *conv, const char *who,

	                 const char *message, PurpleMessageFlags flags,

	                 time_t mtime);

	/** Write a message to a conversation.  This is used rather than the

	 *  chat- or im-specific ops for errors, system messages (such as "x is

	 *  now know as y"), and as the fallback if #write_im and #write_chat

	 *  are not implemented.  It should be implemented, or the UI will miss

	 *  conversation error messages and your users will hate you.

	 *

	 *  @see purple_conversation_write()

	 */

	void (*write_conv)(PurpleConversation *conv,

	                   const char *name,

	                   const char *alias,

	                   const char *message,

	                   PurpleMessageFlags flags,

	                   time_t mtime);

	/** Add @a cbuddies to a chat.

	 *  @param cbuddies      A @c GList of #PurpleConvChatBuddy structs.

	 *  @param new_arrivals  Whether join notices should be shown.

	 *                       (Join notices are actually written to the

	 *                       conversation by #purple_conv_chat_add_users().)

	 */

	void (*chat_add_users)(PurpleConversation *conv,

	                       GList *cbuddies,

	                       gboolean new_arrivals);

	/** Rename the user in this chat named @a old_name to @a new_name.  (The

	 *  rename message is written to the conversation by libpurple.)

	 *  @param new_alias  @a new_name's new alias, if they have one.

	 *  @see purple_conv_chat_add_users()

	 */

	void (*chat_rename_user)(PurpleConversation *conv, const char *old_name,

	                         const char *new_name, const char *new_alias);

	/** Remove @a users from a chat.

	 *  @param users    A @c GList of <tt>const char *</tt>s.

	 *  @see purple_conv_chat_rename_user()

	 */

	void (*chat_remove_users)(PurpleConversation *conv, GList *users);

	/** Called when a user's flags are changed.

	 *  @see purple_conv_chat_user_set_flags()

	 */

	void (*chat_update_user)(PurpleConversation *conv, const char *user);

	/** Present this conversation to the user; for example, by displaying

	 *  the IM dialog.

	 */

	void (*present)(PurpleConversation *conv);

	/** If this UI has a concept of focus (as in a windowing system) and

	 *  this conversation has the focus, return @c TRUE; otherwise, return

	 *  @c FALSE.

	 */

	gboolean (*has_focus)(PurpleConversation *conv);

	/* Custom Smileys */

	gboolean (*custom_smiley_add)(PurpleConversation *conv, const char *smile, gboolean remote);

	void (*custom_smiley_write)(PurpleConversation *conv, const char *smile,

	                            const guchar *data, gsize size);

	void (*custom_smiley_close)(PurpleConversation *conv, const char *smile);

	/** Prompt the user for confirmation to send @a message.  This function

	 *  should arrange for the message to be sent if the user accepts.  If

	 *  this field is @c NULL, libpurple will fall back to using

	 *  #purple_request_action().

	 */

	void (*send_confirm)(PurpleConversation *conv, const char *message);

	void (*_purple_reserved1)(void);

	void (*_purple_reserved2)(void);

	void (*_purple_reserved3)(void);

	void (*_purple_reserved4)(void);

};

/**

 * Data specific to Instant Messages.

 */

struct _PurpleConvIm

{

	PurpleConversation *conv;            /**< The parent conversation.     */

	PurpleTypingState typing_state;      /**< The current typing state.    */

	guint  typing_timeout;             /**< The typing timer handle.     */

	time_t type_again;                 /**< The type again time.         */

	guint  send_typed_timeout;         /**< The type again timer handle. */

	PurpleBuddyIcon *icon;               /**< The buddy icon.              */

};

/**

 * Data specific to Chats.

 */

struct _PurpleConvChat

{

	PurpleConversation *conv;          /**< The parent conversation.      */

	GList *in_room;                  /**< The users in the room.        */

	GList *ignored;                  /**< Ignored users.                */

	char  *who;                      /**< The person who set the topic. */

	char  *topic;                    /**< The topic.                    */

	int    id;                       /**< The chat ID.                  */

	char *nick;                      /**< Your nick in this chat.       */

	gboolean left;                   /**< We left the chat and kept the window open */

};

/**

 * Data for "Chat Buddies"

 */

struct _PurpleConvChatBuddy

{

	char *name;                      /**< The chat participant's name in the chat. */

	char *collate_key;				 /**< A string by which this buddy can be compared with other collate keys. */

	char *alias;                     /**< The chat participant's alias, if known;

	                                  *   @a NULL otherwise.

	                                  */

	char *alias_key;                 /**< A string by which this buddy will be sorted,

	                                  *   or @c NULL if the buddy should be sorted by

	                                  *   its @c name.  (This is currently always @c

	                                  *   NULL.)

	                                  */

	gboolean buddy;                  /**< @a TRUE if this chat participant is on the

	                                  *   buddy list; @a FALSE otherwise.

	                                  */

	PurpleConvChatBuddyFlags flags;  /**< A bitwise OR of flags for this participant,

	                                  *   such as whether they are a channel operator.

	                                  */

	GHashTable *attributes;			 /**< A hash table of attributes about the user, such as

									  *   real name, user@host, etc.

									  */

};

/**

 * Description of a conversation message

 *

 * @since 2.2.0

 */

struct _PurpleConvMessage

{

	char *who;

	char *what;

	PurpleMessageFlags flags;

	time_t when;

	PurpleConversation *conv;  /**< @since 2.3.0 */

	char *alias;               /**< @since 2.3.0 */

};

/**

 * A core representation of a conversation between two or more people.

 *

 * The conversation can be an IM or a chat.

 */

struct _PurpleConversation

{

	PurpleConversationType type;  /**< The type of conversation.          */

	PurpleAccount *account;       /**< The user using this conversation.  */

	char *name;                 /**< The name of the conversation.      */

	char *title;                /**< The window title.                  */

	gboolean logging;           /**< The status of logging.             */

	GList *logs;                /**< This conversation's logs           */

	union

	{

		PurpleConvIm   *im;       /**< IM-specific data.                  */

		PurpleConvChat *chat;     /**< Chat-specific data.                */

		void *misc;             /**< Misc. data.                        */

	} u;

	PurpleConversationUiOps *ui_ops;           /**< UI-specific operations. */

	void *ui_data;                           /**< UI-specific data.       */

	GHashTable *data;                        /**< Plugin-specific data.   */

	PurpleConnectionFlags features; /**< The supported features */

	GList *message_history;         /**< Message history, as a GList of PurpleConvMessage's */

};

#ifdef __cplusplus

extern "C" {

#endif

/**************************************************************************/

/** @name Conversation API                                                */

/**************************************************************************/

/*@{*/

/**

 * Creates a new conversation of the specified type.

 *

 * @param type    The type of conversation.

 * @param account The account opening the conversation window on the purple

 *                user's end.

 * @param name    The name of the conversation.

 *

 * @return The new conversation.

 */

PurpleConversation *purple_conversation_new(PurpleConversationType type,

										PurpleAccount *account,

										const char *name);

/**

 * Destroys the specified conversation and removes it from the parent

 * window.

 *

 * If this conversation is the only one contained in the parent window,

 * that window is also destroyed.

 *

 * @param conv The conversation to destroy.

 */

void purple_conversation_destroy(PurpleConversation *conv);

/**

 * Present a conversation to the user. This allows core code to initiate a

 * conversation by displaying the IM dialog.

 * @param conv The conversation to present

 */

void purple_conversation_present(PurpleConversation *conv);

/**

 * Returns the specified conversation's type.

 *

 * @param conv The conversation.

 *

 * @return The conversation's type.

 */

PurpleConversationType purple_conversation_get_type(const PurpleConversation *conv);

/**

 * Sets the specified conversation's UI operations structure.

 *

 * @param conv The conversation.

 * @param ops  The UI conversation operations structure.

 */

void purple_conversation_set_ui_ops(PurpleConversation *conv,

								  PurpleConversationUiOps *ops);

/**

 * Sets the default conversation UI operations structure.

 *

 * @param ops  The UI conversation operations structure.

 */

void purple_conversations_set_ui_ops(PurpleConversationUiOps *ops);

/**

 * Returns the specified conversation's UI operations structure.

 *

 * @param conv The conversation.

 *

 * @return The operations structure.

 */

PurpleConversationUiOps *purple_conversation_get_ui_ops(

		const PurpleConversation *conv);

/**

 * Sets the specified conversation's purple_account.

 *

 * This purple_account represents the user using purple, not the person the user

 * is having a conversation/chat/flame with.

 *

 * @param conv The conversation.

 * @param account The purple_account.

 */

void purple_conversation_set_account(PurpleConversation *conv,

                                   PurpleAccount *account);

/**

 * Returns the specified conversation's purple_account.

 *

 * This purple_account represents the user using purple, not the person the user

 * is having a conversation/chat/flame with.

 *

 * @param conv The conversation.

 *

 * @return The conversation's purple_account.

 */

PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv);

/**

 * Returns the specified conversation's purple_connection.

 *

 * This is the same as purple_conversation_get_user(conv)->gc.

 *

 * @param conv The conversation.

 *

 * @return The conversation's purple_connection.

 */

PurpleConnection *purple_conversation_get_gc(const PurpleConversation *conv);

/**

 * Sets the specified conversation's title.

 *

 * @param conv  The conversation.

 * @param title The title.

 */

void purple_conversation_set_title(PurpleConversation *conv, const char *title);

/**

 * Returns the specified conversation's title.

 *

 * @param conv The conversation.

 *

 * @return The title.

 */

const char *purple_conversation_get_title(const PurpleConversation *conv);

/**

 * Automatically sets the specified conversation's title.

 *

 * This function takes OPT_IM_ALIAS_TAB into account, as well as the

 * user's alias.

 *

 * @param conv The conversation.

 */

void purple_conversation_autoset_title(PurpleConversation *conv);

/**

 * Sets the specified conversation's name.

 *

 * @param conv The conversation.

 * @param name The conversation's name.

 */

void purple_conversation_set_name(PurpleConversation *conv, const char *name);

/**

 * Returns the specified conversation's name.

 *

 * @param conv The conversation.

 *

 * @return The conversation's name. If the conversation is an IM with a PurpleBuddy,

 *         then it's the name of the PurpleBuddy.

 */

const char *purple_conversation_get_name(const PurpleConversation *conv);

/**

 * Enables or disables logging for this conversation.

 *

 * @param conv The conversation.

 * @param log  @c TRUE if logging should be enabled, or @c FALSE otherwise.

 */

void purple_conversation_set_logging(PurpleConversation *conv, gboolean log);

/**

 * Returns whether or not logging is enabled for this conversation.

 *

 * @param conv The conversation.

 *

 * @return @c TRUE if logging is enabled, or @c FALSE otherwise.

 */

gboolean purple_conversation_is_logging(const PurpleConversation *conv);

/**

 * Closes any open logs for this conversation.

 *

 * Note that new logs will be opened as necessary (e.g. upon receipt of a

 * message, if the conversation has logging enabled. To disable logging for

 * the remainder of the conversation, use purple_conversation_set_logging().

 *

 * @param conv The conversation.

 */

void purple_conversation_close_logs(PurpleConversation *conv);

/**

 * Returns the specified conversation's IM-specific data.

 *

 * If the conversation type is not PURPLE_CONV_TYPE_IM, this will return @c NULL.

 *

 * @param conv The conversation.

 *

 * @return The IM-specific data.

 */

PurpleConvIm *purple_conversation_get_im_data(const PurpleConversation *conv);

#define PURPLE_CONV_IM(c) (purple_conversation_get_im_data(c))

/**

 * Returns the specified conversation's chat-specific data.

 *

 * If the conversation type is not PURPLE_CONV_TYPE_CHAT, this will return @c NULL.

 *

 * @param conv The conversation.

 *

 * @return The chat-specific data.

 */

PurpleConvChat *purple_conversation_get_chat_data(const PurpleConversation *conv);

#define PURPLE_CONV_CHAT(c) (purple_conversation_get_chat_data(c))

/**

 * Sets extra data for a conversation.

 *

 * @param conv The conversation.

 * @param key  The unique key.

 * @param data The data to assign.

 */

void purple_conversation_set_data(PurpleConversation *conv, const char *key,

								gpointer data);

/**

 * Returns extra data in a conversation.

 *

 * @param conv The conversation.

 * @param key  The unqiue key.

 *

 * @return The data associated with the key.

 */

gpointer purple_conversation_get_data(PurpleConversation *conv, const char *key);

/**

 * Returns a list of all conversations.

 *

 * This list includes both IMs and chats.

 *

 * @constreturn A GList of all conversations.

 */

GList *purple_get_conversations(void);

/**

 * Returns a list of all IMs.

 *

 * @constreturn A GList of all IMs.

 */

GList *purple_get_ims(void);

/**

 * Returns a list of all chats.

 *

 * @constreturn A GList of all chats.

 */

GList *purple_get_chats(void);

/**

 * Finds a conversation with the specified type, name, and Purple account.

 *

 * @param type The type of the conversation.

 * @param name The name of the conversation.

 * @param account The purple_account associated with the conversation.

 *

 * @return The conversation if found, or @c NULL otherwise.

 */

PurpleConversation *purple_find_conversation_with_account(

		PurpleConversationType type, const char *name,

		const PurpleAccount *account);

/**

 * Writes to a conversation window.

 *

 * This function should not be used to write IM or chat messages. Use

 * purple_conv_im_write() and purple_conv_chat_write() instead. Those functions will

 * most likely call this anyway, but they may do their own formatting,

 * sound playback, etc.

 *

 * This can be used to write generic messages, such as "so and so closed

 * the conversation window."

 *

 * @param conv    The conversation.

 * @param who     The user who sent the message.

 * @param message The message.

 * @param flags   The message flags.

 * @param mtime   The time the message was sent.

 *

 * @see purple_conv_im_write()

 * @see purple_conv_chat_write()

 */

void purple_conversation_write(PurpleConversation *conv, const char *who,

		const char *message, PurpleMessageFlags flags,

		time_t mtime);

/**

	Set the features as supported for the given conversation.

	@param conv      The conversation

	@param features  Bitset defining supported features

*/

void purple_conversation_set_features(PurpleConversation *conv,

		PurpleConnectionFlags features);

/**

	Get the features supported by the given conversation.

	@param conv  The conversation

*/

PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv);

/**

 * Determines if a conversation has focus

 *

 * @param conv    The conversation.

 *

 * @return @c TRUE if the conversation has focus, @c FALSE if

 * it does not or the UI does not have a concept of conversation focus

 */

gboolean purple_conversation_has_focus(PurpleConversation *conv);

/**

 * Updates the visual status and UI of a conversation.

 *

 * @param conv The conversation.

 * @param type The update type.

 */

void purple_conversation_update(PurpleConversation *conv, PurpleConvUpdateType type);

/**

 * Calls a function on each conversation.

 *

 * @param func The function.

 */

void purple_conversation_foreach(void (*func)(PurpleConversation *conv));

/**

 * Retrieve the message history of a conversation.

 *

 * @param conv   The conversation

 *

 * @return  A GList of PurpleConvMessage's. The must not modify the list or the data within.

 *          The list contains the newest message at the beginning, and the oldest message at

 *          the end.

 *

 * @since 2.2.0

 */

GList *purple_conversation_get_message_history(PurpleConversation *conv);

/**

 * Clear the message history of a conversation.

 *

 * @param conv  The conversation

 *

 * @since 2.2.0

 */

void purple_conversation_clear_message_history(PurpleConversation *conv);

/**

 * Get the sender from a PurpleConvMessage

 *

 * @param msg   A PurpleConvMessage

 *

 * @return   The name of the sender of the message

 *

 * @since 2.2.0

 */

const char *purple_conversation_message_get_sender(PurpleConvMessage *msg);

/**

 * Get the message from a PurpleConvMessage

 *

 * @param msg   A PurpleConvMessage

 *

 * @return   The name of the sender of the message

 *

 * @since 2.2.0

 */

const char *purple_conversation_message_get_message(PurpleConvMessage *msg);

/**

 * Get the message-flags of a PurpleConvMessage

 *

 * @param msg   A PurpleConvMessage

 *

 * @return   The message flags

 *

 * @since 2.2.0

 */

PurpleMessageFlags purple_conversation_message_get_flags(PurpleConvMessage *msg);

/**

 * Get the timestamp of a PurpleConvMessage

 *

 * @param msg   A PurpleConvMessage

 *

 * @return   The timestamp of the message

 *

 * @since 2.2.0

 */

time_t purple_conversation_message_get_timestamp(PurpleConvMessage *msg);

/*@}*/

/**************************************************************************/

/** @name IM Conversation API                                             */

/**************************************************************************/

/*@{*/

/**

 * Gets an IM's parent conversation.

 *

 * @param im The IM.

 *

 * @return The parent conversation.

 */

PurpleConversation *purple_conv_im_get_conversation(const PurpleConvIm *im);

/**

 * Sets the IM's buddy icon.

 *

 * This should only be called from within Purple. You probably want to

 * call purple_buddy_icon_set_data().

 *

 * @param im   The IM.

 * @param icon The buddy icon.

 *

 * @see purple_buddy_icon_set_data()

 */

void purple_conv_im_set_icon(PurpleConvIm *im, PurpleBuddyIcon *icon);

/**

 * Returns the IM's buddy icon.

 *

 * @param im The IM.

 *