annotate doc/conversation-signals.dox @ 22771:43233dc1d40b

applied changes from 4c5110037671f84e3e775214c32692b5b23c11e1 through ae37fe6b64c30704715a369df88bd76674a39b1a applied changes from 4c5110037671f84e3e775214c32692b5b23c11e1 through ae37fe6b64c30704715a369df88bd76674a39b1a applied changes from b28057d6ade7c221b0616c3b02e86659e2d8b10b through 52c0efb045580dac7b6f5e40c91002e917e0cae3 Plucked changes for the chat-join-failed signal and associated server.c function from im.pidgin.pidgin, as these necessitate a minor version bump.

/** @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 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-buddy-joining
  @signal chat-buddy-joined
  @signal chat-buddy-flags
  @signal chat-buddy-leaving
  @signal chat-buddy-left
  @signal chat-inviting-user
  @signal chat-invited-user
  @signal chat-invited
  @signal chat-joined
  @signal chat-join-failed
  @signal chat-left
  @signal chat-topic-changed
  @signal conversation-extended-menu
 @endsignals

 @see conversation.h

 @signaldef writing-im-msg
  @signalproto
gboolean (*writing_im_msg)(PurpleAccount *account, const char *who,
                           char **message, PurpleConversation *conv,
                           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 conv    The 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, PurpleConversation *conv,
                     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 conv    The 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, PurpleConversation *conv,
                             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 conv    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,
                        PurpleConversation *conv, 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 conv    The IM conversation.
  @param flags   The IM message flags.
 @endsignaldef

 @signaldef writing-chat-msg
  @signalproto
gboolean (*writing_chat_msg)(PurpleAccount *account, const char *who,
                             char **message, PurpleConversation *conv,
                             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 conv    The 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, PurpleConversation *conv,
                       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 conv    The 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, PurpleConversation *conv, 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 conv    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,
                              PurpleConversation *conv, 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 conv    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-buddy-joining
  @signalproto
gboolean (*chat_buddy_joining)(PurpleConversation *conv, const char *name,
                           PurpleConvChatBuddyFlags 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 conv 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-buddy-joined
  @signalproto
void (*chat_buddy_joined)(PurpleConversation *conv, const char *name,
                          PurpleConvChatBuddyFlags flags,
                          gboolean new_arrival);
  @endsignalproto
  @signaldesc
   Emitted when a buddy joined a chat, after the users list is updated.
  @param conv 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-buddy-flags
  @signalproto
void (*chat_buddy_flags)(PurpleConversation *conv, const char *name,
                         PurpleConvChatBuddyFlags oldflags,
                         PurpleConvChatBuddyFlags newflags);
  @endsignalproto
  @signaldesc
   Emitted when a user in a chat changes flags.
  @param conv The chat conversation.
  @param name The name of the user.
  @param oldflags The old flags.
  @param newflags The new flags.
 @endsignaldef

 @signaldef chat-buddy-leaving
  @signalproto
gboolean (*chat_buddy_leaving)(PurpleConversation *conv, 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 conv   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-buddy-left
  @signalproto
void (*chat_buddy_left)(PurpleConversation *conv, 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 conv   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)(PurpleConversation *conv, 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 conv           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)(PurpleConversation *conv, const char *name,
                          const char *invite_message);
  @endsignalproto
  @signaldesc
   Emitted when a user invited another user to a chat.
  @param conv           The chat conversation.
  @param conv           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-joined
  @signalproto
void (*chat_joined)(PurpleConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when an account joins a chat room.
  @param conv The conversation that joined the chat room.
 @endsignaldef

 @signaldef chat-join-failed
  @signalproto
void (*chat_join_failed)(PurpleConnection *gc, const char *name);
  @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 name The name of the chat.
 @endsignaldef
 
 @signaldef chat-left
  @signalproto
void (*chat_left)(PurpleConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when an account leaves a chat room.
  @param conv The conversation that left the chat room.
 @endsignaldef

 @signaldef chat-topic-changed
  @signalproto
void (*chat_topic_changed)(PurpleConversation *conv, const char *who, const char *topic);
  @endsignalproto
  @signaldesc
   Emitted when the topic is changed in a chat.
  @param conv  The 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.
  @since 2.1.0
 @endsignaldef
*/
// vim: syntax=c.doxygen tw=75 et