annotate doc/conversation-signals.dox @ 9584:fe35f55ee984

[gaim-migrate @ 10427] " When joining a jabber conference many jabber servers send a recap of the last 20 or so messages. If you have sounds enabled, this will result in either 20 sounds in row, or worse if mixing is available, a horrible mix of 20 overlapping sounds. These recap messages can be identifed be the presence of the "jabber:x:delay". This patch identifies delayed messages, passes that information through flags from the prpl to the core, and then on to the gui. Detailed changes: Add GAIM_MESSAGE_DELAYED to GaimMessageFlags to indicate a delayed message. Change gtkconv.c to not play sounds when either GAIM_MESSAGE_DELAYED or GAIM_MESSAGE_SYSTEM are set. Add GaimConvChatFlags, parallel to GaimConvImFlags, to pass flags from protocols to core. Currently contains two flags: GAIM_CONV_CHAT_WHISPER GAIM_CONV_CHAT_DELAYED Change fourth arg of serv_got_chat_in() from "int whisper" to "GaimConvChatFlags chatflags". Change jabber prpl to set delayed flag when the "jabber:x:delay" element is present. Change toc protocol since it uses the whisper flag." --Nathan Fredrickson Date: 2004-07-24 00:49 Sender: marv_sfAccepting Donations Logged In: YES user_id=790708 I'm not sure I like naming the flags "DELAYED". I mean that's okay inside jabber since that's what the jabber protocol refers to it as, but for the the GAIM_*_DELAYED flags, I think they should be named something else. I thought about NOSOUND, but I decided that was wrong, because the flag should say what kind of message it is, not what to do with it, that's up to the UI to decide. What's up with not playing sounds on GAIM_MESSAGE_SYSTEM? This sounds unrelated to this. Are there times when we want to play sounds on system messages? Date: 2004-07-24 09:13 Sender: noif Logged In: YES user_id=365548 I purposely did not use a name that implied what the UI should do with the flag. The only characteristic that makes these messages unique is that they've been stored in the server for some period of time and are not current. I'm open to a better flag name than "DELAYED"... I thought about "RECAP", but that seemed less generalized than "DELAYED". As for not playing sounds on GAIM_MESSAGE_SYSTEM, that can be removed if it's controversial. I think I slipped that in since the setting of the topic was still playing a sound every time you joined a jabber conference. I think we can change the flag name ourselves if something else is better. committer: Tailor Script <[e-mail]>

