conversation.h File Reference

Conversation API. More...

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

Go to the source code of 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
typedef struct _PurpleConvIm PurpleConvIm
typedef struct _PurpleConvChat PurpleConvChat
typedef struct _PurpleConvChatBuddy PurpleConvChatBuddy
typedef struct _PurpleConvMessage PurpleConvMessage

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
}
 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
}
 Flags applicable to users in Chats. More...

Functions

IM Conversation API
PurpleConversationpurple_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.
PurpleBuddyIconpurple_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
PurpleConversationpurple_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.
PurpleConversationpurple_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.
gboolean purple_conv_chat_has_left (PurpleConvChat *chat)
 Returns true if we're no longer in this chat, and just left the window open.
PurpleConvChatBuddypurple_conv_chat_cb_new (const char *name, const char *alias, PurpleConvChatBuddyFlags flags)
 Creates a new chat buddy.
PurpleConvChatBuddypurple_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))
PurpleConversationpurple_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.
PurpleConversationUiOpspurple_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.
PurpleAccountpurple_conversation_get_account (const PurpleConversation *conv)
 Returns the specified conversation's purple_account.
PurpleConnectionpurple_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.
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.
PurpleConvImpurple_conversation_get_im_data (const PurpleConversation *conv)
 Returns the specified conversation's IM-specific data.
PurpleConvChatpurple_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.
PurpleConversationpurple_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

Data specific to Chats.

Definition at line 42 of file conversation.h.

Data for "Chat Buddies".

Definition at line 44 of file conversation.h.

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.

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.

Description of a conversation message.

Since:
2.2.0

Definition at line 46 of file conversation.h.


Enumeration Type Documentation

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.

Definition at line 135 of file conversation.h.

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.

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.

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.

Definition at line 105 of file conversation.h.

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

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.

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.

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 (maybe only MSN). 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.
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.