comparison libpurple/conversation.h @ 32687:02a2e8183b1d

Clean the API documentation in preparation for 3.0.0 by removing all the old @since tags.

32685:9d5b87e1a4d0

	PURPLE_MESSAGE_RAW         = 0x0800, /**< "Raw" message - don't
	                                        apply formatting         */
	PURPLE_MESSAGE_IMAGES      = 0x1000, /**< Message contains images  */
	PURPLE_MESSAGE_NOTIFY      = 0x2000, /**< Message is a notification */
	PURPLE_MESSAGE_NO_LINKIFY  = 0x4000, /**< Message should not be auto-
										   linkified @since 2.1.0 */
	PURPLE_MESSAGE_INVISIBLE   = 0x8000  /**< Message should not be displayed */
} PurpleMessageFlags;

/**
 * Flags applicable to users in Chats.

	PURPLE_CBFLAGS_VOICE         = 0x0001, /**< Voiced user or "Participant" */
	PURPLE_CBFLAGS_HALFOP        = 0x0002, /**< Half-op                      */
	PURPLE_CBFLAGS_OP            = 0x0004, /**< Channel Op or Moderator      */
	PURPLE_CBFLAGS_FOUNDER       = 0x0008, /**< Channel Founder              */
	PURPLE_CBFLAGS_TYPING        = 0x0010, /**< Currently typing             */
	PURPLE_CBFLAGS_AWAY          = 0x0020  /**< Currently away. @since 2.8.0 */

} PurpleConvChatBuddyFlags;

#include "account.h"
#include "buddyicon.h"

	char  *topic;                    /**< The topic.                    */
	int    id;                       /**< The chat ID.                  */
	char *nick;                      /**< Your nick in this chat.       */

	gboolean left;                   /**< We left the chat and kept the window open */
	GHashTable *users;               /**< Hash table of the users in the room.
	                                  *   @since 2.9.0
	                                  */
};

/**
 * Data for "Chat Buddies"
 */

	gpointer ui_data;
};

/**
 * Description of a conversation message
 *
 * @since 2.2.0
 */
struct _PurpleConvMessage
{
	char *who;
	char *what;
	PurpleMessageFlags flags;
	time_t when;
	PurpleConversation *conv;  /**< @since 2.3.0 */
	char *alias;               /**< @since 2.3.0 */
};

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

 * @param conv   The conversation
 *
 * @return  A GList of PurpleConvMessage's. The must not modify the list or the data within.
 *          The list contains the newest message at the beginning, and the oldest message at
 *          the end.
 *
 * @since 2.2.0
 */
GList *purple_conversation_get_message_history(PurpleConversation *conv);

/**
 * Clear the message history of a conversation.
 *
 * @param conv  The conversation
 *
 * @since 2.2.0
 */
void purple_conversation_clear_message_history(PurpleConversation *conv);

/**
 * Get the sender from a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The name of the sender of the message
 *
 * @since 2.2.0
 */
const char *purple_conversation_message_get_sender(PurpleConvMessage *msg);

/**
 * Get the message from a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The name of the sender of the message
 *
 * @since 2.2.0
 */
const char *purple_conversation_message_get_message(PurpleConvMessage *msg);

/**
 * Get the message-flags of a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The message flags
 *
 * @since 2.2.0
 */
PurpleMessageFlags purple_conversation_message_get_flags(PurpleConvMessage *msg);

/**
 * Get the timestamp of a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The timestamp of the message
 *
 * @since 2.2.0
 */
time_t purple_conversation_message_get_timestamp(PurpleConvMessage *msg);

/**
 * Set the UI data associated with this conversation.

 * @param chat     The chat.
 * @param user     The user to invite to the chat.
 * @param message  The message to send with the invitation.
 * @param confirm  Prompt before sending the invitation. The user is always
 *                 prompted if either \a user or \a message is @c NULL.
 *
 * @since 2.6.0
 */
void purple_conv_chat_invite_user(PurpleConvChat *chat, const char *user,
		const char *message, gboolean confirm);

/**

 * @param conv The conversation.
 *
 * @return  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
 */
GList * purple_conversation_get_extended_menu(PurpleConversation *conv);

/**
 * Perform a command in a conversation. Similar to @see purple_cmd_do_command

 * @param markup  @c NULL, or the formatted command line.
 * @param error   If the command failed errormsg is filled in with the appropriate error
 *                message, if not @c NULL. It must be freed by the caller with g_free().
 *
 * @return  @c TRUE if the command was executed successfully, @c FALSE otherwise.
 *
 * @since 2.1.0
 */