/** @page conversation-signals Conversation Signals

 @signals
  @signal writing-im-msg
  @signal wrote-im-msg
  @signal displaying-im-msg
  @signal displayed-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 displaying-chat-msg
  @signal displayed-chat-msg
  @signal sending-chat-msg
  @signal sent-chat-msg
  @signal receiving-chat-msg
  @signal received-chat-msg
  @signal conversation-switching
  @signal conversation-switched
  @signal conversation-created
  @signal deleting-conversation
  @signal buddy-typing
  @signal buddy-typing-stopped
  @signal chat-buddy-joining
  @signal chat-buddy-joined
  @signal chat-buddy-leaving
  @signal chat-buddy-left
  @signal chat-inviting-user
  @signal chat-invited-user
  @signal chat-invited
  @signal chat-joined
  @signal chat-left
  @signal chat-topic-changed
 @endsignals

 @signaldef writing-im-msg
  @signalproto
gboolean (*writing_im_msg)(GaimAccount *account, GaimConversation *conv, char **message);
  @endsignalproto
  @signaldesc
   Emitted before a message is displayed in an IM conversation or sent to a remote user.
   @a message is a pointer to a string, so the plugin can replace the
   message that will be displayed along with the message that will be sent.
   This can also be used to cancel an outgoing message by returning @c TRUE.
  @note
   Make sure to free @a *message before you replace it!
  @param account The account the message is being displayed and sent on.
  @param conv    The conversation the message is being displayed and sent on.
  @param message A pointer to the message that will be displayed and sent.
  @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 @endsignaldef

 @signaldef wrote-im-msg
  @signalproto
void (*wrote_im_msg)(GaimAccount *account, GaimConversation *conv, const char *message);
  @endsignalproto
  @signaldesc
   Emitted after a message is entered by the user, but before it is sent and displyed.
   When sending an IM, the order that the im-msg callbacks will be called is:
   writing-im-msg, wrote-im-msg, displaying-im-msg, displayed-im-msg, sending-im-msg,
   and finally sent-im-msg.
  @param account The account the message was displayed on.
  @param conv    The conversation the message was displayed on.
  @param message The message that was displayed.
 @endsignaldef

 @signaldef displaying-im-msg
  @signalproto
gboolean (*displaying_im_msg)(GaimAccount *account, GaimConversation *conv, char **message);
  @endsignalproto
  @signaldesc
   Emitted just before a message is displayed in an IM conversation.
   @a message is a pointer to a string, so the plugin can replace the
   message that will be displayed. This can also be used to cancel displaying
   a message by returning @c TRUE.
  @note
   Make sure to free @a *message before you replace it!
  @param account The account the message is being displayed on.
  @param conv    The conversation the message is being displayed on.
  @param message A pointer to the message that will be displayed.
  @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 @endsignaldef

 @signaldef displayed-im-msg
  @signalproto
void (*displayed_im_msg)(GaimAccount *account, GaimConversation *conv, const char *message);
  @endsignalproto
  @signaldesc
   Emitted after a message is displayed in an IM conversation.
  @param account The account the message was displayed on.
  @param conv    The conversation the message was displayed on.
  @param message The message that was displayed.
 @endsignaldef

 @signaldef sending-im-msg
  @signalproto
void (*sending_im_msg)(GaimAccount *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)(GaimAccount *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)(GaimAccount *account, char **sender,
                            char **message, int *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 flags   The message flags.
 @endsignaldef

 @signaldef received-im-msg
  @signalproto
void (*received_im_msg)(GaimAccount *account, char *sender,
                            char *message, int 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 flags   The message flags.
 @endsignaldef

 @signaldef writing-chat-msg
  @signalproto
gboolean (*writing_chat_msg)(GaimAccount *account, GaimConversation *conv, char **message);
  @endsignalproto
  @signaldesc
   Emitted before a message is displayed in a chat conversation or sent to
   a remote chat.  @a message is a pointer to a string, so the plugin can
   replace the message that will be displayed along with the message that
   will be sent.  This can also be used to cancel an outgoing message by
   returning @c TRUE.
  @note
   Make sure to free @a *message before you replace it!
  @param account The account the message is being displayed and sent on.
  @param conv    The conversation the message is being displayed and sent on.
  @param message A pointer to the message that will be displayed and sent.
  @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 @endsignaldef

 @signaldef wrote-chat-msg
  @signalproto
void (*wrote_chat_msg)(GaimAccount *account, GaimConversation *conv, const char *message);
  @endsignalproto
  @signaldesc
   Emitted after a message is entered by the user, but before it is sent and displyed.
   When sending an IM, the order that the im-msg callbacks will be called is:
   writing-im-msg, wrote-im-msg, displaying-im-msg, displayed-im-msg, sending-im-msg,
   and finally sent-im-msg.
  @param account The account the message was displayed on.
  @param conv    The conversation the message was displayed on.
  @param message The message that was displayed.
 @endsignaldef

 @signaldef displaying-chat-msg
  @signalproto
gboolean (*displaying_chat_msg)(GaimAccount *account, GaimConversation *conv, char **message);
  @endsignalproto
  @signaldesc
   Emitted just before a message is displayed in a chat.
   @a message is a pointer to a string, so the plugin can replace the
   message that will be displayed. This can also be used to cancel displaying
   a message by returning @c TRUE.
  @note
   Make sure to free @a *message before you replace it!
  @param account The account the message is being displayed on.
  @param conv    The conversation the message is being displayed on.
  @param message A pointer to the message that will be displayed.
  @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 @endsignaldef

 @signaldef displayed-chat-msg
  @signalproto
void (*displayed_chat_msg)(GaimAccount *account, GaimConversation *conv, const char *message);
  @endsignalproto
  @signaldesc
   Emitted after a message is displayed in a chat conversation.
  @param account The account the message was displayed on.
  @param conv    The conversation the message was displayed on.
  @param message The message that was displayed.
 @endsignaldef

 @signaldef sending-chat-msg
  @signalproto
void (*sending_chat_msg)(GaimAccount *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)(GaimAccount *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)(GaimAccount *account, char **sender,
                              char **message, GaimConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when a chat message is received. The callback can replace the
   name of the sender or the messageby 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.
 @endsignaldef

 @signaldef received-chat-msg
  @signalproto
void (*received_chat_msg)(GaimAccount *account, char *sender,
                              char *message, GaimConversation *conv);
  @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.
 @endsignaldef

 @signaldef conversation-switching
  @signalproto
void (*conversation_switching)(GaimConversation *old_conv,
                               GaimConversation *new_conv);
  @endsignalproto
  @signaldesc
   Emitted when a window is about to switch from one conversation to
   another.
  @param old_conv The old active conversation.
  @param new_conv The soon-to-be active conversation
 @endsignaldef

 @signaldef conversation-switched
  @signalproto
void (*conversation_switched)(GaimConversation *old_conv,
                              GaimConversation *new_conv);
  @endsignalproto
  @signaldesc
   Emitted when a window switched from one conversation to another.
  @param old_conv The old active conversation.
  @param new_conv The now active conversation.
 @endsignaldef

 @signaldef conversation-created
  @signalproto
void (*conversation_created)(GaimConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when a new conversation is created.
  @param conv The new conversation.
 @endsignaldef

 @signaldef deleting-conversation
  @signalproto
void (*deleting_conversation)(GaimConversation *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)(GaimConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when a buddy starts typing in a conversation window.
  @param conv The IM conversation a buddy is typing in.
 @endsignaldef

 @signaldef buddy-typing-stopped
  @signalproto
void (*buddy_typing)(GaimConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when a buddy stops typing in a conversation window.
  @param conv The IM conversation a buddy is typing in.
 @endsignaldef

 @signaldef chat-buddy-joining
  @signalproto
void (*chat_buddy_joining)(GaimConversation *conv, const char *name,
                           GaimConvChatBuddyFlags 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.
  @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)(GaimConversation *conv, const char *name,
                          GaimConvChatBuddyFlags flags);
  @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.
 @endsignaldef

 @signaldef chat-buddy-flags
  @signalproto
void (*chat_buddy_flags)(GaimConversation *conv, const char *name,
                         GaimConvChatBuddyFlags oldflags,
                         GaimConvChatBuddyFlags 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
void (*chat_buddy_leaving)(GaimConversation *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.
  @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)(GaimConversation *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)(GaimConversation *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)(GaimConversation *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
void (*chat_invited)(GaimAccount *account, const char *inviter,
                     const char *chat, const char *invite_message
                     const GHastTable *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
 @endsignaldef

 @signaldef chat-joined
  @signalproto
void (*chat_joined)(GaimConversation *conv);
  @endsignalproto
  @signaldesc
   Emitted when an account joins a chat room.
  @param conv The conversation that joined the chat room.
 @endsignaldef

 @signaldef chat-left
  @signalproto
void (*chat_left)(GaimConversation *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)(GaimConversation *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

*/
// vim: syntax=c tw=75 et