Conversation API. More...

#include "account.h"
#include "buddyicon.h"
#include "log.h"
#include "server.h"

Include dependency graph for conversation.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	_PurpleConversationUiOps
	Conversation operations and events. More...
struct	_PurpleConvIm
	Data specific to Instant Messages. More...
struct	_PurpleConvChat
	Data specific to Chats. More...
struct	_PurpleConvChatBuddy
	Data for "Chat Buddies". More...
struct	_PurpleConvMessage
	Description of a conversation message. More...
struct	_PurpleConversation
	A core representation of a conversation between two or more people. More...

Typedefs
typedef struct _PurpleConversationUiOps	PurpleConversationUiOps
	Data Structures.
typedef struct _PurpleConversation	PurpleConversation
	A core representation of a conversation between two or more people.
typedef struct _PurpleConvIm	PurpleConvIm
	Data specific to Instant Messages.
typedef struct _PurpleConvChat	PurpleConvChat
	Data specific to Chats.
typedef struct _PurpleConvChatBuddy	PurpleConvChatBuddy
	Data for "Chat Buddies".
typedef struct _PurpleConvMessage	PurpleConvMessage
	Description of a conversation message.

Enumerations
enum	PurpleConversationType { PURPLE_CONV_TYPE_UNKNOWN = 0, PURPLE_CONV_TYPE_IM, PURPLE_CONV_TYPE_CHAT, PURPLE_CONV_TYPE_MISC, PURPLE_CONV_TYPE_ANY }
	A type of conversation. More...
enum	PurpleConvUpdateType { PURPLE_CONV_UPDATE_ADD = 0, PURPLE_CONV_UPDATE_REMOVE, PURPLE_CONV_UPDATE_ACCOUNT, PURPLE_CONV_UPDATE_TYPING, PURPLE_CONV_UPDATE_UNSEEN, PURPLE_CONV_UPDATE_LOGGING, PURPLE_CONV_UPDATE_TOPIC, PURPLE_CONV_ACCOUNT_ONLINE, PURPLE_CONV_ACCOUNT_OFFLINE, PURPLE_CONV_UPDATE_AWAY, PURPLE_CONV_UPDATE_ICON, PURPLE_CONV_UPDATE_TITLE, PURPLE_CONV_UPDATE_CHATLEFT, PURPLE_CONV_UPDATE_FEATURES }
	Conversation update type. More...
enum	PurpleTypingState { PURPLE_NOT_TYPING = 0, PURPLE_TYPING, PURPLE_TYPED }
	The typing state of a user. More...
enum	PurpleMessageFlags { PURPLE_MESSAGE_SEND = 0x0001, PURPLE_MESSAGE_RECV = 0x0002, PURPLE_MESSAGE_SYSTEM = 0x0004, PURPLE_MESSAGE_AUTO_RESP = 0x0008, PURPLE_MESSAGE_ACTIVE_ONLY = 0x0010, PURPLE_MESSAGE_NICK = 0x0020, PURPLE_MESSAGE_NO_LOG = 0x0040, PURPLE_MESSAGE_WHISPER = 0x0080, PURPLE_MESSAGE_ERROR = 0x0200, PURPLE_MESSAGE_DELAYED = 0x0400, PURPLE_MESSAGE_RAW = 0x0800, PURPLE_MESSAGE_IMAGES = 0x1000, PURPLE_MESSAGE_NOTIFY = 0x2000, PURPLE_MESSAGE_NO_LINKIFY = 0x4000, PURPLE_MESSAGE_INVISIBLE = 0x8000, PURPLE_MESSAGE_REMOTE_SEND = 0x10000 }
	Flags applicable to a message. More...
enum	PurpleConvChatBuddyFlags { PURPLE_CBFLAGS_NONE = 0x0000, PURPLE_CBFLAGS_VOICE = 0x0001, PURPLE_CBFLAGS_HALFOP = 0x0002, PURPLE_CBFLAGS_OP = 0x0004, PURPLE_CBFLAGS_FOUNDER = 0x0008, PURPLE_CBFLAGS_TYPING = 0x0010, PURPLE_CBFLAGS_AWAY = 0x0020 }
	Flags applicable to users in Chats. More...

Functions
IM Conversation API
PurpleConversation *	purple_conv_im_get_conversation (const PurpleConvIm *im)
	Gets an IM's parent conversation.
void	purple_conv_im_set_icon (PurpleConvIm im, PurpleBuddyIcon icon)
	Sets the IM's buddy icon.
PurpleBuddyIcon *	purple_conv_im_get_icon (const PurpleConvIm *im)
	Returns the IM's buddy icon.
void	purple_conv_im_set_typing_state (PurpleConvIm *im, PurpleTypingState state)
	Sets the IM's typing state.
PurpleTypingState	purple_conv_im_get_typing_state (const PurpleConvIm *im)
	Returns the IM's typing state.
void	purple_conv_im_start_typing_timeout (PurpleConvIm *im, int timeout)
	Starts the IM's typing timeout.
void	purple_conv_im_stop_typing_timeout (PurpleConvIm *im)
	Stops the IM's typing timeout.
guint	purple_conv_im_get_typing_timeout (const PurpleConvIm *im)
	Returns the IM's typing timeout.
void	purple_conv_im_set_type_again (PurpleConvIm *im, unsigned int val)
	Sets the quiet-time when no PURPLE_TYPING messages will be sent.
time_t	purple_conv_im_get_type_again (const PurpleConvIm *im)
	Returns the time after which another PURPLE_TYPING message should be sent.
void	purple_conv_im_start_send_typed_timeout (PurpleConvIm *im)
	Starts the IM's type again timeout.
void	purple_conv_im_stop_send_typed_timeout (PurpleConvIm *im)
	Stops the IM's type again timeout.
guint	purple_conv_im_get_send_typed_timeout (const PurpleConvIm *im)
	Returns the IM's type again timeout interval.