gboolean purple_conversation_do_command(PurpleConversation *conv, const gchar *cmdline, const gchar *markup, gchar **error);

/*@}*/

32687:02a2e8183b1d

	PURPLE_MESSAGE_RAW         = 0x0800, /**< "Raw" message - don't
	                                        apply formatting         */
	PURPLE_MESSAGE_IMAGES      = 0x1000, /**< Message contains images  */
	PURPLE_MESSAGE_NOTIFY      = 0x2000, /**< Message is a notification */
	PURPLE_MESSAGE_NO_LINKIFY  = 0x4000, /**< Message should not be auto-
										   linkified */
	PURPLE_MESSAGE_INVISIBLE   = 0x8000  /**< Message should not be displayed */
} PurpleMessageFlags;

/**
 * Flags applicable to users in Chats.

	PURPLE_CBFLAGS_VOICE         = 0x0001, /**< Voiced user or "Participant" */
	PURPLE_CBFLAGS_HALFOP        = 0x0002, /**< Half-op                      */
	PURPLE_CBFLAGS_OP            = 0x0004, /**< Channel Op or Moderator      */
	PURPLE_CBFLAGS_FOUNDER       = 0x0008, /**< Channel Founder              */
	PURPLE_CBFLAGS_TYPING        = 0x0010, /**< Currently typing             */
	PURPLE_CBFLAGS_AWAY          = 0x0020  /**< Currently away.              */

} PurpleConvChatBuddyFlags;

#include "account.h"
#include "buddyicon.h"

	char  *topic;                    /**< The topic.                    */
	int    id;                       /**< The chat ID.                  */
	char *nick;                      /**< Your nick in this chat.       */

	gboolean left;                   /**< We left the chat and kept the window open */
	GHashTable *users;               /**< Hash table of the users in the room. */
};

/**
 * Data for "Chat Buddies"
 */

	gpointer ui_data;
};

/**
 * Description of a conversation message
 */
struct _PurpleConvMessage
{
	char *who;
	char *what;
	PurpleMessageFlags flags;
	time_t when;
	PurpleConversation *conv;
	char *alias;
};

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

 * @param conv   The conversation
 *
 * @return  A GList of PurpleConvMessage's. The must not modify the list or the data within.
 *          The list contains the newest message at the beginning, and the oldest message at
 *          the end.
 */
GList *purple_conversation_get_message_history(PurpleConversation *conv);

/**
 * Clear the message history of a conversation.
 *
 * @param conv  The conversation
 */
void purple_conversation_clear_message_history(PurpleConversation *conv);

/**
 * Get the sender from a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The name of the sender of the message
 */
const char *purple_conversation_message_get_sender(PurpleConvMessage *msg);

/**
 * Get the message from a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The name of the sender of the message
 */
const char *purple_conversation_message_get_message(PurpleConvMessage *msg);

/**
 * Get the message-flags of a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The message flags
 */
PurpleMessageFlags purple_conversation_message_get_flags(PurpleConvMessage *msg);

/**
 * Get the timestamp of a PurpleConvMessage
 *
 * @param msg   A PurpleConvMessage
 *
 * @return   The timestamp of the message
 */
time_t purple_conversation_message_get_timestamp(PurpleConvMessage *msg);

/**
 * Set the UI data associated with this conversation.

 * @param chat     The chat.
 * @param user     The user to invite to the chat.
 * @param message  The message to send with the invitation.
 * @param confirm  Prompt before sending the invitation. The user is always
 *                 prompted if either \a user or \a message is @c NULL.
 */
void purple_conv_chat_invite_user(PurpleConvChat *chat, const char *user,
		const char *message, gboolean confirm);

/**

 * @param conv The conversation.
 *
 * @return  A list of PurpleMenuAction items, harvested by the
 *          chat-extended-menu signal. The list and the menuaction
 *          items should be freed by the caller.
 */
GList * purple_conversation_get_extended_menu(PurpleConversation *conv);

/**
 * Perform a command in a conversation. Similar to @see purple_cmd_do_command

 * @param markup  @c NULL, or the formatted command line.
 * @param error   If the command failed errormsg is filled in with the appropriate error
 *                message, if not @c NULL. It must be freed by the caller with g_free().
 *
 * @return  @c TRUE if the command was executed successfully, @c FALSE otherwise.
 */
gboolean purple_conversation_do_command(PurpleConversation *conv, const gchar *cmdline, const gchar *markup, gchar **error);

/*@}*/