--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference/libpurple/conversation-signals.dox Sun Oct 13 15:41:22 2013 +0530
@@ -0,0 +1,515 @@
+/** @page conversation-signals Conversation Signals
+
+ @signals
+ @signal writing-im-msg
+ @signal wrote-im-msg
+ @signal sending-im-msg
+ @signal sent-im-msg
+ @signal receiving-im-msg
+ @signal received-im-msg
+ @signal blocked-im-msg
+ @signal writing-chat-msg
+ @signal wrote-chat-msg
+ @signal sending-chat-msg
+ @signal sent-chat-msg
+ @signal receiving-chat-msg
+ @signal received-chat-msg
+ @signal conversation-created
+ @signal conversation-updated
+ @signal deleting-conversation
+ @signal buddy-typing
+ @signal buddy-typing-stopped
+ @signal chat-user-joining
+ @signal chat-user-joined
+ @signal chat-user-flags
+ @signal chat-user-leaving
+ @signal chat-user-left
+ @signal chat-inviting-user
+ @signal chat-invited-user
+ @signal chat-invited
+ @signal chat-invite-blocked
+ @signal chat-joined
+ @signal chat-join-failed
+ @signal chat-left
+ @signal chat-topic-changed
+ @signal cleared-message-history
+ @signal conversation-extended-menu
+ @signal sent-attention
+ @signal got-attention
+ @endsignals
+
+ @see conversation.h
+
+ @signaldef writing-im-msg
+ @signalproto
+gboolean (*writing_im_msg)(PurpleAccount *account, const char *who,
+ char **message, PurpleIMConversation *im,
+ PurpleMessageFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted before a message is written in an IM conversation. If the
+ message is changed, then the changed message is displayed and logged
+ instead of the original message.
+ @note
+ Make sure to free @a *message before you replace it!
+ @param account The account.
+ @param who The name of the user.
+ @param message A pointer to the message.
+ @param im The IM conversation.
+ @param flags Flags for this message.
+ @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
+ @endsignaldef
+
+ @signaldef wrote-im-msg
+ @signalproto
+void (*wrote_im_msg)(PurpleAccount *account, const char *who,
+ char *message, PurpleIMConversation *im,
+ PurpleMessageFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted after a message is written and possibly displayed in a conversation.
+ @param account The account.
+ @param who The name of the user.
+ @param message The message.
+ @param im The IM conversation.
+ @param flags Flags for this message.
+ @endsignaldef
+
+ @signaldef sending-im-msg
+ @signalproto
+void (*sending_im_msg)(PurpleAccount *account, const char *receiver,
+ char **message);
+ @endsignalproto
+ @signaldesc
+ Emitted before sending an IM to a user. @a message is a pointer to the
+ message string, so the plugin can replace the message before being sent.
+ @note
+ Make sure to free @a *message before you replace it!
+ @param account The account the message is being sent on.
+ @param receiver The username of the receiver.
+ @param message A pointer to the outgoing message. This can be modified.
+ @endsignaldef
+
+ @signaldef sent-im-msg
+ @signalproto
+void (*sent_im_msg)(PurpleAccount *account, const char *receiver,
+ const char *message);
+ @endsignalproto
+ @signaldesc
+ Emitted after sending an IM to a user.
+ @param account The account the message was sent on.
+ @param receiver The username of the receiver.
+ @param message The message that was sent.
+ @endsignaldef
+
+ @signaldef receiving-im-msg
+ @signalproto
+gboolean (*receiving_im_msg)(PurpleAccount *account, char **sender,
+ char **message, PurpleIMConversation *im,
+ PurpleMessageFlags *flags);
+ @endsignalproto
+ @signaldesc
+ Emitted when an IM is received. The callback can replace the name of the
+ sender, the message, or the flags by modifying the pointer to the
+ strings and integer. This can also be used to cancel a message by
+ returning @c TRUE.
+ @note
+ Make sure to free @a *sender and @a *message before you replace them!
+ @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
+ @param account The account the message was received on.
+ @param sender A pointer to the username of the sender.
+ @param message A pointer to the message that was sent.
+ @param im The IM conversation.
+ @param flags A pointer to the IM message flags.
+ @endsignaldef
+
+ @signaldef received-im-msg
+ @signalproto
+void (*received_im_msg)(PurpleAccount *account, char *sender, char *message,
+ PurpleIMConversation *im, PurpleMessageFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted after an IM is received.
+ @param account The account the message was received on.
+ @param sender The username of the sender.
+ @param message The message that was sent.
+ @param im The IM conversation.
+ @param flags The IM message flags.
+ @endsignaldef
+
+ @signaldef blocked-im-msg
+ @signalproto
+void (*blocked_im_msg)(PurpleAccount *account, const char *sender,
+ const char *message, PurpleMessageFlags flags, time_t when);
+ @endsignalproto
+ @signaldesc
+ Emitted after an IM is blocked due to privacy settings.
+ @param account The account the message was received on.
+ @param sender The username of the sender.
+ @param message The message that was blocked.
+ @param flags The IM message flags.
+ @param when The time the message was sent.
+ @endsignaldef
+
+ @signaldef writing-chat-msg
+ @signalproto
+gboolean (*writing_chat_msg)(PurpleAccount *account, const char *who,
+ char **message, PurpleChatConversation *chat,
+ PurpleMessageFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted before a message is written in a chat conversation. If the
+ message is changed, then the changed message is displayed and logged
+ instead of the original message.
+ @note
+ Make sure to free @a *message before you replace it!
+ @param account The account.
+ @param who The name of the user.
+ @param message A pointer to the message.
+ @param chat The chat conversation.
+ @param flags Flags for this message.
+ @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
+ @endsignaldef
+
+ @signaldef wrote-chat-msg
+ @signalproto
+void (*wrote_chat_msg)(PurpleAccount *account, const char *who,
+ char *message, PurpleChatConversation *chat,
+ PurpleMessageFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted after a message is written and possibly displayed in a chat.
+ @param account The account.
+ @param who The name of the user.
+ @param message The message.
+ @param chat The chat conversation.
+ @param flags Flags for this message.
+ @endsignaldef
+
+ @signaldef sending-chat-msg
+ @signalproto
+void (*sending_chat_msg)(PurpleAccount *account, char **message, int id);
+ @endsignalproto
+ @signaldesc
+ Emitted before sending a message to a chat. @a message is a pointer to the
+ message string, so the plugin can replace the message before being sent.
+ @note
+ Make sure to free @a *message before you replace it!
+ @param account The account the message is being sent on.
+ @param message A pointer to the message that will be sent.
+ @param id The ID of the chat.
+ @endsignaldef
+
+ @signaldef sent-chat-msg
+ @signalproto
+void (*sent_chat_msg)(PurpleAccount *account, const char *message, int id);
+ @endsignalproto
+ @signaldesc
+ Emitted after sending a message to a chat.
+ @param account The account the message was sent on.
+ @param message The message that was sent.
+ @param id The ID of the chat.
+ @endsignaldef
+
+ @signaldef receiving-chat-msg
+ @signalproto
+gboolean (*receiving_chat_msg)(PurpleAccount *account, char **sender,
+ char **message, PurpleChatConversation *chat, int *flags);
+ @endsignalproto
+ @signaldesc
+ Emitted when a chat message is received. The callback can replace the
+ name of the sender, the message, or the flags by modifying the pointer to the
+ strings. This can also be used to cancel displaying a message by
+ returning @c TRUE.
+ @note
+ Make sure to free @a *sender and @a *message before you replace them!
+ @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
+ @param account The account the message was received on.
+ @param sender A pointer to the username of the sender.
+ @param message A pointer to the message that was sent.
+ @param chat The chat conversation.
+ @param flags A pointer to the chat message flags
+ @endsignaldef
+
+ @signaldef received-chat-msg
+ @signalproto
+void (*received_chat_msg)(PurpleAccount *account, char *sender, char *message,
+ PurpleChatConversation *chat, PurpleMessageFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted after a chat message is received.
+ @param account The account the message was received on.
+ @param sender The username of the sender.
+ @param message The message that was sent.
+ @param chat The chat conversation.
+ @param flags The chat message flags.
+ @endsignaldef
+
+ @signaldef conversation-created
+ @signalproto
+void (*conversation_created)(PurpleConversation *conv);
+ @endsignalproto
+ @signaldesc
+ Emitted when a new conversation is created.
+ @param conv The new conversation.
+ @endsignaldef
+
+ @signaldef conversation-updated
+ @signalproto
+void (*conversation_updated)(PurpleConversation *conv,
+ PurpleConvUpdateType type);
+ @endsignalproto
+ @signaldesc
+ Emitted when a conversation is updated.
+ @param conv The conversation that was updated.
+ @param type The type of update that was made.
+ @endsignaldef
+
+ @signaldef deleting-conversation
+ @signalproto
+void (*deleting_conversation)(PurpleConversation *conv);
+ @endsignalproto
+ @signaldesc
+ Emitted just before a conversation is to be destroyed.
+ @param conv The conversation that's about to be destroyed.
+ @endsignaldef
+
+ @signaldef buddy-typing
+ @signalproto
+void (*buddy_typing)(PurpleAccount *account, const char *name);
+ @endsignalproto
+ @signaldesc
+ Emitted when a buddy starts typing in a conversation window.
+ @param account The account of the user which is typing.
+ @param name The name of the user which is typing.
+ @endsignaldef
+
+ @signaldef buddy-typing-stopped
+ @signalproto
+void (*buddy_typing_stopped)(PurpleAccount *account, const char *name);
+ @endsignalproto
+ @signaldesc
+ Emitted when a buddy stops typing in a conversation window.
+ @param account The account of the user which stopped typing.
+ @param name The name of the user which stopped typing.
+ @endsignaldef
+
+ @signaldef chat-user-joining
+ @signalproto
+gboolean (*chat_user_joining)(PurpleChatConversation *chat, const char *name,
+ PurpleChatUserFlags flags);
+ @endsignalproto
+ @signaldesc
+ Emitted when a buddy is joining a chat, before the list of
+ users in the chat updates to include the new user.
+ @return @c TRUE if the join should be hidden, or @c FALSE otherwise.
+ @param chat The chat conversation.
+ @param name The name of the user that is joining the conversation.
+ @param flags The flags of the user that is joining the conversation.
+ @endsignaldef
+
+ @signaldef chat-user-joined
+ @signalproto
+void (*chat_user_joined)(PurpleChatConversation *chat, const char *name,
+ PurpleChatUserFlags flags,
+ gboolean new_arrival);
+ @endsignalproto
+ @signaldesc
+ Emitted when a buddy joined a chat, after the users list is updated.
+ @param chat The chat conversation.
+ @param name The name of the user that has joined the conversation.
+ @param flags The flags of the user that has joined the conversation.
+ @param new_arrival If the buddy is a new arrival.
+ @endsignaldef
+
+ @signaldef chat-join-failed
+ @signalproto
+void (*chat_join_failed)(PurpleConnection *gc, GHashTable *components);
+ @endsignalproto
+ @signaldesc
+ Emitted when an account fails to join a chat room
+ @param gc The PurpleConnection of the account which failed to join the chat.
+ @param data The components passed to serv_join_chat() originally.
+ The hash function should be g_str_hash() and the equal
+ function should be g_str_equal().
+ @endsignaldef
+
+ @signaldef chat-user-flags
+ @signalproto
+void (*chat_user_flags)(PurpleChatUser *chatuser,
+ PurpleChatUserFlags oldflags,
+ PurpleChatUserFlags newflags);
+ @endsignalproto
+ @signaldesc
+ Emitted when a user in a chat changes flags.
+ @param chatuser The chat user whose flags changed.
+ @param oldflags The old flags.
+ @param newflags The new flags.
+ @endsignaldef
+
+ @signaldef chat-user-leaving
+ @signalproto
+gboolean (*chat_user_leaving)(PurpleChatConversation *chat, const char *name,
+ const char *reason);
+ @endsignalproto
+ @signaldesc
+ Emitted when a user is leaving a chat, before the user list is updated.
+ This may include an optional reason why the user is leaving.
+ @return @c TRUE if the leave should be hidden, or @c FALSE otherwise.
+ @param chat The chat conversation.
+ @param name The name of the user that is leaving the chat.
+ @param reason The optional reason why the user is leaving.
+ @endsignaldef
+
+ @signaldef chat-user-left
+ @signalproto
+void (*chat_user_left)(PurpleChatConversation *chat, const char *name,
+ const char *reason);
+ @endsignalproto
+ @signaldesc
+ Emitted when a user leaves a chat, after the user list is updated.
+ This may include an optional reason why the user is leaving.
+ @param chat The chat conversation.
+ @param name The name of the user that left the chat.
+ @param reason The optional reason why the user left the chat.
+ @endsignaldef
+
+ @signaldef chat-inviting-user
+ @signalproto
+void (*chat_inviting_user)(PurpleChatConversation *chat, const char *name,
+ char **invite_message);
+ @endsignalproto
+ @signaldesc
+ Emitted when a user is being invited to the chat. The callback can
+ replace the invite message to the invitee by modifying the pointer to
+ the invite message.
+ @note
+ Make sure to free @a *invite_message before you replace it!
+ @param chat The chat conversation.
+ @param name The name of the user being invited.
+ @param invite_message A pointer to the reason why a user is being
+ invited.
+ @endsignaldef
+
+ @signaldef chat-invited-user
+ @signalproto
+void (*chat_invited_user)(PurpleChatConversation *conv, const char *name,
+ const char *invite_message);
+ @endsignalproto
+ @signaldesc
+ Emitted when a user invited another user to a chat.
+ @param chat The chat conversation.
+ @param name The name of the user that was invited.
+ @param invite_message The message to be sent to the user when invited.
+ @endsignaldef
+
+ @signaldef chat-invited
+ @signalproto
+gint (*chat_invited)(PurpleAccount *account, const char *inviter,
+ const char *chat, const char *invite_message
+ const GHashTable *components);
+ @endsignalproto
+ @signaldesc
+ Emitted when an account was invited to a chat.
+ @param account The account being invited.
+ @param inviter The username of the person inviting the account.
+ @param chat The name of the chat you're being invited to.
+ @param invite_message The optional invite message.
+ @param components The components necessary if you want to call
+ serv_join_chat()
+ @return Less than zero if the invitation should be rejected, greater than
+ zero if the invitation should be accepted. If zero is returned, the
+ default behavior will be maintained: the user will be prompted.
+ @endsignaldef
+
+ @signaldef chat-invite-blocked
+ @signalproto
+void (*chat_invite_blocked)(PurpleAccount *account, const char *inviter,
+ const char *name, const char *message, GHashTable *data);
+ @endsignalproto
+ @signaldesc
+ Emitted when an invitation to join a chat is blocked.
+ @param account The account the invitation was sent to.
+ @param inviter The name of the person sending the invitation.
+ @param name The name of the chat invited to.
+ @param message The invitation message sent.
+ @param data Hashtable containing data about the invited chat.
+ @endsignaldef
+
+ @signaldef chat-joined
+ @signalproto
+void (*chat_joined)(PurpleChatConversation *chat);
+ @endsignalproto
+ @signaldesc
+ Emitted when an account joins a chat room.
+ @param chat The conversation that joined the chat room.
+ @endsignaldef
+
+ @signaldef chat-left
+ @signalproto
+void (*chat_left)(PurpleChatConversation *chat);
+ @endsignalproto
+ @signaldesc
+ Emitted when an account leaves a chat room.
+ @param chat The conversation that left the chat room.
+ @endsignaldef
+
+ @signaldef chat-topic-changed
+ @signalproto
+void (*chat_topic_changed)(PurpleChatConversation *chat, const char *who,
+ const char *topic);
+ @endsignalproto
+ @signaldesc
+ Emitted when the topic is changed in a chat.
+ @param chat The chat conversation whose topic changed.
+ @param who The name of the person that changed the topic.
+ @param topic The new topic.
+ @endsignaldef
+
+ @signaldef conversation-extended-menu
+ @signalproto
+void (*conversation_extended_menu)(PurpleConversation *conv, GList **list);
+ @endsignalproto
+ @signaldesc
+ Emitted when the UI requests a list of plugin actions for a
+ conversation.
+ @param conv The conversation.
+ @param list A pointer to the list of actions.
+ @endsignaldef
+
+ @signaldef cleared-message-history
+ @signalproto
+void (*cleared_message_history)(PurpleConversation *conv);
+ @endsignalproto
+ @signaldesc
+ Emitted when the conversation history is cleared.
+ @param conv The conversation.
+ @endsignaldef
+
+ @signaldef sent-attention
+ @signalproto
+void (*got_attention)(PurpleAccount *account, const char *who,
+ PurpleConversation *conv, guint type)
+ @endsignalproto
+ @signaldesc
+ Emitted when receiving an attention message (buzz, nudge, etc.).
+ @param account The account
+ @param who The name of the person receiving the attention
+ @param conv The conversation
+ @param type The attention type (an index starting at 0)
+ @endsignaldef
+
+ @signaldef got-attention
+ @signalproto
+void (*got_attention)(PurpleAccount *account, const char *who,
+ PurpleConversation *conv, guint type)
+ @endsignalproto
+ @signaldesc
+ Emitted when receiving an attention message (buzz, nudge, etc.).
+ @param account The account
+ @param who The name of the person sending the attention
+ @param conv The conversation
+ @param type The attention type (an index starting at 0)
+ @endsignaldef
+*/
+// vim: syntax=c.doxygen tw=75 et
