1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/conversation.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,1468 @@
1.4 +/**
1.5 + * @file conversation.h Conversation API
1.6 + * @ingroup core
1.7 + * @see @ref conversation-signals
1.8 + */
1.9 +
1.10 +/* purple
1.11 + *
1.12 + * Purple is the legal property of its developers, whose names are too numerous
1.13 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 + * source distribution.
1.15 + *
1.16 + * This program is free software; you can redistribute it and/or modify
1.17 + * it under the terms of the GNU General Public License as published by
1.18 + * the Free Software Foundation; either version 2 of the License, or
1.19 + * (at your option) any later version.
1.20 + *
1.21 + * This program is distributed in the hope that it will be useful,
1.22 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 + * GNU General Public License for more details.
1.25 + *
1.26 + * You should have received a copy of the GNU General Public License
1.27 + * along with this program; if not, write to the Free Software
1.28 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 + */
1.30 +#ifndef _PURPLE_CONVERSATION_H_
1.31 +#define _PURPLE_CONVERSATION_H_
1.32 +
1.33 +/**************************************************************************/
1.34 +/** Data Structures */
1.35 +/**************************************************************************/
1.36 +
1.37 +
1.38 +/** @copydoc _PurpleConversationUiOps */
1.39 +typedef struct _PurpleConversationUiOps PurpleConversationUiOps;
1.40 +/** @copydoc _PurpleConversation */
1.41 +typedef struct _PurpleConversation PurpleConversation;
1.42 +/** @copydoc _PurpleConvIm */
1.43 +typedef struct _PurpleConvIm PurpleConvIm;
1.44 +/** @copydoc _PurpleConvChat */
1.45 +typedef struct _PurpleConvChat PurpleConvChat;
1.46 +/** @copydoc _PurpleConvChatBuddy */
1.47 +typedef struct _PurpleConvChatBuddy PurpleConvChatBuddy;
1.48 +/** @copydoc _PurpleConvMessage */
1.49 +typedef struct _PurpleConvMessage PurpleConvMessage;
1.50 +
1.51 +/**
1.52 + * A type of conversation.
1.53 + */
1.54 +typedef enum
1.55 +{
1.56 + PURPLE_CONV_TYPE_UNKNOWN = 0, /**< Unknown conversation type. */
1.57 + PURPLE_CONV_TYPE_IM, /**< Instant Message. */
1.58 + PURPLE_CONV_TYPE_CHAT, /**< Chat room. */
1.59 + PURPLE_CONV_TYPE_MISC, /**< A misc. conversation. */
1.60 + PURPLE_CONV_TYPE_ANY /**< Any type of conversation. */
1.61 +
1.62 +} PurpleConversationType;
1.63 +
1.64 +/**
1.65 + * Conversation update type.
1.66 + */
1.67 +typedef enum
1.68 +{
1.69 + PURPLE_CONV_UPDATE_ADD = 0, /**< The buddy associated with the conversation
1.70 + was added. */
1.71 + PURPLE_CONV_UPDATE_REMOVE, /**< The buddy associated with the conversation
1.72 + was removed. */
1.73 + PURPLE_CONV_UPDATE_ACCOUNT, /**< The purple_account was changed. */
1.74 + PURPLE_CONV_UPDATE_TYPING, /**< The typing state was updated. */
1.75 + PURPLE_CONV_UPDATE_UNSEEN, /**< The unseen state was updated. */
1.76 + PURPLE_CONV_UPDATE_LOGGING, /**< Logging for this conversation was
1.77 + enabled or disabled. */
1.78 + PURPLE_CONV_UPDATE_TOPIC, /**< The topic for a chat was updated. */
1.79 + /*
1.80 + * XXX These need to go when we implement a more generic core/UI event
1.81 + * system.
1.82 + */
1.83 + PURPLE_CONV_ACCOUNT_ONLINE, /**< One of the user's accounts went online. */
1.84 + PURPLE_CONV_ACCOUNT_OFFLINE, /**< One of the user's accounts went offline. */
1.85 + PURPLE_CONV_UPDATE_AWAY, /**< The other user went away. */
1.86 + PURPLE_CONV_UPDATE_ICON, /**< The other user's buddy icon changed. */
1.87 + PURPLE_CONV_UPDATE_TITLE,
1.88 + PURPLE_CONV_UPDATE_CHATLEFT,
1.89 +
1.90 + PURPLE_CONV_UPDATE_FEATURES /**< The features for a chat have changed */
1.91 +
1.92 +} PurpleConvUpdateType;
1.93 +
1.94 +/**
1.95 + * The typing state of a user.
1.96 + */
1.97 +typedef enum
1.98 +{
1.99 + PURPLE_NOT_TYPING = 0, /**< Not typing. */
1.100 + PURPLE_TYPING, /**< Currently typing. */
1.101 + PURPLE_TYPED /**< Stopped typing momentarily. */
1.102 +
1.103 +} PurpleTypingState;
1.104 +
1.105 +/**
1.106 + * Flags applicable to a message. Most will have send, recv or system.
1.107 + */
1.108 +typedef enum
1.109 +{
1.110 + PURPLE_MESSAGE_SEND = 0x0001, /**< Outgoing message. */
1.111 + PURPLE_MESSAGE_RECV = 0x0002, /**< Incoming message. */
1.112 + PURPLE_MESSAGE_SYSTEM = 0x0004, /**< System message. */
1.113 + PURPLE_MESSAGE_AUTO_RESP = 0x0008, /**< Auto response. */
1.114 + PURPLE_MESSAGE_ACTIVE_ONLY = 0x0010, /**< Hint to the UI that this
1.115 + message should not be
1.116 + shown in conversations
1.117 + which are only open for
1.118 + internal UI purposes
1.119 + (e.g. for contact-aware
1.120 + conversations). */
1.121 + PURPLE_MESSAGE_NICK = 0x0020, /**< Contains your nick. */
1.122 + PURPLE_MESSAGE_NO_LOG = 0x0040, /**< Do not log. */
1.123 + PURPLE_MESSAGE_WHISPER = 0x0080, /**< Whispered message. */
1.124 + PURPLE_MESSAGE_ERROR = 0x0200, /**< Error message. */
1.125 + PURPLE_MESSAGE_DELAYED = 0x0400, /**< Delayed message. */
1.126 + PURPLE_MESSAGE_RAW = 0x0800, /**< "Raw" message - don't
1.127 + apply formatting */
1.128 + PURPLE_MESSAGE_IMAGES = 0x1000, /**< Message contains images */
1.129 + PURPLE_MESSAGE_NOTIFY = 0x2000, /**< Message is a notification */
1.130 + PURPLE_MESSAGE_NO_LINKIFY = 0x4000, /**< Message should not be auto-
1.131 + linkified @since 2.1.0 */
1.132 + PURPLE_MESSAGE_INVISIBLE = 0x8000 /**< Message should not be displayed */
1.133 +} PurpleMessageFlags;
1.134 +
1.135 +/**
1.136 + * Flags applicable to users in Chats.
1.137 + */
1.138 +typedef enum
1.139 +{
1.140 + PURPLE_CBFLAGS_NONE = 0x0000, /**< No flags */
1.141 + PURPLE_CBFLAGS_VOICE = 0x0001, /**< Voiced user or "Participant" */
1.142 + PURPLE_CBFLAGS_HALFOP = 0x0002, /**< Half-op */
1.143 + PURPLE_CBFLAGS_OP = 0x0004, /**< Channel Op or Moderator */
1.144 + PURPLE_CBFLAGS_FOUNDER = 0x0008, /**< Channel Founder */
1.145 + PURPLE_CBFLAGS_TYPING = 0x0010, /**< Currently typing */
1.146 + PURPLE_CBFLAGS_AWAY = 0x0020 /**< Currently away */
1.147 +} PurpleConvChatBuddyFlags;
1.148 +
1.149 +#include "account.h"
1.150 +#include "buddyicon.h"
1.151 +#include "log.h"
1.152 +#include "server.h"
1.153 +
1.154 +/**
1.155 + * Conversation operations and events.
1.156 + *
1.157 + * Any UI representing a conversation must assign a filled-out
1.158 + * PurpleConversationUiOps structure to the PurpleConversation.
1.159 + */
1.160 +struct _PurpleConversationUiOps
1.161 +{
1.162 + /** Called when @a conv is created (but before the @ref
1.163 + * conversation-created signal is emitted).
1.164 + */
1.165 + void (*create_conversation)(PurpleConversation *conv);
1.166 +
1.167 + /** Called just before @a conv is freed. */
1.168 + void (*destroy_conversation)(PurpleConversation *conv);
1.169 + /** Write a message to a chat. If this field is @c NULL, libpurple will
1.170 + * fall back to using #write_conv.
1.171 + * @see purple_conv_chat_write()
1.172 + */
1.173 + void (*write_chat)(PurpleConversation *conv, const char *who,
1.174 + const char *message, PurpleMessageFlags flags,
1.175 + time_t mtime);
1.176 + /** Write a message to an IM conversation. If this field is @c NULL,
1.177 + * libpurple will fall back to using #write_conv.
1.178 + * @see purple_conv_im_write()
1.179 + */
1.180 + void (*write_im)(PurpleConversation *conv, const char *who,
1.181 + const char *message, PurpleMessageFlags flags,
1.182 + time_t mtime);
1.183 + /** Write a message to a conversation. This is used rather than the
1.184 + * chat- or im-specific ops for errors, system messages (such as "x is
1.185 + * now know as y"), and as the fallback if #write_im and #write_chat
1.186 + * are not implemented. It should be implemented, or the UI will miss
1.187 + * conversation error messages and your users will hate you.
1.188 + *
1.189 + * @see purple_conversation_write()
1.190 + */
1.191 + void (*write_conv)(PurpleConversation *conv,
1.192 + const char *name,
1.193 + const char *alias,
1.194 + const char *message,
1.195 + PurpleMessageFlags flags,
1.196 + time_t mtime);
1.197 +
1.198 + /** Add @a cbuddies to a chat.
1.199 + * @param cbuddies A @c GList of #PurpleConvChatBuddy structs.
1.200 + * @param new_arrivals Whether join notices should be shown.
1.201 + * (Join notices are actually written to the
1.202 + * conversation by #purple_conv_chat_add_users().)
1.203 + */
1.204 + void (*chat_add_users)(PurpleConversation *conv,
1.205 + GList *cbuddies,
1.206 + gboolean new_arrivals);
1.207 + /** Rename the user in this chat named @a old_name to @a new_name. (The
1.208 + * rename message is written to the conversation by libpurple.)
1.209 + * @param new_alias @a new_name's new alias, if they have one.
1.210 + * @see purple_conv_chat_add_users()
1.211 + */
1.212 + void (*chat_rename_user)(PurpleConversation *conv, const char *old_name,
1.213 + const char *new_name, const char *new_alias);
1.214 + /** Remove @a users from a chat.
1.215 + * @param users A @c GList of <tt>const char *</tt>s.
1.216 + * @see purple_conv_chat_rename_user()
1.217 + */
1.218 + void (*chat_remove_users)(PurpleConversation *conv, GList *users);
1.219 + /** Called when a user's flags are changed.
1.220 + * @see purple_conv_chat_user_set_flags()
1.221 + */
1.222 + void (*chat_update_user)(PurpleConversation *conv, const char *user);
1.223 +
1.224 + /** Present this conversation to the user; for example, by displaying
1.225 + * the IM dialog.
1.226 + */
1.227 + void (*present)(PurpleConversation *conv);
1.228 +
1.229 + /** If this UI has a concept of focus (as in a windowing system) and
1.230 + * this conversation has the focus, return @c TRUE; otherwise, return
1.231 + * @c FALSE.
1.232 + */
1.233 + gboolean (*has_focus)(PurpleConversation *conv);
1.234 +
1.235 + /* Custom Smileys */
1.236 + gboolean (*custom_smiley_add)(PurpleConversation *conv, const char *smile, gboolean remote);
1.237 + void (*custom_smiley_write)(PurpleConversation *conv, const char *smile,
1.238 + const guchar *data, gsize size);
1.239 + void (*custom_smiley_close)(PurpleConversation *conv, const char *smile);
1.240 +
1.241 + /** Prompt the user for confirmation to send @a message. This function
1.242 + * should arrange for the message to be sent if the user accepts. If
1.243 + * this field is @c NULL, libpurple will fall back to using
1.244 + * #purple_request_action().
1.245 + */
1.246 + void (*send_confirm)(PurpleConversation *conv, const char *message);
1.247 +
1.248 + void (*_purple_reserved1)(void);
1.249 + void (*_purple_reserved2)(void);
1.250 + void (*_purple_reserved3)(void);
1.251 + void (*_purple_reserved4)(void);
1.252 +};
1.253 +
1.254 +/**
1.255 + * Data specific to Instant Messages.
1.256 + */
1.257 +struct _PurpleConvIm
1.258 +{
1.259 + PurpleConversation *conv; /**< The parent conversation. */
1.260 +
1.261 + PurpleTypingState typing_state; /**< The current typing state. */
1.262 + guint typing_timeout; /**< The typing timer handle. */
1.263 + time_t type_again; /**< The type again time. */
1.264 + guint send_typed_timeout; /**< The type again timer handle. */
1.265 +
1.266 + PurpleBuddyIcon *icon; /**< The buddy icon. */
1.267 +};
1.268 +
1.269 +/**
1.270 + * Data specific to Chats.
1.271 + */
1.272 +struct _PurpleConvChat
1.273 +{
1.274 + PurpleConversation *conv; /**< The parent conversation. */
1.275 +
1.276 + GList *in_room; /**< The users in the room. */
1.277 + GList *ignored; /**< Ignored users. */
1.278 + char *who; /**< The person who set the topic. */
1.279 + char *topic; /**< The topic. */
1.280 + int id; /**< The chat ID. */
1.281 + char *nick; /**< Your nick in this chat. */
1.282 +
1.283 + gboolean left; /**< We left the chat and kept the window open */
1.284 +};
1.285 +
1.286 +/**
1.287 + * Data for "Chat Buddies"
1.288 + */
1.289 +struct _PurpleConvChatBuddy
1.290 +{
1.291 + char *name; /**< The chat participant's name in the chat. */
1.292 + char *collate_key; /**< A string by which this buddy can be compared with other collate keys. */
1.293 + char *alias; /**< The chat participant's alias, if known;
1.294 + * @a NULL otherwise.
1.295 + */
1.296 + char *alias_key; /**< A string by which this buddy will be sorted,
1.297 + * or @c NULL if the buddy should be sorted by
1.298 + * its @c name. (This is currently always @c
1.299 + * NULL.)
1.300 + */
1.301 + gboolean buddy; /**< @a TRUE if this chat participant is on the
1.302 + * buddy list; @a FALSE otherwise.
1.303 + */
1.304 + PurpleConvChatBuddyFlags flags; /**< A bitwise OR of flags for this participant,
1.305 + * such as whether they are a channel operator.
1.306 + */
1.307 + GHashTable *attributes; /**< A hash table of attributes about the user, such as
1.308 + * real name, user@host, etc.
1.309 + */
1.310 +};
1.311 +
1.312 +/**
1.313 + * Description of a conversation message
1.314 + *
1.315 + * @since 2.2.0
1.316 + */
1.317 +struct _PurpleConvMessage
1.318 +{
1.319 + char *who;
1.320 + char *what;
1.321 + PurpleMessageFlags flags;
1.322 + time_t when;
1.323 + PurpleConversation *conv; /**< @since 2.3.0 */
1.324 + char *alias; /**< @since 2.3.0 */
1.325 +};
1.326 +
1.327 +/**
1.328 + * A core representation of a conversation between two or more people.
1.329 + *
1.330 + * The conversation can be an IM or a chat.
1.331 + */
1.332 +struct _PurpleConversation
1.333 +{
1.334 + PurpleConversationType type; /**< The type of conversation. */
1.335 +
1.336 + PurpleAccount *account; /**< The user using this conversation. */
1.337 +
1.338 +
1.339 + char *name; /**< The name of the conversation. */
1.340 + char *title; /**< The window title. */
1.341 +
1.342 + gboolean logging; /**< The status of logging. */
1.343 +
1.344 + GList *logs; /**< This conversation's logs */
1.345 +
1.346 + union
1.347 + {
1.348 + PurpleConvIm *im; /**< IM-specific data. */
1.349 + PurpleConvChat *chat; /**< Chat-specific data. */
1.350 + void *misc; /**< Misc. data. */
1.351 +
1.352 + } u;
1.353 +
1.354 + PurpleConversationUiOps *ui_ops; /**< UI-specific operations. */
1.355 + void *ui_data; /**< UI-specific data. */
1.356 +
1.357 + GHashTable *data; /**< Plugin-specific data. */
1.358 +
1.359 + PurpleConnectionFlags features; /**< The supported features */
1.360 + GList *message_history; /**< Message history, as a GList of PurpleConvMessage's */
1.361 +};
1.362 +
1.363 +#ifdef __cplusplus
1.364 +extern "C" {
1.365 +#endif
1.366 +
1.367 +/**************************************************************************/
1.368 +/** @name Conversation API */
1.369 +/**************************************************************************/
1.370 +/*@{*/
1.371 +
1.372 +/**
1.373 + * Creates a new conversation of the specified type.
1.374 + *
1.375 + * @param type The type of conversation.
1.376 + * @param account The account opening the conversation window on the purple
1.377 + * user's end.
1.378 + * @param name The name of the conversation.
1.379 + *
1.380 + * @return The new conversation.
1.381 + */
1.382 +PurpleConversation *purple_conversation_new(PurpleConversationType type,
1.383 + PurpleAccount *account,
1.384 + const char *name);
1.385 +
1.386 +/**
1.387 + * Destroys the specified conversation and removes it from the parent
1.388 + * window.
1.389 + *
1.390 + * If this conversation is the only one contained in the parent window,
1.391 + * that window is also destroyed.
1.392 + *
1.393 + * @param conv The conversation to destroy.
1.394 + */
1.395 +void purple_conversation_destroy(PurpleConversation *conv);
1.396 +
1.397 +
1.398 +/**
1.399 + * Present a conversation to the user. This allows core code to initiate a
1.400 + * conversation by displaying the IM dialog.
1.401 + * @param conv The conversation to present
1.402 + */
1.403 +void purple_conversation_present(PurpleConversation *conv);
1.404 +
1.405 +
1.406 +/**
1.407 + * Returns the specified conversation's type.
1.408 + *
1.409 + * @param conv The conversation.
1.410 + *
1.411 + * @return The conversation's type.
1.412 + */
1.413 +PurpleConversationType purple_conversation_get_type(const PurpleConversation *conv);
1.414 +
1.415 +/**
1.416 + * Sets the specified conversation's UI operations structure.
1.417 + *
1.418 + * @param conv The conversation.
1.419 + * @param ops The UI conversation operations structure.
1.420 + */
1.421 +void purple_conversation_set_ui_ops(PurpleConversation *conv,
1.422 + PurpleConversationUiOps *ops);
1.423 +
1.424 +/**
1.425 + * Sets the default conversation UI operations structure.
1.426 + *
1.427 + * @param ops The UI conversation operations structure.
1.428 + */
1.429 +void purple_conversations_set_ui_ops(PurpleConversationUiOps *ops);
1.430 +
1.431 +/**
1.432 + * Returns the specified conversation's UI operations structure.
1.433 + *
1.434 + * @param conv The conversation.
1.435 + *
1.436 + * @return The operations structure.
1.437 + */
1.438 +PurpleConversationUiOps *purple_conversation_get_ui_ops(
1.439 + const PurpleConversation *conv);
1.440 +
1.441 +/**
1.442 + * Sets the specified conversation's purple_account.
1.443 + *
1.444 + * This purple_account represents the user using purple, not the person the user
1.445 + * is having a conversation/chat/flame with.
1.446 + *
1.447 + * @param conv The conversation.
1.448 + * @param account The purple_account.
1.449 + */
1.450 +void purple_conversation_set_account(PurpleConversation *conv,
1.451 + PurpleAccount *account);
1.452 +
1.453 +/**
1.454 + * Returns the specified conversation's purple_account.
1.455 + *
1.456 + * This purple_account represents the user using purple, not the person the user
1.457 + * is having a conversation/chat/flame with.
1.458 + *
1.459 + * @param conv The conversation.
1.460 + *
1.461 + * @return The conversation's purple_account.
1.462 + */
1.463 +PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv);
1.464 +
1.465 +/**
1.466 + * Returns the specified conversation's purple_connection.
1.467 + *
1.468 + * This is the same as purple_conversation_get_user(conv)->gc.
1.469 + *
1.470 + * @param conv The conversation.
1.471 + *
1.472 + * @return The conversation's purple_connection.
1.473 + */
1.474 +PurpleConnection *purple_conversation_get_gc(const PurpleConversation *conv);
1.475 +
1.476 +/**
1.477 + * Sets the specified conversation's title.
1.478 + *
1.479 + * @param conv The conversation.
1.480 + * @param title The title.
1.481 + */
1.482 +void purple_conversation_set_title(PurpleConversation *conv, const char *title);
1.483 +
1.484 +/**
1.485 + * Returns the specified conversation's title.
1.486 + *
1.487 + * @param conv The conversation.
1.488 + *
1.489 + * @return The title.
1.490 + */
1.491 +const char *purple_conversation_get_title(const PurpleConversation *conv);
1.492 +
1.493 +/**
1.494 + * Automatically sets the specified conversation's title.
1.495 + *
1.496 + * This function takes OPT_IM_ALIAS_TAB into account, as well as the
1.497 + * user's alias.
1.498 + *
1.499 + * @param conv The conversation.
1.500 + */
1.501 +void purple_conversation_autoset_title(PurpleConversation *conv);
1.502 +
1.503 +/**
1.504 + * Sets the specified conversation's name.
1.505 + *
1.506 + * @param conv The conversation.
1.507 + * @param name The conversation's name.
1.508 + */
1.509 +void purple_conversation_set_name(PurpleConversation *conv, const char *name);
1.510 +
1.511 +/**
1.512 + * Returns the specified conversation's name.
1.513 + *
1.514 + * @param conv The conversation.
1.515 + *
1.516 + * @return The conversation's name. If the conversation is an IM with a PurpleBuddy,
1.517 + * then it's the name of the PurpleBuddy.
1.518 + */
1.519 +const char *purple_conversation_get_name(const PurpleConversation *conv);
1.520 +
1.521 +/**
1.522 + * Enables or disables logging for this conversation.
1.523 + *
1.524 + * @param conv The conversation.
1.525 + * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
1.526 + */
1.527 +void purple_conversation_set_logging(PurpleConversation *conv, gboolean log);
1.528 +
1.529 +/**
1.530 + * Returns whether or not logging is enabled for this conversation.
1.531 + *
1.532 + * @param conv The conversation.
1.533 + *
1.534 + * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
1.535 + */
1.536 +gboolean purple_conversation_is_logging(const PurpleConversation *conv);
1.537 +
1.538 +/**
1.539 + * Closes any open logs for this conversation.
1.540 + *
1.541 + * Note that new logs will be opened as necessary (e.g. upon receipt of a
1.542 + * message, if the conversation has logging enabled. To disable logging for
1.543 + * the remainder of the conversation, use purple_conversation_set_logging().
1.544 + *
1.545 + * @param conv The conversation.
1.546 + */
1.547 +void purple_conversation_close_logs(PurpleConversation *conv);
1.548 +
1.549 +/**
1.550 + * Returns the specified conversation's IM-specific data.
1.551 + *
1.552 + * If the conversation type is not PURPLE_CONV_TYPE_IM, this will return @c NULL.
1.553 + *
1.554 + * @param conv The conversation.
1.555 + *
1.556 + * @return The IM-specific data.
1.557 + */
1.558 +PurpleConvIm *purple_conversation_get_im_data(const PurpleConversation *conv);
1.559 +
1.560 +#define PURPLE_CONV_IM(c) (purple_conversation_get_im_data(c))
1.561 +
1.562 +/**
1.563 + * Returns the specified conversation's chat-specific data.
1.564 + *
1.565 + * If the conversation type is not PURPLE_CONV_TYPE_CHAT, this will return @c NULL.
1.566 + *
1.567 + * @param conv The conversation.
1.568 + *
1.569 + * @return The chat-specific data.
1.570 + */
1.571 +PurpleConvChat *purple_conversation_get_chat_data(const PurpleConversation *conv);
1.572 +
1.573 +#define PURPLE_CONV_CHAT(c) (purple_conversation_get_chat_data(c))
1.574 +
1.575 +/**
1.576 + * Sets extra data for a conversation.
1.577 + *
1.578 + * @param conv The conversation.
1.579 + * @param key The unique key.
1.580 + * @param data The data to assign.
1.581 + */
1.582 +void purple_conversation_set_data(PurpleConversation *conv, const char *key,
1.583 + gpointer data);
1.584 +
1.585 +/**
1.586 + * Returns extra data in a conversation.
1.587 + *
1.588 + * @param conv The conversation.
1.589 + * @param key The unqiue key.
1.590 + *
1.591 + * @return The data associated with the key.
1.592 + */
1.593 +gpointer purple_conversation_get_data(PurpleConversation *conv, const char *key);
1.594 +
1.595 +/**
1.596 + * Returns a list of all conversations.
1.597 + *
1.598 + * This list includes both IMs and chats.
1.599 + *
1.600 + * @constreturn A GList of all conversations.
1.601 + */
1.602 +GList *purple_get_conversations(void);
1.603 +
1.604 +/**
1.605 + * Returns a list of all IMs.
1.606 + *
1.607 + * @constreturn A GList of all IMs.
1.608 + */
1.609 +GList *purple_get_ims(void);
1.610 +
1.611 +/**
1.612 + * Returns a list of all chats.
1.613 + *
1.614 + * @constreturn A GList of all chats.
1.615 + */
1.616 +GList *purple_get_chats(void);
1.617 +
1.618 +/**
1.619 + * Finds a conversation with the specified type, name, and Purple account.
1.620 + *
1.621 + * @param type The type of the conversation.
1.622 + * @param name The name of the conversation.
1.623 + * @param account The purple_account associated with the conversation.
1.624 + *
1.625 + * @return The conversation if found, or @c NULL otherwise.
1.626 + */
1.627 +PurpleConversation *purple_find_conversation_with_account(
1.628 + PurpleConversationType type, const char *name,
1.629 + const PurpleAccount *account);
1.630 +
1.631 +/**
1.632 + * Writes to a conversation window.
1.633 + *
1.634 + * This function should not be used to write IM or chat messages. Use
1.635 + * purple_conv_im_write() and purple_conv_chat_write() instead. Those functions will
1.636 + * most likely call this anyway, but they may do their own formatting,
1.637 + * sound playback, etc.
1.638 + *
1.639 + * This can be used to write generic messages, such as "so and so closed
1.640 + * the conversation window."
1.641 + *
1.642 + * @param conv The conversation.
1.643 + * @param who The user who sent the message.
1.644 + * @param message The message.
1.645 + * @param flags The message flags.
1.646 + * @param mtime The time the message was sent.
1.647 + *
1.648 + * @see purple_conv_im_write()
1.649 + * @see purple_conv_chat_write()
1.650 + */
1.651 +void purple_conversation_write(PurpleConversation *conv, const char *who,
1.652 + const char *message, PurpleMessageFlags flags,
1.653 + time_t mtime);
1.654 +
1.655 +
1.656 +/**
1.657 + Set the features as supported for the given conversation.
1.658 + @param conv The conversation
1.659 + @param features Bitset defining supported features
1.660 +*/
1.661 +void purple_conversation_set_features(PurpleConversation *conv,
1.662 + PurpleConnectionFlags features);
1.663 +
1.664 +
1.665 +/**
1.666 + Get the features supported by the given conversation.
1.667 + @param conv The conversation
1.668 +*/
1.669 +PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv);
1.670 +
1.671 +/**
1.672 + * Determines if a conversation has focus
1.673 + *
1.674 + * @param conv The conversation.
1.675 + *
1.676 + * @return @c TRUE if the conversation has focus, @c FALSE if
1.677 + * it does not or the UI does not have a concept of conversation focus
1.678 + */
1.679 +gboolean purple_conversation_has_focus(PurpleConversation *conv);
1.680 +
1.681 +/**
1.682 + * Updates the visual status and UI of a conversation.
1.683 + *
1.684 + * @param conv The conversation.
1.685 + * @param type The update type.
1.686 + */
1.687 +void purple_conversation_update(PurpleConversation *conv, PurpleConvUpdateType type);
1.688 +
1.689 +/**
1.690 + * Calls a function on each conversation.
1.691 + *
1.692 + * @param func The function.
1.693 + */
1.694 +void purple_conversation_foreach(void (*func)(PurpleConversation *conv));
1.695 +
1.696 +/**
1.697 + * Retrieve the message history of a conversation.
1.698 + *
1.699 + * @param conv The conversation
1.700 + *
1.701 + * @return A GList of PurpleConvMessage's. The must not modify the list or the data within.
1.702 + * The list contains the newest message at the beginning, and the oldest message at
1.703 + * the end.
1.704 + *
1.705 + * @since 2.2.0
1.706 + */
1.707 +GList *purple_conversation_get_message_history(PurpleConversation *conv);
1.708 +
1.709 +/**
1.710 + * Clear the message history of a conversation.
1.711 + *
1.712 + * @param conv The conversation
1.713 + *
1.714 + * @since 2.2.0
1.715 + */
1.716 +void purple_conversation_clear_message_history(PurpleConversation *conv);
1.717 +
1.718 +/**
1.719 + * Get the sender from a PurpleConvMessage
1.720 + *
1.721 + * @param msg A PurpleConvMessage
1.722 + *
1.723 + * @return The name of the sender of the message
1.724 + *
1.725 + * @since 2.2.0
1.726 + */
1.727 +const char *purple_conversation_message_get_sender(PurpleConvMessage *msg);
1.728 +
1.729 +/**
1.730 + * Get the message from a PurpleConvMessage
1.731 + *
1.732 + * @param msg A PurpleConvMessage
1.733 + *
1.734 + * @return The name of the sender of the message
1.735 + *
1.736 + * @since 2.2.0
1.737 + */
1.738 +const char *purple_conversation_message_get_message(PurpleConvMessage *msg);
1.739 +
1.740 +/**
1.741 + * Get the message-flags of a PurpleConvMessage
1.742 + *
1.743 + * @param msg A PurpleConvMessage
1.744 + *
1.745 + * @return The message flags
1.746 + *
1.747 + * @since 2.2.0
1.748 + */
1.749 +PurpleMessageFlags purple_conversation_message_get_flags(PurpleConvMessage *msg);
1.750 +
1.751 +/**
1.752 + * Get the timestamp of a PurpleConvMessage
1.753 + *
1.754 + * @param msg A PurpleConvMessage
1.755 + *
1.756 + * @return The timestamp of the message
1.757 + *
1.758 + * @since 2.2.0
1.759 + */
1.760 +time_t purple_conversation_message_get_timestamp(PurpleConvMessage *msg);
1.761 +
1.762 +/*@}*/
1.763 +
1.764 +
1.765 +/**************************************************************************/
1.766 +/** @name IM Conversation API */
1.767 +/**************************************************************************/
1.768 +/*@{*/
1.769 +
1.770 +/**
1.771 + * Gets an IM's parent conversation.
1.772 + *
1.773 + * @param im The IM.
1.774 + *
1.775 + * @return The parent conversation.
1.776 + */
1.777 +PurpleConversation *purple_conv_im_get_conversation(const PurpleConvIm *im);
1.778 +
1.779 +/**
1.780 + * Sets the IM's buddy icon.
1.781 + *
1.782 + * This should only be called from within Purple. You probably want to
1.783 + * call purple_buddy_icon_set_data().
1.784 + *
1.785 + * @param im The IM.
1.786 + * @param icon The buddy icon.
1.787 + *
1.788 + * @see purple_buddy_icon_set_data()
1.789 + */
1.790 +void purple_conv_im_set_icon(PurpleConvIm *im, PurpleBuddyIcon *icon);
1.791 +
1.792 +/**
1.793 + * Returns the IM's buddy icon.
1.794 + *
1.795 + * @param im The IM.
1.796 + *
1.797 + * @return The buddy icon.
1.798 + */
1.799 +PurpleBuddyIcon *purple_conv_im_get_icon(const PurpleConvIm *im);
1.800 +
1.801 +/**
1.802 + * Sets the IM's typing state.
1.803 + *
1.804 + * @param im The IM.
1.805 + * @param state The typing state.
1.806 + */
1.807 +void purple_conv_im_set_typing_state(PurpleConvIm *im, PurpleTypingState state);
1.808 +
1.809 +/**
1.810 + * Returns the IM's typing state.
1.811 + *
1.812 + * @param im The IM.
1.813 + *
1.814 + * @return The IM's typing state.
1.815 + */
1.816 +PurpleTypingState purple_conv_im_get_typing_state(const PurpleConvIm *im);
1.817 +
1.818 +/**
1.819 + * Starts the IM's typing timeout.
1.820 + *
1.821 + * @param im The IM.
1.822 + * @param timeout The timeout.
1.823 + */
1.824 +void purple_conv_im_start_typing_timeout(PurpleConvIm *im, int timeout);
1.825 +
1.826 +/**
1.827 + * Stops the IM's typing timeout.
1.828 + *
1.829 + * @param im The IM.
1.830 + */
1.831 +void purple_conv_im_stop_typing_timeout(PurpleConvIm *im);
1.832 +
1.833 +/**
1.834 + * Returns the IM's typing timeout.
1.835 + *
1.836 + * @param im The IM.
1.837 + *
1.838 + * @return The timeout.
1.839 + */
1.840 +guint purple_conv_im_get_typing_timeout(const PurpleConvIm *im);
1.841 +
1.842 +/**
1.843 + * Sets the quiet-time when no PURPLE_TYPING messages will be sent.
1.844 + * Few protocols need this (maybe only MSN). If the user is still
1.845 + * typing after this quiet-period, then another PURPLE_TYPING message
1.846 + * will be sent.
1.847 + *
1.848 + * @param im The IM.
1.849 + * @param val The number of seconds to wait before allowing another
1.850 + * PURPLE_TYPING message to be sent to the user. Or 0 to
1.851 + * not send another PURPLE_TYPING message.
1.852 + */
1.853 +void purple_conv_im_set_type_again(PurpleConvIm *im, unsigned int val);
1.854 +
1.855 +/**
1.856 + * Returns the time after which another PURPLE_TYPING message should be sent.
1.857 + *
1.858 + * @param im The IM.
1.859 + *
1.860 + * @return The time in seconds since the epoch. Or 0 if no additional
1.861 + * PURPLE_TYPING message should be sent.
1.862 + */
1.863 +time_t purple_conv_im_get_type_again(const PurpleConvIm *im);
1.864 +
1.865 +/**
1.866 + * Starts the IM's type again timeout.
1.867 + *
1.868 + * @param im The IM.
1.869 + */
1.870 +void purple_conv_im_start_send_typed_timeout(PurpleConvIm *im);
1.871 +
1.872 +/**
1.873 + * Stops the IM's type again timeout.
1.874 + *
1.875 + * @param im The IM.
1.876 + */
1.877 +void purple_conv_im_stop_send_typed_timeout(PurpleConvIm *im);
1.878 +
1.879 +/**
1.880 + * Returns the IM's type again timeout interval.
1.881 + *
1.882 + * @param im The IM.
1.883 + *
1.884 + * @return The type again timeout interval.
1.885 + */
1.886 +guint purple_conv_im_get_send_typed_timeout(const PurpleConvIm *im);
1.887 +
1.888 +/**
1.889 + * Updates the visual typing notification for an IM conversation.
1.890 + *
1.891 + * @param im The IM.
1.892 + */
1.893 +void purple_conv_im_update_typing(PurpleConvIm *im);
1.894 +
1.895 +/**
1.896 + * Writes to an IM.
1.897 + *
1.898 + * @param im The IM.
1.899 + * @param who The user who sent the message.
1.900 + * @param message The message to write.
1.901 + * @param flags The message flags.
1.902 + * @param mtime The time the message was sent.
1.903 + */
1.904 +void purple_conv_im_write(PurpleConvIm *im, const char *who,
1.905 + const char *message, PurpleMessageFlags flags,
1.906 + time_t mtime);
1.907 +
1.908 +/**
1.909 + * Presents an IM-error to the user
1.910 + *
1.911 + * This is a helper function to find a conversation, write an error to it, and
1.912 + * raise the window. If a conversation with this user doesn't already exist,
1.913 + * the function will return FALSE and the calling function can attempt to present
1.914 + * the error another way (purple_notify_error, most likely)
1.915 + *
1.916 + * @param who The user this error is about
1.917 + * @param account The account this error is on
1.918 + * @param what The error
1.919 + * @return TRUE if the error was presented, else FALSE
1.920 + */
1.921 +gboolean purple_conv_present_error(const char *who, PurpleAccount *account, const char *what);
1.922 +
1.923 +/**
1.924 + * Sends a message to this IM conversation.
1.925 + *
1.926 + * @param im The IM.
1.927 + * @param message The message to send.
1.928 + */
1.929 +void purple_conv_im_send(PurpleConvIm *im, const char *message);
1.930 +
1.931 +/**
1.932 + * Sends a message to a conversation after confirming with
1.933 + * the user.
1.934 + *
1.935 + * This function is intended for use in cases where the user
1.936 + * hasn't explicitly and knowingly caused a message to be sent.
1.937 + * The confirmation ensures that the user isn't sending a
1.938 + * message by mistake.
1.939 + *
1.940 + * @param conv The conversation.
1.941 + * @param message The message to send.
1.942 + */
1.943 +void purple_conv_send_confirm(PurpleConversation *conv, const char *message);
1.944 +
1.945 +/**
1.946 + * Sends a message to this IM conversation with specified flags.
1.947 + *
1.948 + * @param im The IM.
1.949 + * @param message The message to send.
1.950 + * @param flags The PurpleMessageFlags flags to use in addition to PURPLE_MESSAGE_SEND.
1.951 + */
1.952 +void purple_conv_im_send_with_flags(PurpleConvIm *im, const char *message, PurpleMessageFlags flags);
1.953 +
1.954 +/**
1.955 + * Adds a smiley to the conversation's smiley tree. If this returns
1.956 + * @c TRUE you should call purple_conv_custom_smiley_write() one or more
1.957 + * times, and then purple_conv_custom_smiley_close(). If this returns
1.958 + * @c FALSE, either the conv or smile were invalid, or the icon was
1.959 + * found in the cache. In either case, calling write or close would
1.960 + * be an error.
1.961 + *
1.962 + * @param conv The conversation to associate the smiley with.
1.963 + * @param smile The text associated with the smiley
1.964 + * @param cksum_type The type of checksum.
1.965 + * @param chksum The checksum, as a NUL terminated base64 string.
1.966 + * @param remote @c TRUE if the custom smiley is set by the remote user (buddy).
1.967 + * @return @c TRUE if an icon is expected, else FALSE. Note that
1.968 + * it is an error to never call purple_conv_custom_smiley_close if
1.969 + * this function returns @c TRUE, but an error to call it if
1.970 + * @c FALSE is returned.
1.971 + */
1.972 +
1.973 +gboolean purple_conv_custom_smiley_add(PurpleConversation *conv, const char *smile,
1.974 + const char *cksum_type, const char *chksum,
1.975 + gboolean remote);
1.976 +
1.977 +
1.978 +/**
1.979 + * Updates the image associated with the current smiley.
1.980 + *
1.981 + * @param conv The conversation associated with the smiley.
1.982 + * @param smile The text associated with the smiley.
1.983 + * @param data The actual image data.
1.984 + * @param size The length of the data.
1.985 + */
1.986 +
1.987 +void purple_conv_custom_smiley_write(PurpleConversation *conv,
1.988 + const char *smile,
1.989 + const guchar *data,
1.990 + gsize size);
1.991 +
1.992 +/**
1.993 + * Close the custom smiley, all data has been written with
1.994 + * purple_conv_custom_smiley_write, and it is no longer valid
1.995 + * to call that function on that smiley.
1.996 + *
1.997 + * @param conv The purple conversation associated with the smiley.
1.998 + * @param smile The text associated with the smiley
1.999 + */
1.1000 +
1.1001 +void purple_conv_custom_smiley_close(PurpleConversation *conv, const char *smile);
1.1002 +
1.1003 +/*@}*/
1.1004 +
1.1005 +
1.1006 +/**************************************************************************/
1.1007 +/** @name Chat Conversation API */
1.1008 +/**************************************************************************/
1.1009 +/*@{*/
1.1010 +
1.1011 +/**
1.1012 + * Gets a chat's parent conversation.
1.1013 + *
1.1014 + * @param chat The chat.
1.1015 + *
1.1016 + * @return The parent conversation.
1.1017 + */
1.1018 +PurpleConversation *purple_conv_chat_get_conversation(const PurpleConvChat *chat);
1.1019 +
1.1020 +/**
1.1021 + * Sets the list of users in the chat room.
1.1022 + *
1.1023 + * @note Calling this function will not update the display of the users.
1.1024 + * Please use purple_conv_chat_add_user(), purple_conv_chat_add_users(),
1.1025 + * purple_conv_chat_remove_user(), and purple_conv_chat_remove_users() instead.
1.1026 + *
1.1027 + * @param chat The chat.
1.1028 + * @param users The list of users.
1.1029 + *
1.1030 + * @return The list passed.
1.1031 + */
1.1032 +GList *purple_conv_chat_set_users(PurpleConvChat *chat, GList *users);
1.1033 +
1.1034 +/**
1.1035 + * Returns a list of users in the chat room.
1.1036 + *
1.1037 + * @param chat The chat.
1.1038 + *
1.1039 + * @constreturn The list of users.
1.1040 + */
1.1041 +GList *purple_conv_chat_get_users(const PurpleConvChat *chat);
1.1042 +
1.1043 +/**
1.1044 + * Ignores a user in a chat room.
1.1045 + *
1.1046 + * @param chat The chat.
1.1047 + * @param name The name of the user.
1.1048 + */
1.1049 +void purple_conv_chat_ignore(PurpleConvChat *chat, const char *name);
1.1050 +
1.1051 +/**
1.1052 + * Unignores a user in a chat room.
1.1053 + *
1.1054 + * @param chat The chat.
1.1055 + * @param name The name of the user.
1.1056 + */
1.1057 +void purple_conv_chat_unignore(PurpleConvChat *chat, const char *name);
1.1058 +
1.1059 +/**
1.1060 + * Sets the list of ignored users in the chat room.
1.1061 + *
1.1062 + * @param chat The chat.
1.1063 + * @param ignored The list of ignored users.
1.1064 + *
1.1065 + * @return The list passed.
1.1066 + */
1.1067 +GList *purple_conv_chat_set_ignored(PurpleConvChat *chat, GList *ignored);
1.1068 +
1.1069 +/**
1.1070 + * Returns the list of ignored users in the chat room.
1.1071 + *
1.1072 + * @param chat The chat.
1.1073 + *
1.1074 + * @constreturn The list of ignored users.
1.1075 + */
1.1076 +GList *purple_conv_chat_get_ignored(const PurpleConvChat *chat);
1.1077 +
1.1078 +/**
1.1079 + * Returns the actual name of the specified ignored user, if it exists in
1.1080 + * the ignore list.
1.1081 + *
1.1082 + * If the user found contains a prefix, such as '+' or '\@', this is also
1.1083 + * returned. The username passed to the function does not have to have this
1.1084 + * formatting.
1.1085 + *
1.1086 + * @param chat The chat.
1.1087 + * @param user The user to check in the ignore list.
1.1088 + *
1.1089 + * @return The ignored user if found, complete with prefixes, or @c NULL
1.1090 + * if not found.
1.1091 + */
1.1092 +const char *purple_conv_chat_get_ignored_user(const PurpleConvChat *chat,
1.1093 + const char *user);
1.1094 +
1.1095 +/**
1.1096 + * Returns @c TRUE if the specified user is ignored.
1.1097 + *
1.1098 + * @param chat The chat.
1.1099 + * @param user The user.
1.1100 + *
1.1101 + * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise.
1.1102 + */
1.1103 +gboolean purple_conv_chat_is_user_ignored(const PurpleConvChat *chat,
1.1104 + const char *user);
1.1105 +
1.1106 +/**
1.1107 + * Sets the chat room's topic.
1.1108 + *
1.1109 + * @param chat The chat.
1.1110 + * @param who The user that set the topic.
1.1111 + * @param topic The topic.
1.1112 + */
1.1113 +void purple_conv_chat_set_topic(PurpleConvChat *chat, const char *who,
1.1114 + const char *topic);
1.1115 +
1.1116 +/**
1.1117 + * Returns the chat room's topic.
1.1118 + *
1.1119 + * @param chat The chat.
1.1120 + *
1.1121 + * @return The chat's topic.
1.1122 + */
1.1123 +const char *purple_conv_chat_get_topic(const PurpleConvChat *chat);
1.1124 +
1.1125 +/**
1.1126 + * Sets the chat room's ID.
1.1127 + *
1.1128 + * @param chat The chat.
1.1129 + * @param id The ID.
1.1130 + */
1.1131 +void purple_conv_chat_set_id(PurpleConvChat *chat, int id);
1.1132 +
1.1133 +/**
1.1134 + * Returns the chat room's ID.
1.1135 + *
1.1136 + * @param chat The chat.
1.1137 + *
1.1138 + * @return The ID.
1.1139 + */
1.1140 +int purple_conv_chat_get_id(const PurpleConvChat *chat);
1.1141 +
1.1142 +/**
1.1143 + * Writes to a chat.
1.1144 + *
1.1145 + * @param chat The chat.
1.1146 + * @param who The user who sent the message.
1.1147 + * @param message The message to write.
1.1148 + * @param flags The flags.
1.1149 + * @param mtime The time the message was sent.
1.1150 + */
1.1151 +void purple_conv_chat_write(PurpleConvChat *chat, const char *who,
1.1152 + const char *message, PurpleMessageFlags flags,
1.1153 + time_t mtime);
1.1154 +
1.1155 +/**
1.1156 + * Sends a message to this chat conversation.
1.1157 + *
1.1158 + * @param chat The chat.
1.1159 + * @param message The message to send.
1.1160 + */
1.1161 +void purple_conv_chat_send(PurpleConvChat *chat, const char *message);
1.1162 +
1.1163 +/**
1.1164 + * Sends a message to this chat conversation with specified flags.
1.1165 + *
1.1166 + * @param chat The chat.
1.1167 + * @param message The message to send.
1.1168 + * @param flags The PurpleMessageFlags flags to use.
1.1169 + */
1.1170 +void purple_conv_chat_send_with_flags(PurpleConvChat *chat, const char *message, PurpleMessageFlags flags);
1.1171 +
1.1172 +/**
1.1173 + * Adds a user to a chat.
1.1174 + *
1.1175 + * @param chat The chat.
1.1176 + * @param user The user to add.
1.1177 + * @param extra_msg An extra message to display with the join message.
1.1178 + * @param flags The users flags
1.1179 + * @param new_arrival Decides whether or not to show a join notice.
1.1180 + */
1.1181 +void purple_conv_chat_add_user(PurpleConvChat *chat, const char *user,
1.1182 + const char *extra_msg, PurpleConvChatBuddyFlags flags,
1.1183 + gboolean new_arrival);
1.1184 +
1.1185 +/**
1.1186 + * Adds a list of users to a chat.
1.1187 + *
1.1188 + * The data is copied from @a users, @a extra_msgs, and @a flags, so it is up to
1.1189 + * the caller to free this list after calling this function.
1.1190 + *
1.1191 + * @param chat The chat.
1.1192 + * @param users The list of users to add.
1.1193 + * @param extra_msgs An extra message to display with the join message for each
1.1194 + * user. This list may be shorter than @a users, in which
1.1195 + * case, the users after the end of extra_msgs will not have
1.1196 + * an extra message. By extension, this means that extra_msgs
1.1197 + * can simply be @c NULL and none of the users will have an
1.1198 + * extra message.
1.1199 + * @param flags The list of flags for each user.
1.1200 + * @param new_arrivals Decides whether or not to show join notices.
1.1201 + */
1.1202 +void purple_conv_chat_add_users(PurpleConvChat *chat, GList *users, GList *extra_msgs,
1.1203 + GList *flags, gboolean new_arrivals);
1.1204 +
1.1205 +/**
1.1206 + * Renames a user in a chat.
1.1207 + *
1.1208 + * @param chat The chat.
1.1209 + * @param old_user The old username.
1.1210 + * @param new_user The new username.
1.1211 + */
1.1212 +void purple_conv_chat_rename_user(PurpleConvChat *chat, const char *old_user,
1.1213 + const char *new_user);
1.1214 +
1.1215 +/**
1.1216 + * Removes a user from a chat, optionally with a reason.
1.1217 + *
1.1218 + * It is up to the developer to free this list after calling this function.
1.1219 + *
1.1220 + * @param chat The chat.
1.1221 + * @param user The user that is being removed.
1.1222 + * @param reason The optional reason given for the removal. Can be @c NULL.
1.1223 + */
1.1224 +void purple_conv_chat_remove_user(PurpleConvChat *chat, const char *user,
1.1225 + const char *reason);
1.1226 +
1.1227 +/**
1.1228 + * Removes a list of users from a chat, optionally with a single reason.
1.1229 + *
1.1230 + * @param chat The chat.
1.1231 + * @param users The users that are being removed.
1.1232 + * @param reason The optional reason given for the removal. Can be @c NULL.
1.1233 + */
1.1234 +void purple_conv_chat_remove_users(PurpleConvChat *chat, GList *users,
1.1235 + const char *reason);
1.1236 +
1.1237 +/**
1.1238 + * Finds a user in a chat
1.1239 + *
1.1240 + * @param chat The chat.
1.1241 + * @param user The user to look for.
1.1242 + *
1.1243 + * @return TRUE if the user is in the chat, FALSE if not
1.1244 + */
1.1245 +gboolean purple_conv_chat_find_user(PurpleConvChat *chat, const char *user);
1.1246 +
1.1247 +/**
1.1248 + * Set a users flags in a chat
1.1249 + *
1.1250 + * @param chat The chat.
1.1251 + * @param user The user to update.
1.1252 + * @param flags The new flags.
1.1253 + */
1.1254 +void purple_conv_chat_user_set_flags(PurpleConvChat *chat, const char *user,
1.1255 + PurpleConvChatBuddyFlags flags);
1.1256 +
1.1257 +/**
1.1258 + * Get the flags for a user in a chat
1.1259 + *
1.1260 + * @param chat The chat.
1.1261 + * @param user The user to find the flags for
1.1262 + *
1.1263 + * @return The flags for the user
1.1264 + */
1.1265 +PurpleConvChatBuddyFlags purple_conv_chat_user_get_flags(PurpleConvChat *chat,
1.1266 + const char *user);
1.1267 +
1.1268 +/**
1.1269 + * Clears all users from a chat.
1.1270 + *
1.1271 + * @param chat The chat.
1.1272 + */
1.1273 +void purple_conv_chat_clear_users(PurpleConvChat *chat);
1.1274 +
1.1275 +/**
1.1276 + * Sets your nickname (used for hilighting) for a chat.
1.1277 + *
1.1278 + * @param chat The chat.
1.1279 + * @param nick The nick.
1.1280 + */
1.1281 +void purple_conv_chat_set_nick(PurpleConvChat *chat, const char *nick);
1.1282 +
1.1283 +/**
1.1284 + * Gets your nickname (used for hilighting) for a chat.
1.1285 + *
1.1286 + * @param chat The chat.
1.1287 + * @return The nick.
1.1288 + */
1.1289 +const char *purple_conv_chat_get_nick(PurpleConvChat *chat);
1.1290 +
1.1291 +/**
1.1292 + * Finds a chat with the specified chat ID.
1.1293 + *
1.1294 + * @param gc The purple_connection.
1.1295 + * @param id The chat ID.
1.1296 + *
1.1297 + * @return The chat conversation.
1.1298 + */
1.1299 +PurpleConversation *purple_find_chat(const PurpleConnection *gc, int id);
1.1300 +
1.1301 +/**
1.1302 + * Lets the core know we left a chat, without destroying it.
1.1303 + * Called from serv_got_chat_left().
1.1304 + *
1.1305 + * @param chat The chat.
1.1306 + */
1.1307 +void purple_conv_chat_left(PurpleConvChat *chat);
1.1308 +
1.1309 +/**
1.1310 + * Invite a user to a chat.
1.1311 + * The user will be prompted to enter the user's name or a message if one is
1.1312 + * not given.
1.1313 + *
1.1314 + * @param chat The chat.
1.1315 + * @param user The user to invite to the chat.
1.1316 + * @param message The message to send with the invitation.
1.1317 + * @param confirm Prompt before sending the invitation. The user is always
1.1318 + * prompted if either #user or #message is @c NULL.
1.1319 + *
1.1320 + * @since 2.6.0
1.1321 + */
1.1322 +void purple_conv_chat_invite_user(PurpleConvChat *chat, const char *user,
1.1323 + const char *message, gboolean confirm);
1.1324 +
1.1325 +/**
1.1326 + * Returns true if we're no longer in this chat,
1.1327 + * and just left the window open.
1.1328 + *
1.1329 + * @param chat The chat.
1.1330 + *
1.1331 + * @return @c TRUE if we left the chat already, @c FALSE if
1.1332 + * we're still there.
1.1333 + */
1.1334 +gboolean purple_conv_chat_has_left(PurpleConvChat *chat);
1.1335 +
1.1336 +/**
1.1337 + * Creates a new chat buddy
1.1338 + *
1.1339 + * @param name The name.
1.1340 + * @param alias The alias.
1.1341 + * @param flags The flags.
1.1342 + *
1.1343 + * @return The new chat buddy
1.1344 + */
1.1345 +PurpleConvChatBuddy *purple_conv_chat_cb_new(const char *name, const char *alias,
1.1346 + PurpleConvChatBuddyFlags flags);
1.1347 +
1.1348 +/**
1.1349 + * Find a chat buddy in a chat
1.1350 + *
1.1351 + * @param chat The chat.
1.1352 + * @param name The name of the chat buddy to find.
1.1353 + */
1.1354 +PurpleConvChatBuddy *purple_conv_chat_cb_find(PurpleConvChat *chat, const char *name);
1.1355 +
1.1356 +/**
1.1357 + * Get the name of a chat buddy
1.1358 + *
1.1359 + * @param cb The chat buddy.
1.1360 + *
1.1361 + * @return The name of the chat buddy.
1.1362 + */
1.1363 +const char *purple_conv_chat_cb_get_name(PurpleConvChatBuddy *cb);
1.1364 +
1.1365 +/**
1.1366 + * Get an attribute of a chat buddy
1.1367 + *
1.1368 + * @param cb The chat buddy.
1.1369 + * @param key The key of the attribute.
1.1370 + *
1.1371 + * @return The value of the attribute key.
1.1372 + */
1.1373 +const char *purple_conv_chat_cb_get_attribute(PurpleConvChatBuddy *cb, const char *key);
1.1374 +
1.1375 +/**
1.1376 + * Get the keys of all atributes of a chat buddy
1.1377 + *
1.1378 + * @param cb The chat buddy.
1.1379 + *
1.1380 + * @return A list of the attributes of a chat buddy.
1.1381 + */
1.1382 +GList *purple_conv_chat_cb_get_attribute_keys(PurpleConvChatBuddy *cb);
1.1383 +
1.1384 +/**
1.1385 + * Set an attribute of a chat buddy
1.1386 + *
1.1387 + * @param chat The chat.
1.1388 + * @param cb The chat buddy.
1.1389 + * @param key The key of the attribute.
1.1390 + * @param value The value of the attribute.
1.1391 + */
1.1392 +void purple_conv_chat_cb_set_attribute(PurpleConvChat *chat, PurpleConvChatBuddy *cb, const char *key, const char *value);
1.1393 +
1.1394 +/**
1.1395 + * Set attributes of a chat buddy
1.1396 + *
1.1397 + * @param chat The chat.
1.1398 + * @param cb The chat buddy.
1.1399 + * @param keys A GList of the keys.
1.1400 + * @param values A GList of the values.
1.1401 + */
1.1402 +void
1.1403 +purple_conv_chat_cb_set_attributes(PurpleConvChat *chat, PurpleConvChatBuddy *cb, GList *keys, GList *values);
1.1404 +
1.1405 +
1.1406 +/**
1.1407 + * Destroys a chat buddy
1.1408 + *
1.1409 + * @param cb The chat buddy to destroy
1.1410 + */
1.1411 +void purple_conv_chat_cb_destroy(PurpleConvChatBuddy *cb);
1.1412 +
1.1413 +/**
1.1414 + * Retrieves the extended menu items for the conversation.
1.1415 + *
1.1416 + * @param conv The conversation.
1.1417 + *
1.1418 + * @return A list of PurpleMenuAction items, harvested by the
1.1419 + * chat-extended-menu signal. The list and the menuaction
1.1420 + * items should be freed by the caller.
1.1421 + *
1.1422 + * @since 2.1.0
1.1423 + */
1.1424 +GList * purple_conversation_get_extended_menu(PurpleConversation *conv);
1.1425 +
1.1426 +/**
1.1427 + * Perform a command in a conversation. Similar to @see purple_cmd_do_command
1.1428 + *
1.1429 + * @param conv The conversation.
1.1430 + * @param cmdline The entire command including the arguments.
1.1431 + * @param markup @c NULL, or the formatted command line.
1.1432 + * @param error If the command failed errormsg is filled in with the appropriate error
1.1433 + * message, if not @c NULL. It must be freed by the caller with g_free().
1.1434 + *
1.1435 + * @return @c TRUE if the command was executed successfully, @c FALSE otherwise.
1.1436 + *
1.1437 + * @since 2.1.0
1.1438 + */
1.1439 +gboolean purple_conversation_do_command(PurpleConversation *conv, const gchar *cmdline, const gchar *markup, gchar **error);
1.1440 +
1.1441 +/*@}*/
1.1442 +
1.1443 +/**************************************************************************/
1.1444 +/** @name Conversations Subsystem */
1.1445 +/**************************************************************************/
1.1446 +/*@{*/
1.1447 +
1.1448 +/**
1.1449 + * Returns the conversation subsystem handle.
1.1450 + *
1.1451 + * @return The conversation subsystem handle.
1.1452 + */
1.1453 +void *purple_conversations_get_handle(void);
1.1454 +
1.1455 +/**
1.1456 + * Initializes the conversation subsystem.
1.1457 + */
1.1458 +void purple_conversations_init(void);
1.1459 +
1.1460 +/**
1.1461 + * Uninitializes the conversation subsystem.
1.1462 + */
1.1463 +void purple_conversations_uninit(void);
1.1464 +
1.1465 +/*@}*/
1.1466 +
1.1467 +#ifdef __cplusplus
1.1468 +}
1.1469 +#endif
1.1470 +
1.1471 +#endif /* _PURPLE_CONVERSATION_H_ */