plugins/SIGNALS

   1 enum gaim_event {
   2         event_signon = 0,
   3         event_signoff,
   4         event_away,
   5         event_back,
   6         event_im_recv,
   7         event_im_send,
   8         event_buddy_signon,
   9         event_buddy_signoff,
  10         event_buddy_away,
  11         event_buddy_back,
  12         event_buddy_idle,
  13         event_buddy_unidle,
  14         event_blist_update,
  15         event_chat_invited,
  16         event_chat_join,
  17         event_chat_leave,
  18         event_chat_buddy_join,
  19         event_chat_buddy_leave,
  20         event_chat_recv,
  21         event_chat_send,
  22         event_warned,
  23         event_quit,
  24         event_new_conversation,
  25         event_set_info,
  26         event_draw_menu,
  27         event_im_displayed_sent,
  28         event_im_displayed_rcvd,
  29         event_chat_send_invite
  30 };
  31
  32 To add a signal handler, call the fuction gaim_signal_connect with the
  33 following arguments:
  34
  35 void *, enum gaim_event, void *, void *
  36
  37 The first arg is the handle that was passed to gaim_signal_init. You did
  38         save it, right?
  39 The second arg is hopefully obvious.
  40 The third arg is a pointer to a function that takes various args
  41         depending on which event you're dealing with.
  42 The fourth arg is any data you want to send to your function, as a final
  43         argument.
  44
  45 To remove a signal handler, call the function gaim_signal_disconnect with the
  46 following arguments:
  47
  48 void *, enum gaim_event, void *
  49
  50 The first arg is the handle that was passed to gaim_signal_init.
  51 The second arg is hopefully obvious.
  52 The third arg is a pointer to the function you attached.
  53
  54 Note that it deletes *all* functions matching the function you pass, not just
  55 one. Sorry, that's just the way it works.
  56
  57 So here are the args that get passed to your functions in various events:
  58
  59 event_signon:
  60         struct gaim_connection *gc
  61
  62         'gc' is the new connection.
  63
  64 event_signoff:
  65         struct gaim_connection *gc
  66
  67         'gc' is the connection that is about to go offline. This is called before
  68         serv_close is, so you still have a chance to get one last message out.
  69
  70 event_away:
  71         struct gaim_connection *gc, char *state, char *message
  72
  73         'gc' is the connection. Duh.
  74         'state' is confusing. We'll save that for now.
  75         'message' is the away message to be used.
  76
  77         Each protocol sets up what away states it can have. These are all char *,
  78         and when the connection goes away it uses one of those. That's what state
  79         is.
  80
  81         There's no way of telling from state and message whether you're actually
  82         away; it only gives state information, and a possible message.
  83
  84         However, the protocols also are very nice (usually) and will set gc->away
  85         if they're in an away-like state (e.g. Away or N/A for ICQ, etc). You can
  86         use that for a more rigid (read "boolean") way of checking away-ness.
  87
  88 event_back:
  89         (none)
  90
  91         This is deprecated and will not be called again. It will probably be
  92         removed eventually.
  93
  94 event_im_recv:
  95         struct gaim_connection *gc, char **who, char **text, guint32 flags
  96
  97         'gc' is the connection that received the message.
  98         'who' is the username of the person who sent the message.
  99         'text' is the actual strict text (with HTML tags and all) of the
 100                 message they sent.
 101         'flags' is message flags.
 102
 103         Note that you can modify these values. (You are encouraged to do so!)
 104         Note that *other* plugins can also modify these values, so you should
 105         check that they are not NULL, and try not to leave them as NULL.
 106
 107         gc was placed as the first arg as opposed to the third for intuitiveness.
 108         Unfortunately, it means that most plugins that use this event need to be
 109         slightly modified and then recompiled.
 110
 111         flags is actually a bit mask. AND with IM_FLAG_AWAY to see if they were
 112         away, etc.
 113
 114 event_im_send:
 115         struct gaim_connection *gc, char *who, char **text
 116
 117         'gc' is the connection that you are about to send the message through.
 118         'who' is the username of the person you're sending the message to.
 119         'text' is the actual strict text (with HTML tags and all) of the
 120                 message you're sending.
 121
 122         Note that you can modify outgoing text. The **text points to a g_malloc'd
 123         data chunk that contains the text. If your plugin changes it, it should
 124         either not add length to the string, or g_free *text and g_malloc a new
 125         segment. Since plugins can modify this, you should not try and remember it
 126         in your plugin.
 127
 128 event_buddy_signon:
 129         struct gaim_connection *gc, char *who
 130
 131         'who' is who signed on. (There is currently no way to see which connection
 132         reported that the buddy came online. Hopefully this will happen soon.)
 133
 134 event_buddy_signoff:
 135         struct gaim_connection *gc, char *who
 136
 137         'who' is who signed off.
 138
 139 event_buddy_away:
 140         struct gaim_connection *gc, char *who
 141
 142         'who' is who went away.
 143
 144 event_buddy_back:
 145         struct gaim_connection *gc, char *who
 146
 147         'who' is who is no longer away.
 148
 149 event_buddy_idle:
 150         struct gaim_connection *gc, char *who
 151
 152         'who' is who went idle.
 153
 154 event_buddy_unidle:
 155         struct gaim_connection *gc, char *who
 156
 157         'who' is who is no longer idle.
 158
 159 event_blist_update:
 160         (none)
 161
 162         called when the idle times are updated in the buddy list
 163
 164 event_chat_invited:
 165         struct gaim_connection *gc, char *who, char *room, char *message
 166
 167         'gc' is the connection that received the invitation.
 168         'who' is who invited you to a chat room.
 169         'room' is the room they invited you to.
 170         'message' is the (optional) message they sent to invite you, and may be
 171         an empty string.
 172
 173 event_chat_join:
 174         struct gaim_connection *gc, int id, char *room
 175
 176         'gc' is the connection that joined the room.
 177         'id' is the id of the room. See, each room is given an id unique
 178         within the connection. The struct conversation*'s in gc->buddy_chats
 179         have an 'id' field that's only used if it's is_chat member is TRUE.
 180         'id' is the *only* way to detect which chat room you actually mean,
 181         because the name of the chat room is not always unique (for example,
 182         MSN always uses "MSN Chat" as its name, since group chats in MSN
 183         don't actually have names).
 184         'room' is the chat room that you have just joined.
 185
 186 event_chat_leave:
 187         struct gaim_connection *gc, int
 188
 189         'gc' is the connection that joined the room.
 190         'id' is the id of the chat room that you have just left.
 191
 192 event_chat_buddy_join:
 193         struct gaim_connection *gc, int id, char *who
 194
 195         'gc' is the connection that the chat room is attached to.
 196         'id' is the id of the room the person joined.
 197         'who' is the screenname of the person who joined.
 198
 199         This is also triggered upon entering the room for every person in the
 200         room, including yourself. (E.g. if you join a room that already had 3
 201         people in it this will be called 4 times, once for each of them and
 202         once again for you. You will not always be the last one this is called
 203         for though.)
 204
 205 event_chat_buddy_leave:
 206         struct gaim_connection *gc, int id, char *who
 207
 208         'gc' is the connection that the chat room is attached to.
 209         'id' is the id of the room the person left.
 210         'who' is the screenname of the person who left.
 211
 212 event_chat_recv:
 213         struct gaim_connection *gc, int id, char *who, char *text
 214
 215         'gc' is the connection that received the message.
 216         'who' should be too.
 217         'text' is the message that got sent.
 218         'id' is the id of the room that received the message (see
 219         event_chat_join)
 220
 221         Note that because of the bizarre way chat works, you also receive
 222         messages that you send. I didn't design it, AOL did.
 223
 224 event_chat_send:
 225         struct gaim_connection *gc, int id, char **text
 226
 227         'gc' is the connection that the message is about to be sent on.
 228         'id' is the id of the room to which you're sending the message.
 229         'text' is what you're about to say, linkified/HTML-ized, but not
 230         TOC-escaped.
 231
 232         Be aware that you receive messages you send (as noted above). This
 233         event will be called before you actually send the message though.
 234         The **text pointer behaves the same as the **text pointer for the
 235         event_im_send event above; so read the note about it there.
 236
 237 event_warned:
 238         struct gaim_connection *gc, char *who, int level
 239
 240         'gc' is the account that got warned.
 241         'who' is who warned you. Note that this can be NULL, indicating either
 242         an anonymous warning, or your warning level has dropped.
 243         'level' is your new warning level.
 244
 245 event_quit:
 246         (none)
 247
 248         Called when gaim quits normally.  This can be called from either the
 249         signed on state or the signed off state (from either the Cancel button
 250         in the login window or the Quit option in the File menu on the buddy
 251         list). If gaim dies or is murdered, this won't be called. It's not my
 252         fault, it's Seg's.
 253
 254 event_new_conversation:
 255         char *who
 256
 257         'who' is who the conversation is with. This gets called when a new
 258         conversation window is created. You can use find_conversation(char *)
 259         to then find the struct conversation * and modify those values.
 260
 261 event_set_info:
 262         struct gaim_connection *gc, char *info
 263
 264         Called when the user sends his profile to the server.  'info' is the
 265         profile being sent.
 266
 267 event_draw_menu:
 268         GtkWidget *menu, char *name
 269
 270         Called when you right-click on a buddy.
 271
 272         'menu' is the menu that is about to be displayed.
 273         'name' is the name of the buddy that was clicked.
 274
 275 event_im_displayed_sent:
 276         struct gaim_connection *gc, char *who, char **what
 277
 278         This is called after what you send is displayed but before it's
 279         actually sent. That is, when the user clicks the "send" button
 280         in an IM window, first it gets passed to event_im_send handlers,
 281         then it gets displayed, then it gets passed to these handlers, and
 282         then it gets sent over the wire. This is useful for when you want
 283         to encrypt something on the way out.
 284
 285         'gc' is the connection the message is sent on.
 286         'who' is who the message is for.
 287         'what' is what was sent. It's expected that you modify this. If
 288         you set *what to NULL the message won't be sent, but the preferred
 289         way of doing this is to attach to event_im_send so that it really
 290         won't be displayed at all.
 291
 292 event_im_displayed_rcvd:
 293         struct gaim_connection *gc, char *who, char *what, guint32 flags
 294
 295         This is called after what you receive is displayed. This is useful
 296         for displaying an autoresponse after the message that triggered it.
 297         There are a bunch of things that are odd about this, especially
 298         when dealing with being away, so be careful.
 299
 300         'gc' is the connection the message was received on.
 301         'who' is who sent the message.
 302         'what' is what was sent.
 303         'flags' is flags on the message.
 304
 305 event_chat_send_invite:
 306         struct gaim_connection *gc, int id, char *who, char **msg
 307
 308         This is called just before you're about to invite someone. It's
 309         useful for if you want to pass someone a key so that they can
 310         participate in a group encrypted chat (ahem).
 311
 312         'gc' is the connection the invite is sent on.
 313         'id' is the id of the room you're inviting them to.
 314         'who' is who you're inviting.
 315         'msg' is the message they'll receive when they're invited. It may be
 316         NULL. Setting this to NULL won't stop the invitation from going thru.