void	purple_conv_im_update_typing (PurpleConvIm *im)
	Updates the visual typing notification for an IM conversation.
void	purple_conv_im_write (PurpleConvIm im, const char who, const char *message, PurpleMessageFlags flags, time_t mtime)
	Writes to an IM.
gboolean	purple_conv_present_error (const char who, PurpleAccount account, const char *what)
	Presents an IM-error to the user.
void	purple_conv_im_send (PurpleConvIm im, const char message)
	Sends a message to this IM conversation.
void	purple_conv_send_confirm (PurpleConversation conv, const char message)
	Sends a message to a conversation after confirming with the user.
void	purple_conv_im_send_with_flags (PurpleConvIm im, const char message, PurpleMessageFlags flags)
	Sends a message to this IM conversation with specified flags.
gboolean	purple_conv_custom_smiley_add (PurpleConversation conv, const char smile, const char cksum_type, const char chksum, gboolean remote)
	Adds a smiley to the conversation's smiley tree.
void	purple_conv_custom_smiley_write (PurpleConversation conv, const char smile, const guchar *data, gsize size)
	Updates the image associated with the current smiley.
void	purple_conv_custom_smiley_close (PurpleConversation conv, const char smile)
	Close the custom smiley, all data has been written with purple_conv_custom_smiley_write, and it is no longer valid to call that function on that smiley.
Chat Conversation API
PurpleConversation *	purple_conv_chat_get_conversation (const PurpleConvChat *chat)
	Gets a chat's parent conversation.
GList *	purple_conv_chat_set_users (PurpleConvChat chat, GList users)
	Sets the list of users in the chat room.
GList *	purple_conv_chat_get_users (const PurpleConvChat *chat)
	Returns a list of users in the chat room.
void	purple_conv_chat_ignore (PurpleConvChat chat, const char name)
	Ignores a user in a chat room.
void	purple_conv_chat_unignore (PurpleConvChat chat, const char name)
	Unignores a user in a chat room.
GList *	purple_conv_chat_set_ignored (PurpleConvChat chat, GList ignored)
	Sets the list of ignored users in the chat room.
GList *	purple_conv_chat_get_ignored (const PurpleConvChat *chat)
	Returns the list of ignored users in the chat room.
const char *	purple_conv_chat_get_ignored_user (const PurpleConvChat chat, const char user)
	Returns the actual name of the specified ignored user, if it exists in the ignore list.
gboolean	purple_conv_chat_is_user_ignored (const PurpleConvChat chat, const char user)
	Returns `TRUE` if the specified user is ignored.
void	purple_conv_chat_set_topic (PurpleConvChat chat, const char who, const char *topic)
	Sets the chat room's topic.
const char *	purple_conv_chat_get_topic (const PurpleConvChat *chat)
	Returns the chat room's topic.
void	purple_conv_chat_set_id (PurpleConvChat *chat, int id)
	Sets the chat room's ID.
int	purple_conv_chat_get_id (const PurpleConvChat *chat)
	Returns the chat room's ID.
void	purple_conv_chat_write (PurpleConvChat chat, const char who, const char *message, PurpleMessageFlags flags, time_t mtime)
	Writes to a chat.
void	purple_conv_chat_send (PurpleConvChat chat, const char message)
	Sends a message to this chat conversation.
void	purple_conv_chat_send_with_flags (PurpleConvChat chat, const char message, PurpleMessageFlags flags)
	Sends a message to this chat conversation with specified flags.
void	purple_conv_chat_add_user (PurpleConvChat chat, const char user, const char *extra_msg, PurpleConvChatBuddyFlags flags, gboolean new_arrival)
	Adds a user to a chat.
void	purple_conv_chat_add_users (PurpleConvChat chat, GList users, GList extra_msgs, GList flags, gboolean new_arrivals)
	Adds a list of users to a chat.
void	purple_conv_chat_rename_user (PurpleConvChat chat, const char old_user, const char *new_user)
	Renames a user in a chat.
void	purple_conv_chat_remove_user (PurpleConvChat chat, const char user, const char *reason)
	Removes a user from a chat, optionally with a reason.
void	purple_conv_chat_remove_users (PurpleConvChat chat, GList users, const char *reason)
	Removes a list of users from a chat, optionally with a single reason.
gboolean	purple_conv_chat_find_user (PurpleConvChat chat, const char user)
	Finds a user in a chat.
void	purple_conv_chat_user_set_flags (PurpleConvChat chat, const char user, PurpleConvChatBuddyFlags flags)
	Set a users flags in a chat.
PurpleConvChatBuddyFlags	purple_conv_chat_user_get_flags (PurpleConvChat chat, const char user)
	Get the flags for a user in a chat.
void	purple_conv_chat_clear_users (PurpleConvChat *chat)
	Clears all users from a chat.
void	purple_conv_chat_set_nick (PurpleConvChat chat, const char nick)
	Sets your nickname (used for hilighting) for a chat.
const char *	purple_conv_chat_get_nick (PurpleConvChat *chat)
	Gets your nickname (used for hilighting) for a chat.
PurpleConversation *	purple_find_chat (const PurpleConnection *gc, int id)
	Finds a chat with the specified chat ID.
void	purple_conv_chat_left (PurpleConvChat *chat)
	Lets the core know we left a chat, without destroying it.
void	purple_conv_chat_invite_user (PurpleConvChat chat, const char user, const char *message, gboolean confirm)
	Invite a user to a chat.
gboolean	purple_conv_chat_has_left (PurpleConvChat *chat)
	Returns true if we're no longer in this chat, and just left the window open.
PurpleConvChatBuddy *	purple_conv_chat_cb_new (const char name, const char alias, PurpleConvChatBuddyFlags flags)
	Creates a new chat buddy.
