# HG changeset patch # User Christian Hammond # Date 1064770434 0 # Node ID 2a72cb6c1c12214e0f24d1e98df36980c39cdaf9 # Parent e0c2320a0f017c91173f1017a45a7391ad83791c [gaim-migrate @ 7547] Nuke SIGNALS. committer: Tailor Script diff -r e0c2320a0f01 -r 2a72cb6c1c12 plugins/SIGNALS --- a/plugins/SIGNALS Sun Sep 28 16:32:28 2003 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,371 +0,0 @@ -enum gaim_event { - event_signon = 0, - event_signoff, - event_away, - event_back, - event_im_recv, - event_im_send, - event_buddy_signon, - event_buddy_signoff, - event_buddy_away, - event_buddy_back, - event_buddy_idle, - event_buddy_unidle, - event_blist_update, - event_chat_invited, - event_chat_join, - event_chat_leave, - event_chat_buddy_join, - event_chat_buddy_leave, - event_chat_recv, - event_chat_send, - event_warned, - event_quit, - event_new_conversation, - event_set_info, - event_draw_menu, - event_im_displayed_sent, - event_im_displayed_rcvd, - event_chat_send_invite, - event_got_typing, - event_del_conversation, - event_connecting, - event_switch_conversation, -}; - -To add a signal handler, call the fuction gaim_signal_connect with the -following arguments: - -void *, enum gaim_event, void *, void * - -The first arg is the handle that was passed to gaim_plugin_init. You did - save it, right? -The second arg is hopefully obvious. -The third arg is a pointer to a function that takes various args - depending on which event you're dealing with. -The fourth arg is any data you want to send to your function, as a final - argument. - -To remove a signal handler, call the function gaim_signal_disconnect with the -following arguments: - -void *, enum gaim_event, void * - -The first arg is the handle that was passed to gaim_signal_init. -The second arg is hopefully obvious. -The third arg is a pointer to the function you attached. - -Note that it deletes *all* functions matching the function you pass, not just -one. Sorry, that's just the way it works. - -So here are the args that get passed to your functions in various events: - -event_signon: - struct gaim_connection *gc - - 'gc' is the new connection. - -event_signoff: - struct gaim_connection *gc - - 'gc' is the connection that is about to go offline. This is called before - serv_close is, so you still have a chance to get one last message out. - -event_away: - struct gaim_connection *gc, char *state, char *message - - 'gc' is the connection. Duh. - 'state' is confusing. We'll save that for now. - 'message' is the away message to be used. - - Each protocol sets up what away states it can have. These are all char *, - and when the connection goes away it uses one of those. That's what state - is. - - There's no way of telling from state and message whether you're actually - away; it only gives state information, and a possible message. - - However, the protocols also are very nice (usually) and will set gc->away - if they're in an away-like state (e.g. Away or N/A for ICQ, etc). You can - use that for a more rigid (read "boolean") way of checking away-ness. - -event_back: - (none) - - This is deprecated and will not be called again. It will probably be - removed eventually. - -event_im_recv: - struct gaim_connection *gc, char **who, char **text, guint32 *flags - - 'gc' is the connection that received the message. - 'who' is the username of the person who sent the message. - 'text' is the actual strict text (with HTML tags and all) of the - message they sent. - 'flags' is message flags. - - Note that you can modify these values. (You are encouraged to do so!) - Note that *other* plugins can also modify these values, so you should - check that they are not NULL, and try not to leave them as NULL. - - gc was placed as the first arg as opposed to the third for intuitiveness. - Unfortunately, it means that most plugins that use this event need to be - slightly modified and then recompiled. - - flags is actually a bit mask. AND with IM_FLAG_AWAY to see if they were - away, etc. - -event_im_send: - struct gaim_connection *gc, char *who, char **text - - 'gc' is the connection that you are about to send the message through. - 'who' is the username of the person you're sending the message to. - 'text' is the actual strict text (with HTML tags and all) of the - message you're sending. - - Note that you can modify outgoing text. The **text points to a g_malloc'd - data chunk that contains the text. If your plugin changes it, it should - either not add length to the string, or g_free *text and g_malloc a new - segment. Since plugins can modify this, you should not try and remember it - in your plugin. - -event_buddy_signon: - struct gaim_connection *gc, char *who - - 'who' is who signed on. (There is currently no way to see which connection - reported that the buddy came online. Hopefully this will happen soon.) - -event_buddy_signoff: - struct gaim_connection *gc, char *who - - 'who' is who signed off. - -event_buddy_away: - struct gaim_connection *gc, char *who - - 'who' is who went away. - -event_buddy_back: - struct gaim_connection *gc, char *who - - 'who' is who is no longer away. - -event_buddy_idle: - struct gaim_connection *gc, char *who - - 'who' is who went idle. - -event_buddy_unidle: - struct gaim_connection *gc, char *who - - 'who' is who is no longer idle. - -event_blist_update: - (none) - - called when the idle times are updated in the buddy list - -event_chat_invited: - struct gaim_connection *gc, char *who, char *room, char *message - - 'gc' is the connection that received the invitation. - 'who' is who invited you to a chat room. - 'room' is the room they invited you to. - 'message' is the (optional) message they sent to invite you, and may be - an empty string. - -event_chat_join: - struct gaim_connection *gc, int id, char *room - - 'gc' is the connection that joined the room. - 'id' is the id of the room. See, each room is given an id unique - within the connection. The struct conversation*'s in gc->buddy_chats - have an 'id' field that's only used if it's is_chat member is TRUE. - 'id' is the *only* way to detect which chat room you actually mean, - because the name of the chat room is not always unique (for example, - MSN always uses "MSN Chat" as its name, since group chats in MSN - don't actually have names). - 'room' is the chat room that you have just joined. - -event_chat_leave: - struct gaim_connection *gc, int - - 'gc' is the connection that joined the room. - 'id' is the id of the chat room that you have just left. - -event_chat_buddy_join: - struct gaim_connection *gc, int id, char *who - - 'gc' is the connection that the chat room is attached to. - 'id' is the id of the room the person joined. - 'who' is the screenname of the person who joined. - - This is also triggered upon entering the room for every person in the - room, including yourself. (E.g. if you join a room that already had 3 - people in it this will be called 4 times, once for each of them and - once again for you. You will not always be the last one this is called - for though.) - -event_chat_buddy_leave: - struct gaim_connection *gc, int id, char *who - - 'gc' is the connection that the chat room is attached to. - 'id' is the id of the room the person left. - 'who' is the screenname of the person who left. - -event_chat_recv: - struct gaim_connection *gc, int id, char **who, char **text - - 'gc' is the connection that received the message. - 'who' should be too. - 'text' is the message that got sent. - 'id' is the id of the room that received the message (see - event_chat_join) - - Like event_im_recv, you are allowed and encouraged to change - these values - - Note that because of the bizarre way chat works, you also receive - messages that you send. I didn't design it, AOL did. - -event_chat_send: - struct gaim_connection *gc, int id, char **text - - 'gc' is the connection that the message is about to be sent on. - 'id' is the id of the room to which you're sending the message. - 'text' is what you're about to say, linkified/HTML-ized, but not - TOC-escaped. - - Be aware that you receive messages you send (as noted above). This - event will be called before you actually send the message though. - The **text pointer behaves the same as the **text pointer for the - event_im_send event above; so read the note about it there. - -event_warned: - struct gaim_connection *gc, char *who, int level - - 'gc' is the account that got warned. - 'who' is who warned you. Note that this can be NULL, indicating either - an anonymous warning, or your warning level has dropped. - 'level' is your new warning level. - -event_quit: - (none) - - Called when gaim quits normally. This can be called from either the - signed on state or the signed off state (from either the Cancel button - in the login window or the Quit option in the File menu on the buddy - list). If gaim dies or is murdered, this won't be called. It's not my - fault, it's Seg's. - -event_new_conversation: - char *who - - 'who' is who the conversation is with. This gets called when a new - conversation window is created. You can use find_conversation(char *) - to then find the struct conversation * and modify those values. - -event_set_info: - struct gaim_connection *gc, char *info - - Called when the user sends his profile to the server. 'info' is the - profile being sent. - -event_draw_menu: - GtkWidget *menu, char *name - - Called when you right-click on a buddy. - - 'menu' is the menu that is about to be displayed. - 'name' is the name of the buddy that was clicked. - -event_im_displayed_sent: - struct gaim_connection *gc, char *who, char **what - - This is called after what you send is displayed but before it's - actually sent. That is, when the user clicks the "send" button - in an IM window, first it gets passed to event_im_send handlers, - then it gets displayed, then it gets passed to these handlers, and - then it gets sent over the wire. This is useful for when you want - to encrypt something on the way out. - - 'gc' is the connection the message is sent on. - 'who' is who the message is for. - 'what' is what was sent. It's expected that you modify this. If - you set *what to NULL the message won't be sent, but the preferred - way of doing this is to attach to event_im_send so that it really - won't be displayed at all. - -event_im_displayed_rcvd: - struct gaim_connection *gc, char *who, char *what, guint32 flags, time_t time - - This is called after what you receive is displayed. This is useful - for displaying an autoresponse after the message that triggered it. - There are a bunch of things that are odd about this, especially - when dealing with being away, so be careful. - - 'gc' is the connection the message was received on. - 'who' is who sent the message. - 'what' is what was sent. - 'flags' is flags on the message. - 'time' is the time the message was received--it may be very different from the - time this signal gets called - -event_chat_send_invite: - struct gaim_connection *gc, int id, char *who, char **msg - - This is called just before you're about to invite someone. It's - useful for if you want to pass someone a key so that they can - participate in a group encrypted chat (ahem). - - 'gc' is the connection the invite is sent on. - 'id' is the id of the room you're inviting them to. - 'who' is who you're inviting. - 'msg' is the message they'll receive when they're invited. It may be - NULL. Setting this to NULL won't stop the invitation from going thru. - -event_got_typing: - struct gaim_connection *gc, char *who - - This is called when a buddy starts typing you and is called - differently depending on the protocol. MSN requires that a - conversation is already in progress, and may send more than - one notification while typing. OSCAR can receive typing - notifications in direct IMs, and Yahoo can receive them any - time. - - 'gc' is the connection the typing is sent to. - 'who' is the person typing to you. - -event_del_conversation: - struct conversation *c - - This is called when a conversation window is closed. It is - called before any memory is deallocated so you are able to - access any data related to the conversation without breaking - anything. - - 'c' is the conversation being closed. - -event_connecting: - struct gaim_account *u - - This is called when Gaim attempts to bring a user on-line. The - boolean u->connecting is set to true, and connecting_count - incremented. The attempt can end with event_signon or event_signoff - being called, depending upon whether the attempt was a sucess or - a failure. In both cases, u->connecting is set to false and the - counter decremented. - - 'u' is the account being connected. - -event_conversation_switch: - GaimConversation *c - - This is called when a new conversation has become the active conversation - in its GaimWindow. - - Using this in conjuction with GTK's focus-in-event will allow you to trigger - callbacks anytime a conversation receives focus. - - 'c' is the conversation that has just received focus.