doc/conversation-signals.dox

   1 /** @page conversation-signals Conversation Signals
   2
   3  @signals
   4   @signal writing-im-msg
   5   @signal wrote-im-msg
   6   @signal sending-im-msg
   7   @signal sent-im-msg
   8   @signal receiving-im-msg
   9   @signal received-im-msg
  10   @signal blocked-im-msg
  11   @signal writing-chat-msg
  12   @signal wrote-chat-msg
  13   @signal sending-chat-msg
  14   @signal sent-chat-msg
  15   @signal receiving-chat-msg
  16   @signal received-chat-msg
  17   @signal conversation-created
  18   @signal conversation-updated
  19   @signal deleting-conversation
  20   @signal buddy-typing
  21   @signal buddy-typing-stopped
  22   @signal chat-buddy-joining
  23   @signal chat-buddy-joined
  24   @signal chat-buddy-flags
  25   @signal chat-buddy-leaving
  26   @signal chat-buddy-left
  27   @signal chat-inviting-user
  28   @signal chat-invited-user
  29   @signal chat-invited
  30   @signal chat-invite-blocked
  31   @signal chat-joined
  32   @signal chat-join-failed
  33   @signal chat-left
  34   @signal chat-topic-changed
  35   @signal cleared-message-history
  36   @signal conversation-extended-menu
  37   @signal sent-attention
  38   @signal got-attention
  39  @endsignals
  40
  41  @see conversation.h
  42
  43  @signaldef writing-im-msg
  44   @signalproto
  45 gboolean (*writing_im_msg)(PurpleAccount *account, const char *who,
  46                            char **message, PurpleConversation *conv,
  47                            PurpleMessageFlags flags);
  48   @endsignalproto
  49   @signaldesc
  50    Emitted before a message is written in an IM conversation. If the
  51    message is changed, then the changed message is displayed and logged
  52    instead of the original message.
  53   @note
  54    Make sure to free @a *message before you replace it!
  55   @param account The account.
  56   @param who     The name of the user.
  57   @param message A pointer to the message.
  58   @param conv    The conversation.
  59   @param flags   Flags for this message.
  60   @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
  61  @endsignaldef
  62
  63  @signaldef wrote-im-msg
  64   @signalproto
  65 void (*wrote_im_msg)(PurpleAccount *account, const char *who,
  66                      char *message, PurpleConversation *conv,
  67                      PurpleMessageFlags flags);
  68   @endsignalproto
  69   @signaldesc
  70    Emitted after a message is written and possibly displayed in a conversation.
  71   @param account The account.
  72   @param who     The name of the user.
  73   @param message The message.
  74   @param conv    The conversation.
  75   @param flags   Flags for this message.
  76  @endsignaldef
  77
  78  @signaldef sending-im-msg
  79   @signalproto
  80 void (*sending_im_msg)(PurpleAccount *account, const char *receiver,
  81                        char **message);
  82   @endsignalproto
  83   @signaldesc
  84    Emitted before sending an IM to a user. @a message is a pointer to the
  85    message string, so the plugin can replace the message before being sent.
  86   @note
  87    Make sure to free @a *message before you replace it!
  88   @param account  The account the message is being sent on.
  89   @param receiver The username of the receiver.
  90   @param message  A pointer to the outgoing message. This can be modified.
  91  @endsignaldef
  92
  93  @signaldef sent-im-msg
  94   @signalproto
  95 void (*sent_im_msg)(PurpleAccount *account, const char *receiver,
  96                     const char *message);
  97   @endsignalproto
  98   @signaldesc
  99    Emitted after sending an IM to a user.
 100   @param account  The account the message was sent on.
 101   @param receiver The username of the receiver.
 102   @param message  The message that was sent.
 103  @endsignaldef
 104
 105  @signaldef receiving-im-msg
 106   @signalproto
 107 gboolean (*receiving_im_msg)(PurpleAccount *account, char **sender,
 108                              char **message, PurpleConversation *conv,
 109                              PurpleMessageFlags *flags);
 110   @endsignalproto
 111   @signaldesc
 112    Emitted when an IM is received. The callback can replace the name of the
 113    sender, the message, or the flags by modifying the pointer to the
 114    strings and integer. This can also be used to cancel a message by
 115    returning @c TRUE.
 116   @note
 117    Make sure to free @a *sender and @a *message before you replace them!
 118   @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 119   @param account The account the message was received on.
 120   @param sender  A pointer to the username of the sender.
 121   @param message A pointer to the message that was sent.
 122   @param conv    The IM conversation.
 123   @param flags   A pointer to the IM message flags.
 124  @endsignaldef
 125
 126  @signaldef received-im-msg
 127   @signalproto
 128 void (*received_im_msg)(PurpleAccount *account, char *sender, char *message,
 129                         PurpleConversation *conv, PurpleMessageFlags flags);
 130   @endsignalproto
 131   @signaldesc
 132    Emitted after an IM is received.
 133   @param account The account the message was received on.
 134   @param sender  The username of the sender.
 135   @param message The message that was sent.
 136   @param conv    The IM conversation.
 137   @param flags   The IM message flags.
 138  @endsignaldef
 139
 140  @signaldef blocked-im-msg
 141   @signalproto
 142 void (*blocked_im_msg)(PurpleAccount *account, const char *sender,
 143         const char *message, PurpleMessageFlags flags, time_t when);
 144   @endsignalproto
 145   @signaldesc
 146    Emitted after an IM is blocked due to privacy settings.
 147   @param account The account the message was received on.
 148   @param sender  The username of the sender.
 149   @param message The message that was blocked.
 150   @param flags   The IM message flags.
 151   @param when    The time the message was sent.
 152   @since 2.5.0
 153  @endsignaldef
 154
 155  @signaldef writing-chat-msg
 156   @signalproto
 157 gboolean (*writing_chat_msg)(PurpleAccount *account, const char *who,
 158                              char **message, PurpleConversation *conv,
 159                              PurpleMessageFlags flags);
 160   @endsignalproto
 161   @signaldesc
 162    Emitted before a message is written in a chat conversation. If the
 163    message is changed, then the changed message is displayed and logged
 164    instead of the original message.
 165   @note
 166    Make sure to free @a *message before you replace it!
 167   @param account The account.
 168   @param who     The name of the user.
 169   @param message A pointer to the message.
 170   @param conv    The conversation.
 171   @param flags   Flags for this message.
 172   @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 173  @endsignaldef
 174
 175  @signaldef wrote-chat-msg
 176   @signalproto
 177 void (*wrote_chat_msg)(PurpleAccount *account, const char *who,
 178                        char *message, PurpleConversation *conv,
 179                        PurpleMessageFlags flags);
 180   @endsignalproto
 181   @signaldesc
 182    Emitted after a message is written and possibly displayed in a chat.
 183   @param account The account.
 184   @param who     The name of the user.
 185   @param message The message.
 186   @param conv    The conversation.
 187   @param flags   Flags for this message.
 188  @endsignaldef
 189
 190  @signaldef sending-chat-msg
 191   @signalproto
 192 void (*sending_chat_msg)(PurpleAccount *account, char **message, int id);
 193   @endsignalproto
 194   @signaldesc
 195    Emitted before sending a message to a chat. @a message is a pointer to the
 196    message string, so the plugin can replace the message before being sent.
 197   @note
 198    Make sure to free @a *message before you replace it!
 199   @param account The account the message is being sent on.
 200   @param message A pointer to the message that will be sent.
 201   @param id      The ID of the chat.
 202  @endsignaldef
 203
 204  @signaldef sent-chat-msg
 205   @signalproto
 206 void (*sent_chat_msg)(PurpleAccount *account, const char *message, int id);
 207   @endsignalproto
 208   @signaldesc
 209    Emitted after sending a message to a chat.
 210   @param account The account the message was sent on.
 211   @param message The message that was sent.
 212   @param id      The ID of the chat.
 213  @endsignaldef
 214
 215  @signaldef receiving-chat-msg
 216   @signalproto
 217 gboolean (*receiving_chat_msg)(PurpleAccount *account, char **sender,
 218                               char **message, PurpleConversation *conv, int *flags);
 219   @endsignalproto
 220   @signaldesc
 221    Emitted when a chat message is received. The callback can replace the
 222    name of the sender, the message, or the flags by modifying the pointer to the
 223    strings. This can also be used to cancel displaying a message by
 224    returning @c TRUE.
 225   @note
 226    Make sure to free @a *sender and @a *message before you replace them!
 227   @return @c TRUE if the message should be canceled, or @c FALSE otherwise.
 228   @param account The account the message was received on.
 229   @param sender  A pointer to the username of the sender.
 230   @param message A pointer to the message that was sent.
 231   @param conv    The chat conversation.
 232   @param flags   A pointer to the chat message flags
 233  @endsignaldef
 234
 235  @signaldef received-chat-msg
 236   @signalproto
 237 void (*received_chat_msg)(PurpleAccount *account, char *sender, char *message,
 238                               PurpleConversation *conv, PurpleMessageFlags flags);
 239   @endsignalproto
 240   @signaldesc
 241    Emitted after a chat message is received.
 242   @param account The account the message was received on.
 243   @param sender  The username of the sender.
 244   @param message The message that was sent.
 245   @param conv    The chat conversation.
 246   @param flags   The chat message flags.
 247  @endsignaldef
 248
 249  @signaldef conversation-created
 250   @signalproto
 251 void (*conversation_created)(PurpleConversation *conv);
 252   @endsignalproto
 253   @signaldesc
 254    Emitted when a new conversation is created.
 255   @param conv The new conversation.
 256  @endsignaldef
 257
 258  @signaldef conversation-updated
 259   @signalproto
 260 void (*conversation_updated)(PurpleConversation *conv,
 261                              PurpleConvUpdateType type);
 262   @endsignalproto
 263   @signaldesc
 264    Emitted when a conversation is updated.
 265   @param conv The conversation that was updated.
 266   @param type The type of update that was made.
 267  @endsignaldef
 268
 269  @signaldef deleting-conversation
 270   @signalproto
 271 void (*deleting_conversation)(PurpleConversation *conv);
 272   @endsignalproto
 273   @signaldesc
 274    Emitted just before a conversation is to be destroyed.
 275   @param conv The conversation that's about to be destroyed.
 276  @endsignaldef
 277
 278  @signaldef buddy-typing
 279   @signalproto
 280 void (*buddy_typing)(PurpleAccount *account, const char *name);
 281   @endsignalproto
 282   @signaldesc
 283    Emitted when a buddy starts typing in a conversation window.
 284   @param account The account of the user which is typing.
 285   @param name    The name of the user which is typing.
 286  @endsignaldef
 287
 288  @signaldef buddy-typing-stopped
 289   @signalproto
 290 void (*buddy_typing_stopped)(PurpleAccount *account, const char *name);
 291   @endsignalproto
 292   @signaldesc
 293    Emitted when a buddy stops typing in a conversation window.
 294   @param account The account of the user which stopped typing.
 295   @param name    The name of the user which stopped typing.
 296  @endsignaldef
 297
 298  @signaldef chat-buddy-joining
 299   @signalproto
 300 gboolean (*chat_buddy_joining)(PurpleConversation *conv, const char *name,
 301                            PurpleConvChatBuddyFlags flags);
 302   @endsignalproto
 303   @signaldesc
 304    Emitted when a buddy is joining a chat, before the list of
 305    users in the chat updates to include the new user.
 306   @return @c TRUE if the join should be hidden, or @c FALSE otherwise.
 307   @param conv The chat conversation.
 308   @param name The name of the user that is joining the conversation.
 309   @param flags The flags of the user that is joining the conversation.
 310  @endsignaldef
 311
 312  @signaldef chat-buddy-joined
 313   @signalproto
 314 void (*chat_buddy_joined)(PurpleConversation *conv, const char *name,
 315                           PurpleConvChatBuddyFlags flags,
 316                           gboolean new_arrival);
 317   @endsignalproto
 318   @signaldesc
 319    Emitted when a buddy joined a chat, after the users list is updated.
 320   @param conv The chat conversation.
 321   @param name The name of the user that has joined the conversation.
 322   @param flags The flags of the user that has joined the conversation.
 323   @param new_arrival If the buddy is a new arrival.
 324  @endsignaldef
 325
 326  @signaldef chat-join-failed
 327   @signalproto
 328 void (*chat_join_failed)(PurpleConnection *gc, GHashTable *components);
 329   @endsignalproto
 330   @signaldesc
 331    Emitted when an account fails to join a chat room
 332   @param gc The PurpleConnection of the account which failed to join the chat.
 333   @param data    The components passed to serv_join_chat() originally.
 334                  The hash function should be g_str_hash() and the equal
 335                  function should be g_str_equal().
 336  @endsignaldef
 337
 338  @signaldef chat-buddy-flags
 339   @signalproto
 340 void (*chat_buddy_flags)(PurpleConversation *conv, const char *name,
 341                          PurpleConvChatBuddyFlags oldflags,
 342                          PurpleConvChatBuddyFlags newflags);
 343   @endsignalproto
 344   @signaldesc
 345    Emitted when a user in a chat changes flags.
 346   @param conv The chat conversation.
 347   @param name The name of the user.
 348   @param oldflags The old flags.
 349   @param newflags The new flags.
 350  @endsignaldef
 351
 352  @signaldef chat-buddy-leaving
 353   @signalproto
 354 gboolean (*chat_buddy_leaving)(PurpleConversation *conv, const char *name,
 355                            const char *reason);
 356   @endsignalproto
 357   @signaldesc
 358    Emitted when a user is leaving a chat, before the user list is updated.
 359    This may include an optional reason why the user is leaving.
 360   @return @c TRUE if the leave should be hidden, or @c FALSE otherwise.
 361   @param conv   The chat conversation.
 362   @param name   The name of the user that is leaving the chat.
 363   @param reason The optional reason why the user is leaving.
 364  @endsignaldef
 365
 366  @signaldef chat-buddy-left
 367   @signalproto
 368 void (*chat_buddy_left)(PurpleConversation *conv, const char *name,
 369                         const char *reason);
 370   @endsignalproto
 371   @signaldesc
 372    Emitted when a user leaves a chat, after the user list is updated.
 373    This may include an optional reason why the user is leaving.
 374   @param conv   The chat conversation.
 375   @param name   The name of the user that left the chat.
 376   @param reason The optional reason why the user left the chat.
 377  @endsignaldef
 378
 379  @signaldef chat-inviting-user
 380   @signalproto
 381 void (*chat_inviting_user)(PurpleConversation *conv, const char *name,
 382                            char **invite_message);
 383   @endsignalproto
 384   @signaldesc
 385    Emitted when a user is being invited to the chat. The callback can
 386    replace the invite message to the invitee by modifying the pointer to
 387    the invite message.
 388   @note
 389    Make sure to free @a *invite_message before you replace it!
 390   @param conv           The chat conversation.
 391   @param name           The name of the user being invited.
 392   @param invite_message A pointer to the reason why a user is being
 393                         invited.
 394  @endsignaldef
 395
 396  @signaldef chat-invited-user
 397   @signalproto
 398 void (*chat_invited_user)(PurpleConversation *conv, const char *name,
 399                           const char *invite_message);
 400   @endsignalproto
 401   @signaldesc
 402    Emitted when a user invited another user to a chat.
 403   @param conv           The chat conversation.
 404   @param conv           The name of the user that was invited.
 405   @param invite_message The message to be sent to the user when invited.
 406  @endsignaldef
 407
 408  @signaldef chat-invited
 409   @signalproto
 410 gint (*chat_invited)(PurpleAccount *account, const char *inviter,
 411                      const char *chat, const char *invite_message
 412                      const GHashTable *components);
 413   @endsignalproto
 414   @signaldesc
 415    Emitted when an account was invited to a chat.
 416   @param account        The account being invited.
 417   @param inviter        The username of the person inviting the account.
 418   @param chat           The name of the chat you're being invited to.
 419   @param invite_message The optional invite message.
 420   @param components     The components necessary if you want to call
 421                         serv_join_chat()
 422   @return Less than zero if the invitation should be rejected, greater than
 423           zero if the invitation should be accepted. If zero is returned, the
 424           default behavior will be maintained: the user will be prompted.
 425  @endsignaldef
 426
 427  @signaldef chat-invite-blocked
 428   @signalproto
 429 void (*chat_invite_blocked)(PurpleAccount *account, const char *inviter,
 430                    const char *name, const char *message, GHashTable *data);
 431   @endsignalproto
 432   @signaldesc
 433    Emitted when an invitation to join a chat is blocked.
 434   @param account  The account the invitation was sent to.
 435   @param inviter  The name of the person sending the invitation.
 436   @param name     The name of the chat invited to.
 437   @param message  The invitation message sent.
 438   @param data     Hashtable containing data about the invited chat.
 439   @since 2.5.0
 440  @endsignaldef
 441
 442  @signaldef chat-joined
 443   @signalproto
 444 void (*chat_joined)(PurpleConversation *conv);
 445   @endsignalproto
 446   @signaldesc
 447    Emitted when an account joins a chat room.
 448   @param conv The conversation that joined the chat room.
 449  @endsignaldef
 450
 451  @signaldef chat-left
 452   @signalproto
 453 void (*chat_left)(PurpleConversation *conv);
 454   @endsignalproto
 455   @signaldesc
 456    Emitted when an account leaves a chat room.
 457   @param conv The conversation that left the chat room.
 458  @endsignaldef
 459
 460  @signaldef chat-topic-changed
 461   @signalproto
 462 void (*chat_topic_changed)(PurpleConversation *conv, const char *who, const char *topic);
 463   @endsignalproto
 464   @signaldesc
 465    Emitted when the topic is changed in a chat.
 466   @param conv  The conversation whose topic changed.
 467   @param who   The name of the person that changed the topic.
 468   @param topic The new topic.
 469  @endsignaldef
 470
 471  @signaldef conversation-extended-menu
 472   @signalproto
 473 void (*conversation_extended_menu)(PurpleConversation *conv, GList **list);
 474   @endsignalproto
 475   @signaldesc
 476    Emitted when the UI requests a list of plugin actions for a
 477    conversation.
 478   @param conv   The conversation.
 479   @param list   A pointer to the list of actions.
 480   @since 2.1.0
 481  @endsignaldef
 482
 483  @signaldef cleared-message-history
 484   @signalproto
 485 void (*cleared_message_history)(PurpleConversation *conv);
 486   @endsignalproto
 487   @signaldesc
 488     Emitted when the conversation history is cleared.
 489   @param conv   The conversation.
 490   @since 2.8.0
 491  @endsignaldef
 492
 493  @signaldef sent-attention
 494   @signalproto
 495 void (*got_attention)(PurpleAccount *account, const char *who,
 496         PurpleConversation *conv, guint type)
 497   @endsignalproto
 498   @signaldesc
 499     Emitted when receiving an attention message (buzz, nudge, etc.).
 500   @param account  The account
 501   @param who      The name of the person receiving the attention
 502   @param conv     The conversation
 503   @param type     The attention type (an index starting at 0)
 504   @since 2.7.0
 505  @endsignaldef
 506
 507  @signaldef got-attention
 508   @signalproto
 509 void (*got_attention)(PurpleAccount *account, const char *who,
 510         PurpleConversation *conv, guint type)
 511   @endsignalproto
 512   @signaldesc
 513     Emitted when receiving an attention message (buzz, nudge, etc.).
 514   @param account  The account
 515   @param who      The name of the person sending the attention
 516   @param conv     The conversation
 517   @param type     The attention type (an index starting at 0)
 518   @since 2.7.0
 519  @endsignaldef
 520 */
 521 // vim: syntax=c.doxygen tw=75 et