PurpleConvChatBuddy *	purple_conv_chat_cb_find (PurpleConvChat chat, const char name)
	Find a chat buddy in a chat.
const char *	purple_conv_chat_cb_get_name (PurpleConvChatBuddy *cb)
	Get the name of a chat buddy.
void	purple_conv_chat_cb_destroy (PurpleConvChatBuddy *cb)
	Destroys a chat buddy.
GList *	purple_conversation_get_extended_menu (PurpleConversation *conv)
	Retrieves the extended menu items for the conversation.
gboolean	purple_conversation_do_command (PurpleConversation conv, const gchar cmdline, const gchar markup, gchar *error)
	Perform a command in a conversation.
Conversations Subsystem
void *	purple_conversations_get_handle (void)
	Returns the conversation subsystem handle.
void	purple_conversations_init (void)
	Initializes the conversation subsystem.
void	purple_conversations_uninit (void)
	Uninitializes the conversation subsystem.

Conversation API
#define	PURPLE_CONV_IM(c) (purple_conversation_get_im_data(c))
#define	PURPLE_CONV_CHAT(c) (purple_conversation_get_chat_data(c))
PurpleConversation *	purple_conversation_new (PurpleConversationType type, PurpleAccount account, const char name)
	Creates a new conversation of the specified type.
void	purple_conversation_destroy (PurpleConversation *conv)
	Destroys the specified conversation and removes it from the parent window.
void	purple_conversation_present (PurpleConversation *conv)
	Present a conversation to the user.
PurpleConversationType	purple_conversation_get_type (const PurpleConversation *conv)
	Returns the specified conversation's type.
void	purple_conversation_set_ui_ops (PurpleConversation conv, PurpleConversationUiOps ops)
	Sets the specified conversation's UI operations structure.
void	purple_conversations_set_ui_ops (PurpleConversationUiOps *ops)
	Sets the default conversation UI operations structure.
PurpleConversationUiOps *	purple_conversation_get_ui_ops (const PurpleConversation *conv)
	Returns the specified conversation's UI operations structure.
void	purple_conversation_set_account (PurpleConversation conv, PurpleAccount account)
	Sets the specified conversation's purple_account.
PurpleAccount *	purple_conversation_get_account (const PurpleConversation *conv)
	Returns the specified conversation's purple_account.
PurpleConnection *	purple_conversation_get_gc (const PurpleConversation *conv)
	Returns the specified conversation's purple_connection.
void	purple_conversation_set_title (PurpleConversation conv, const char title)
	Sets the specified conversation's title.
const char *	purple_conversation_get_title (const PurpleConversation *conv)
	Returns the specified conversation's title.
void	purple_conversation_autoset_title (PurpleConversation *conv)
	Automatically sets the specified conversation's title.
void	purple_conversation_set_name (PurpleConversation conv, const char name)
	Sets the specified conversation's name.
const char *	purple_conversation_get_name (const PurpleConversation *conv)
	Returns the specified conversation's name.
const char *	purple_conv_chat_cb_get_attribute (PurpleConvChatBuddy cb, const char key)
	Get an attribute of a chat buddy.
GList *	purple_conv_chat_cb_get_attribute_keys (PurpleConvChatBuddy *cb)
	Get the keys of all atributes of a chat buddy.
void	purple_conv_chat_cb_set_attribute (PurpleConvChat chat, PurpleConvChatBuddy cb, const char key, const char value)
	Set an attribute of a chat buddy.
void	purple_conv_chat_cb_set_attributes (PurpleConvChat chat, PurpleConvChatBuddy cb, GList keys, GList values)
	Set attributes of a chat buddy.
void	purple_conversation_set_logging (PurpleConversation *conv, gboolean log)
	Enables or disables logging for this conversation.
gboolean	purple_conversation_is_logging (const PurpleConversation *conv)
	Returns whether or not logging is enabled for this conversation.
void	purple_conversation_close_logs (PurpleConversation *conv)
	Closes any open logs for this conversation.
PurpleConvIm *	purple_conversation_get_im_data (const PurpleConversation *conv)
	Returns the specified conversation's IM-specific data.
PurpleConvChat *	purple_conversation_get_chat_data (const PurpleConversation *conv)
	Returns the specified conversation's chat-specific data.
void	purple_conversation_set_data (PurpleConversation conv, const char key, gpointer data)
	Sets extra data for a conversation.
gpointer	purple_conversation_get_data (PurpleConversation conv, const char key)
	Returns extra data in a conversation.
GList *	purple_get_conversations (void)
	Returns a list of all conversations.
GList *	purple_get_ims (void)
	Returns a list of all IMs.
GList *	purple_get_chats (void)
	Returns a list of all chats.
PurpleConversation *	purple_find_conversation_with_account (PurpleConversationType type, const char name, const PurpleAccount account)
	Finds a conversation with the specified type, name, and Purple account.
void	purple_conversation_write (PurpleConversation conv, const char who, const char *message, PurpleMessageFlags flags, time_t mtime)
	Writes to a conversation window.
void	purple_conversation_set_features (PurpleConversation *conv, PurpleConnectionFlags features)
	Set the features as supported for the given conversation.
PurpleConnectionFlags	purple_conversation_get_features (PurpleConversation *conv)
	Get the features supported by the given conversation.
gboolean	purple_conversation_has_focus (PurpleConversation *conv)
	Determines if a conversation has focus.
void	purple_conversation_update (PurpleConversation *conv, PurpleConvUpdateType type)
	Updates the visual status and UI of a conversation.
void	purple_conversation_foreach (void(func)(PurpleConversation conv))
	Calls a function on each conversation.
GList *	purple_conversation_get_message_history (PurpleConversation *conv)
	Retrieve the message history of a conversation.
void	purple_conversation_clear_message_history (PurpleConversation *conv)
	Clear the message history of a conversation.
const char *	purple_conversation_message_get_sender (PurpleConvMessage *msg)
	Get the sender from a PurpleConvMessage.
const char *	purple_conversation_message_get_message (PurpleConvMessage *msg)
	Get the message from a PurpleConvMessage.
PurpleMessageFlags	purple_conversation_message_get_flags (PurpleConvMessage *msg)
	Get the message-flags of a PurpleConvMessage.
time_t	purple_conversation_message_get_timestamp (PurpleConvMessage *msg)
	Get the timestamp of a PurpleConvMessage.

Detailed Description

Conversation API.

See Also: Conversation Signals

Definition in file conversation.h.

Typedef Documentation

typedef struct _PurpleConvChat PurpleConvChat

Data specific to Chats.

Definition at line 42 of file conversation.h.

typedef struct _PurpleConvChatBuddy PurpleConvChatBuddy

Data for "Chat Buddies".

Definition at line 44 of file conversation.h.

typedef struct _PurpleConversation PurpleConversation

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

The conversation can be an IM or a chat.

Definition at line 38 of file conversation.h.

typedef struct _PurpleConversationUiOps PurpleConversationUiOps

Data Structures.

Conversation operations and events. Any UI representing a conversation must assign a filled-out PurpleConversationUiOps structure to the PurpleConversation.

Definition at line 36 of file conversation.h.

typedef struct _PurpleConvIm PurpleConvIm

Data specific to Instant Messages.

Definition at line 40 of file conversation.h.

typedef struct _PurpleConvMessage PurpleConvMessage

Description of a conversation message.

Since: 2.2.0

Definition at line 46 of file conversation.h.

Enumeration Type Documentation

enum PurpleConvChatBuddyFlags

Flags applicable to users in Chats.

Enumerator:

PURPLE_CBFLAGS_NONE	No flags.
PURPLE_CBFLAGS_VOICE	Voiced user or "Participant".
PURPLE_CBFLAGS_HALFOP	Half-op.
PURPLE_CBFLAGS_OP	Channel Op or Moderator.
PURPLE_CBFLAGS_FOUNDER	Channel Founder.
PURPLE_CBFLAGS_TYPING	Currently typing.
PURPLE_CBFLAGS_AWAY	Currently away. Since 2.8.0

Definition at line 138 of file conversation.h.

enum PurpleConversationType

A type of conversation.

Enumerator:

PURPLE_CONV_TYPE_UNKNOWN	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.

Definition at line 51 of file conversation.h.

enum PurpleConvUpdateType

Conversation update type.

Enumerator:

PURPLE_CONV_UPDATE_ADD	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.
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_FEATURES	The features for a chat have changed.

Definition at line 64 of file conversation.h.

enum PurpleMessageFlags

Flags applicable to a message.

Most will have send, recv or system.

Enumerator:

PURPLE_MESSAGE_SEND	Outgoing message.
PURPLE_MESSAGE_RECV	Incoming message.
PURPLE_MESSAGE_SYSTEM	System message.
PURPLE_MESSAGE_AUTO_RESP	Auto response.
PURPLE_MESSAGE_ACTIVE_ONLY	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	Contains your nick.
PURPLE_MESSAGE_NO_LOG	Do not log.
PURPLE_MESSAGE_WHISPER	Whispered message.
PURPLE_MESSAGE_ERROR	Error message.
PURPLE_MESSAGE_DELAYED	Delayed message.
PURPLE_MESSAGE_RAW	"Raw" message - don't apply formatting
PURPLE_MESSAGE_IMAGES	Message contains images.
PURPLE_MESSAGE_NOTIFY	Message is a notification.
PURPLE_MESSAGE_NO_LINKIFY	Message should not be auto- linkified. Since 2.1.0
PURPLE_MESSAGE_INVISIBLE	Message should not be displayed.
PURPLE_MESSAGE_REMOTE_SEND	Message sent from another location, not an echo of a local one. Since 2.12.0

Definition at line 105 of file conversation.h.

enum PurpleTypingState

The typing state of a user.

Enumerator:

PURPLE_NOT_TYPING	Not typing.
PURPLE_TYPING	Currently typing.
PURPLE_TYPED	Stopped typing momentarily.

Definition at line 94 of file conversation.h.

Function Documentation

void purple_conv_chat_add_user	(	PurpleConvChat *	chat,
		const char *	user,
		const char *	extra_msg,
		PurpleConvChatBuddyFlags	flags,
		gboolean	new_arrival
	)

Adds a user to a chat.

Parameters

chat	The chat.
user	The user to add.
extra_msg	An extra message to display with the join message.
flags	The users flags
new_arrival	Decides whether or not to show a join notice.

void purple_conv_chat_add_users	(	PurpleConvChat *	chat,
		GList *	users,
		GList *	extra_msgs,
		GList *	flags,
		gboolean	new_arrivals
	)

Adds a list of users to a chat.

The data is copied from users, extra_msgs, and flags, so it is up to the caller to free this list after calling this function.

Parameters

chat	The chat.
users	The list of users to add.
extra_msgs	An extra message to display with the join message for each user. This list may be shorter than users, in which case, the users after the end of extra_msgs will not have an extra message. By extension, this means that extra_msgs can simply be `NULL` and none of the users will have an extra message.
flags	The list of flags for each user.
new_arrivals	Decides whether or not to show join notices.

void purple_conv_chat_cb_destroy ( PurpleConvChatBuddy * cb )

Destroys a chat buddy.

Parameters

cb	The chat buddy to destroy

PurpleConvChatBuddy* purple_conv_chat_cb_find	(	PurpleConvChat *	chat,
		const char *	name
	)

Find a chat buddy in a chat.

Parameters

chat	The chat.
name	The name of the chat buddy to find.

const char* purple_conv_chat_cb_get_attribute	(	PurpleConvChatBuddy *	cb,
		const char *	key
	)

Get an attribute of a chat buddy.

Parameters

cb	The chat buddy.
key	The key of the attribute.

Returns: The value of the attribute key.

GList* purple_conv_chat_cb_get_attribute_keys ( PurpleConvChatBuddy * cb )

Get the keys of all atributes of a chat buddy.

Parameters

cb	The chat buddy.

Returns: A list of the attributes of a chat buddy.

const char* purple_conv_chat_cb_get_name ( PurpleConvChatBuddy * cb )

Get the name of a chat buddy.

Parameters

cb	The chat buddy.

Returns: The name of the chat buddy.

PurpleConvChatBuddy* purple_conv_chat_cb_new	(	const char *	name,
		const char *	alias,
		PurpleConvChatBuddyFlags	flags
	)

Creates a new chat buddy.

Parameters

name	The name.
alias	The alias.
flags	The flags.

Returns: The new chat buddy

void purple_conv_chat_cb_set_attribute	(	PurpleConvChat *	chat,
		PurpleConvChatBuddy *	cb,
		const char *	key,
		const char *	value
	)

Set an attribute of a chat buddy.

Parameters

chat	The chat.
cb	The chat buddy.
key	The key of the attribute.
value	The value of the attribute.

void purple_conv_chat_cb_set_attributes	(	PurpleConvChat *	chat,
		PurpleConvChatBuddy *	cb,
		GList *	keys,
		GList *	values
	)

Set attributes of a chat buddy.

Parameters

chat	The chat.
cb	The chat buddy.
keys	A GList of the keys.
values	A GList of the values.

void purple_conv_chat_clear_users ( PurpleConvChat * chat )

Clears all users from a chat.

Parameters

chat The chat.

gboolean purple_conv_chat_find_user	(	PurpleConvChat *	chat,
		const char *	user
	)

Finds a user in a chat.

Parameters

chat	The chat.
user	The user to look for.

Returns: TRUE if the user is in the chat, FALSE if not

PurpleConversation* purple_conv_chat_get_conversation ( const PurpleConvChat * chat )

Gets a chat's parent conversation.

Parameters

chat The chat.

Returns: The parent conversation.

int purple_conv_chat_get_id ( const PurpleConvChat * chat )

Returns the chat room's ID.

Parameters

chat The chat.

Returns: The ID.

GList* purple_conv_chat_get_ignored ( const PurpleConvChat * chat )

Returns the list of ignored users in the chat room.

Parameters

chat The chat.

Note: The return value of this function must not be modified or freed.

Returns: The list of ignored users.

const char* purple_conv_chat_get_ignored_user	(	const PurpleConvChat *	chat,
		const char *	user
	)

Returns the actual name of the specified ignored user, if it exists in the ignore list.

If the user found contains a prefix, such as '+' or '@', this is also returned. The username passed to the function does not have to have this formatting.

Parameters

chat	The chat.
user	The user to check in the ignore list.

Returns: The ignored user if found, complete with prefixes, or NULL if not found.

const char* purple_conv_chat_get_nick ( PurpleConvChat * chat )

Gets your nickname (used for hilighting) for a chat.

Parameters

chat The chat.

Returns: The nick.

const char* purple_conv_chat_get_topic ( const PurpleConvChat * chat )

Returns the chat room's topic.

Parameters

chat The chat.

Returns: The chat's topic.

GList* purple_conv_chat_get_users ( const PurpleConvChat * chat )

Returns a list of users in the chat room.

The members of the list are PurpleConvChatBuddy objects.

Parameters

chat The chat.

Note: The return value of this function must not be modified or freed.

Returns: The list of users.

gboolean purple_conv_chat_has_left ( PurpleConvChat * chat )

Returns true if we're no longer in this chat, and just left the window open.

Parameters

chat The chat.

Returns: TRUE if we left the chat already, FALSE if we're still there.

void purple_conv_chat_ignore	(	PurpleConvChat *	chat,
		const char *	name
	)

Ignores a user in a chat room.

Parameters

chat	The chat.
name	The name of the user.

void purple_conv_chat_invite_user	(	PurpleConvChat *	chat,
		const char *	user,
		const char *	message,
		gboolean	confirm
	)

Invite a user to a chat.

The user will be prompted to enter the user's name or a message if one is not given.

Parameters

chat	The chat.
user	The user to invite to the chat.
message	The message to send with the invitation.
confirm	Prompt before sending the invitation. The user is always prompted if either user or message is `NULL`.

Since: 2.6.0

gboolean purple_conv_chat_is_user_ignored	(	const PurpleConvChat *	chat,
		const char *	user
	)

Returns TRUE if the specified user is ignored.

Parameters

chat	The chat.
user	The user.

Returns: TRUE if the user is in the ignore list; FALSE otherwise.

void purple_conv_chat_left ( PurpleConvChat * chat )

Lets the core know we left a chat, without destroying it.

Called from serv_got_chat_left().

Parameters

chat The chat.

void purple_conv_chat_remove_user	(	PurpleConvChat *	chat,
		const char *	user,
		const char *	reason
	)

Removes a user from a chat, optionally with a reason.

It is up to the developer to free this list after calling this function.

Parameters

chat	The chat.
user	The user that is being removed.
reason	The optional reason given for the removal. Can be `NULL`.

void purple_conv_chat_remove_users	(	PurpleConvChat *	chat,
		GList *	users,
		const char *	reason
	)

Removes a list of users from a chat, optionally with a single reason.

Parameters

chat	The chat.
users	The users that are being removed.
reason	The optional reason given for the removal. Can be `NULL`.

void purple_conv_chat_rename_user	(	PurpleConvChat *	chat,
		const char *	old_user,
		const char *	new_user
	)

Renames a user in a chat.

Parameters

chat	The chat.
old_user	The old username.
new_user	The new username.

void purple_conv_chat_send	(	PurpleConvChat *	chat,
		const char *	message
	)

Sends a message to this chat conversation.

Parameters

chat	The chat.
message	The message to send.

void purple_conv_chat_send_with_flags	(	PurpleConvChat *	chat,
		const char *	message,
		PurpleMessageFlags	flags
	)

Sends a message to this chat conversation with specified flags.

Parameters

chat	The chat.
message	The message to send.
flags	The PurpleMessageFlags flags to use.

void purple_conv_chat_set_id	(	PurpleConvChat *	chat,
		int	id
	)

Sets the chat room's ID.

Parameters

chat	The chat.
id	The ID.

GList* purple_conv_chat_set_ignored	(	PurpleConvChat *	chat,
		GList *	ignored
	)

Sets the list of ignored users in the chat room.

Parameters

chat	The chat.
ignored	The list of ignored users.

Returns: The list passed.

void purple_conv_chat_set_nick	(	PurpleConvChat *	chat,
		const char *	nick
	)

Sets your nickname (used for hilighting) for a chat.

Parameters

chat	The chat.
nick	The nick.

void purple_conv_chat_set_topic	(	PurpleConvChat *	chat,
		const char *	who,
		const char *	topic
	)

Sets the chat room's topic.

Parameters

chat	The chat.
who	The user that set the topic.
topic	The topic.

GList* purple_conv_chat_set_users	(	PurpleConvChat *	chat,
		GList *	users
	)

Sets the list of users in the chat room.

Note: Calling this function will not update the display of the users. Please use purple_conv_chat_add_user(), purple_conv_chat_add_users(), purple_conv_chat_remove_user(), and purple_conv_chat_remove_users() instead.

Parameters

chat	The chat.
users	The list of users.

Returns: The list passed.

Deprecated:: This function will be removed in 3.0.0. You shouldn't be using it anyway.

void purple_conv_chat_unignore	(	PurpleConvChat *	chat,
		const char *	name
	)

Unignores a user in a chat room.

Parameters

chat	The chat.
name	The name of the user.

PurpleConvChatBuddyFlags purple_conv_chat_user_get_flags	(	PurpleConvChat *	chat,
		const char *	user
	)

Get the flags for a user in a chat.

Parameters

chat	The chat.
user	The user to find the flags for

Returns: The flags for the user

void purple_conv_chat_user_set_flags	(	PurpleConvChat *	chat,
		const char *	user,
		PurpleConvChatBuddyFlags	flags
	)

Set a users flags in a chat.

Parameters

chat	The chat.
user	The user to update.
flags	The new flags.

void purple_conv_chat_write	(	PurpleConvChat *	chat,
		const char *	who,
		const char *	message,
		PurpleMessageFlags	flags,
		time_t	mtime
	)

Writes to a chat.

Parameters

chat	The chat.
who	The user who sent the message.
message	The message to write.
flags	The flags.
mtime	The time the message was sent.

gboolean purple_conv_custom_smiley_add	(	PurpleConversation *	conv,
		const char *	smile,
		const char *	cksum_type,
		const char *	chksum,
		gboolean	remote
	)

Adds a smiley to the conversation's smiley tree.

If this returns TRUE you should call purple_conv_custom_smiley_write() one or more times, and then purple_conv_custom_smiley_close(). If this returns FALSE, either the conv or smile were invalid, or the icon was found in the cache. In either case, calling write or close would be an error.

Parameters

conv	The conversation to associate the smiley with.
smile	The text associated with the smiley
cksum_type	The type of checksum.
chksum	The checksum, as a NUL terminated base64 string.
remote	`TRUE` if the custom smiley is set by the remote user (buddy).

Returns: TRUE if an icon is expected, else FALSE. Note that it is an error to never call purple_conv_custom_smiley_close if this function returns TRUE, but an error to call it if FALSE is returned.

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

Close the custom smiley, all data has been written with purple_conv_custom_smiley_write, and it is no longer valid to call that function on that smiley.

Parameters

conv	The purple conversation associated with the smiley.
smile	The text associated with the smiley

void purple_conv_custom_smiley_write	(	PurpleConversation *	conv,
		const char *	smile,
		const guchar *	data,
		gsize	size
	)

Updates the image associated with the current smiley.

Parameters

conv	The conversation associated with the smiley.
smile	The text associated with the smiley.
data	The actual image data.
size	The length of the data.

PurpleConversation* purple_conv_im_get_conversation ( const PurpleConvIm * im )

Gets an IM's parent conversation.

Parameters

im The IM.

Returns: The parent conversation.

PurpleBuddyIcon* purple_conv_im_get_icon ( const PurpleConvIm * im )

Returns the IM's buddy icon.

Parameters

im The IM.

Returns: The buddy icon.

guint purple_conv_im_get_send_typed_timeout ( const PurpleConvIm * im )

Returns the IM's type again timeout interval.

Parameters

im The IM.

Returns: The type again timeout interval.

time_t purple_conv_im_get_type_again ( const PurpleConvIm * im )

Returns the time after which another PURPLE_TYPING message should be sent.

Parameters

im The IM.

Returns: The time in seconds since the epoch. Or 0 if no additional PURPLE_TYPING message should be sent.

PurpleTypingState purple_conv_im_get_typing_state ( const PurpleConvIm * im )

Returns the IM's typing state.

Parameters

im The IM.

Returns: The IM's typing state.

guint purple_conv_im_get_typing_timeout ( const PurpleConvIm * im )

Returns the IM's typing timeout.

Parameters

im The IM.

Returns: The timeout.

void purple_conv_im_send	(	PurpleConvIm *	im,
		const char *	message
	)

Sends a message to this IM conversation.

Parameters

im	The IM.
message	The message to send.

void purple_conv_im_send_with_flags	(	PurpleConvIm *	im,
		const char *	message,
		PurpleMessageFlags	flags
	)

Sends a message to this IM conversation with specified flags.

Parameters

im	The IM.
message	The message to send.
flags	The PurpleMessageFlags flags to use in addition to PURPLE_MESSAGE_SEND.

void purple_conv_im_set_icon	(	PurpleConvIm *	im,
		PurpleBuddyIcon *	icon
	)

Sets the IM's buddy icon.

This should only be called from within Purple. You probably want to call purple_buddy_icon_set_data().

Parameters

im	The IM.
icon	The buddy icon.

See Also: purple_buddy_icon_set_data()

void purple_conv_im_set_type_again	(	PurpleConvIm *	im,
		unsigned int	val
	)

Sets the quiet-time when no PURPLE_TYPING messages will be sent.

Few protocols need this. If the user is still typing after this quiet-period, then another PURPLE_TYPING message will be sent.

Parameters

im	The IM.
val	The number of seconds to wait before allowing another PURPLE_TYPING message to be sent to the user. Or 0 to not send another PURPLE_TYPING message.

void purple_conv_im_set_typing_state	(	PurpleConvIm *	im,
		PurpleTypingState	state
	)

Sets the IM's typing state.

Parameters

im	The IM.
state	The typing state.

void purple_conv_im_start_send_typed_timeout ( PurpleConvIm * im )

Starts the IM's type again timeout.

Parameters

im The IM.

void purple_conv_im_start_typing_timeout	(	PurpleConvIm *	im,
		int	timeout
	)

Starts the IM's typing timeout.

Parameters

im	The IM.
timeout	The timeout.

void purple_conv_im_stop_send_typed_timeout ( PurpleConvIm * im )

Stops the IM's type again timeout.

Parameters

im The IM.

void purple_conv_im_stop_typing_timeout ( PurpleConvIm * im )

Stops the IM's typing timeout.

Parameters

im The IM.

void purple_conv_im_update_typing ( PurpleConvIm * im )

Updates the visual typing notification for an IM conversation.

Parameters

im The IM.

void purple_conv_im_write	(	PurpleConvIm *	im,
		const char *	who,
		const char *	message,
		PurpleMessageFlags	flags,
		time_t	mtime
	)

Writes to an IM.

Parameters

im	The IM.
who	The user who sent the message.
message	The message to write.
flags	The message flags.
mtime	The time the message was sent.

gboolean purple_conv_present_error	(	const char *	who,
		PurpleAccount *	account,
		const char *	what
	)

Presents an IM-error to the user.

This is a helper function to find a conversation, write an error to it, and raise the window. If a conversation with this user doesn't already exist, the function will return FALSE and the calling function can attempt to present the error another way (purple_notify_error, most likely)

Parameters

who	The user this error is about
account	The account this error is on
what	The error

Returns: TRUE if the error was presented, else FALSE

void purple_conv_send_confirm	(	PurpleConversation *	conv,
		const char *	message
	)

Sends a message to a conversation after confirming with the user.

This function is intended for use in cases where the user hasn't explicitly and knowingly caused a message to be sent. The confirmation ensures that the user isn't sending a message by mistake.

Parameters

conv	The conversation.
message	The message to send.

void purple_conversation_autoset_title ( 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.

Parameters

conv	The conversation.

void purple_conversation_clear_message_history ( PurpleConversation * conv )

Clear the message history of a conversation.

Parameters

conv	The conversation

Since: 2.2.0

void purple_conversation_close_logs ( 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().

Parameters

conv	The conversation.

void purple_conversation_destroy ( PurpleConversation * conv )

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.

Parameters

conv	The conversation to destroy.

gboolean purple_conversation_do_command	(	PurpleConversation *	conv,
		const gchar *	cmdline,
		const gchar *	markup,
		gchar **	error
	)

Perform a command in a conversation.

Similar to

See Also: purple_cmd_do_command

Parameters

conv	The conversation.
cmdline	The entire command including the arguments.
markup	`NULL`, or the formatted command line.
error	If the command failed errormsg is filled in with the appropriate error message, if not `NULL`. It must be freed by the caller with g_free().

Returns: TRUE if the command was executed successfully, FALSE otherwise.

Since: 2.1.0

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

Calls a function on each conversation.

Parameters

func	The function.

PurpleAccount* purple_conversation_get_account ( const PurpleConversation * conv )

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.

Parameters

conv	The conversation.

Returns: The conversation's purple_account.

PurpleConvChat* purple_conversation_get_chat_data ( const PurpleConversation * conv )

Returns the specified conversation's chat-specific data.

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

Parameters

conv	The conversation.

Returns: The chat-specific data.

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

Returns extra data in a conversation.

Parameters

conv	The conversation.
key	The unqiue key.

Returns: The data associated with the key.

GList* purple_conversation_get_extended_menu ( PurpleConversation * conv )

Retrieves the extended menu items for the conversation.

Parameters

conv	The conversation.

Returns: A list of PurpleMenuAction items, harvested by the chat-extended-menu signal. The list and the menuaction items should be freed by the caller.

Since: 2.1.0

PurpleConnectionFlags purple_conversation_get_features ( PurpleConversation * conv )

Get the features supported by the given conversation.

Parameters

conv	The conversation

PurpleConnection* purple_conversation_get_gc ( const PurpleConversation * conv )

Returns the specified conversation's purple_connection.

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

Parameters

conv	The conversation.

Returns: The conversation's purple_connection.

PurpleConvIm* purple_conversation_get_im_data ( const PurpleConversation * conv )

Returns the specified conversation's IM-specific data.

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

Parameters

conv	The conversation.

Returns: The IM-specific data.

GList* purple_conversation_get_message_history ( PurpleConversation * conv )

Retrieve the message history of a conversation.

Parameters

conv	The conversation

Returns: 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

const char* purple_conversation_get_name ( const PurpleConversation * conv )

Returns the specified conversation's name.

Parameters

conv	The conversation.

Returns: 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_title ( const PurpleConversation * conv )

Returns the specified conversation's title.

Parameters

conv	The conversation.

Returns: The title.

PurpleConversationType purple_conversation_get_type ( const PurpleConversation * conv )

Returns the specified conversation's type.

Parameters

conv	The conversation.

Returns: The conversation's type.

PurpleConversationUiOps* purple_conversation_get_ui_ops ( const PurpleConversation * conv )

Returns the specified conversation's UI operations structure.

Parameters

conv	The conversation.

Returns: The operations structure.

gboolean purple_conversation_has_focus ( PurpleConversation * conv )

Determines if a conversation has focus.

Parameters

conv	The conversation.

Returns: TRUE if the conversation has focus, FALSE if it does not or the UI does not have a concept of conversation focus

gboolean purple_conversation_is_logging ( const PurpleConversation * conv )

Returns whether or not logging is enabled for this conversation.

Parameters

conv	The conversation.

Returns: TRUE if logging is enabled, or FALSE otherwise.

PurpleMessageFlags purple_conversation_message_get_flags ( PurpleConvMessage * msg )

Get the message-flags of a PurpleConvMessage.

Parameters

msg	A PurpleConvMessage

Returns: The message flags

Since: 2.2.0

const char* purple_conversation_message_get_message ( PurpleConvMessage * msg )

Get the message from a PurpleConvMessage.

Parameters

msg	A PurpleConvMessage

Returns: The name of the sender of the message

Since: 2.2.0

const char* purple_conversation_message_get_sender ( PurpleConvMessage * msg )

Get the sender from a PurpleConvMessage.

Parameters

msg	A PurpleConvMessage

Returns: The name of the sender of the message

Since: 2.2.0

time_t purple_conversation_message_get_timestamp ( PurpleConvMessage * msg )

Get the timestamp of a PurpleConvMessage.

Parameters

msg	A PurpleConvMessage

Returns: The timestamp of the message

Since: 2.2.0

PurpleConversation* purple_conversation_new	(	PurpleConversationType	type,
		PurpleAccount *	account,
		const char *	name
	)

Creates a new conversation of the specified type.

Parameters

type	The type of conversation.
account	The account opening the conversation window on the purple user's end.
name	The name of the conversation. For PURPLE_CONV_TYPE_IM, this is the name of the buddy.

Returns: The new conversation.

void purple_conversation_present ( PurpleConversation * conv )

Present a conversation to the user.

This allows core code to initiate a conversation by displaying the IM dialog.

Parameters

conv	The conversation to present

void purple_conversation_set_account	(	PurpleConversation *	conv,
		PurpleAccount *	account
	)

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.

Parameters

conv	The conversation.
account	The purple_account.

void purple_conversation_set_data	(	PurpleConversation *	conv,
		const char *	key,
		gpointer	data
	)

Sets extra data for a conversation.

Parameters

conv	The conversation.
key	The unique key.
data	The data to assign.

void purple_conversation_set_features	(	PurpleConversation *	conv,
		PurpleConnectionFlags	features
	)

Set the features as supported for the given conversation.

Parameters

conv	The conversation
features	Bitset defining supported features

void purple_conversation_set_logging	(	PurpleConversation *	conv,
		gboolean	log
	)

Enables or disables logging for this conversation.

Parameters

conv	The conversation.
log	`TRUE` if logging should be enabled, or `FALSE` otherwise.

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

Sets the specified conversation's name.

Parameters

conv	The conversation.
name	The conversation's name.

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

Sets the specified conversation's title.

Parameters

conv	The conversation.
title	The title.

void purple_conversation_set_ui_ops	(	PurpleConversation *	conv,
		PurpleConversationUiOps *	ops
	)

Sets the specified conversation's UI operations structure.

Parameters

conv	The conversation.
ops	The UI conversation operations structure.

void purple_conversation_update	(	PurpleConversation *	conv,
		PurpleConvUpdateType	type
	)

Updates the visual status and UI of a conversation.

Parameters

conv	The conversation.
type	The update type.

void purple_conversation_write	(	PurpleConversation *	conv,
		const char *	who,
		const char *	message,
		PurpleMessageFlags	flags,
		time_t	mtime
	)

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."

Parameters

conv	The conversation.
who	The user who sent the message.
message	The message.
flags	The message flags.
mtime	The time the message was sent.

See Also: purple_conv_im_write(); purple_conv_chat_write()

void* purple_conversations_get_handle ( void )

Returns the conversation subsystem handle.

Returns: The conversation subsystem handle.

void purple_conversations_set_ui_ops ( PurpleConversationUiOps * ops )

Sets the default conversation UI operations structure.

Parameters

ops	The UI conversation operations structure.

PurpleConversation* purple_find_chat	(	const PurpleConnection *	gc,
		int	id
	)

Finds a chat with the specified chat ID.

Parameters

gc	The purple_connection.
id	The chat ID.

Returns: The chat conversation.

PurpleConversation* purple_find_conversation_with_account	(	PurpleConversationType	type,
		const char *	name,
		const PurpleAccount *	account
	)

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

Parameters

type	The type of the conversation.
name	The name of the conversation.
account	The purple_account associated with the conversation.

Returns: The conversation if found, or NULL otherwise.

GList* purple_get_chats ( void )

Returns a list of all chats.

Note: The return value of this function must not be modified or freed.

Returns: A GList of all chats.

GList* purple_get_conversations ( void )

Returns a list of all conversations.

This list includes both IMs and chats.

Note: The return value of this function must not be modified or freed.

Returns: A GList of all conversations.

GList* purple_get_ims ( void )

Returns a list of all IMs.

Note: The return value of this function must not be modified or freed.

Returns: A GList of all IMs.

Context Navigation

Data Structures

Typedefs

Enumerations

Functions

Conversation API

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation