annotate plugins/SIGNALS @ 2138:cfa83a1b3d49

[gaim-migrate @ 2148] hopefully fixes any problems we might have with icq. also makes it so we can receive messages from people whose names are longer than 64 characters. this should be arbitrary. committer: Tailor Script <[e-mail]>

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_error,
	event_quit,
	event_new_conversation,
	event_set_info,
	event_draw_menu,
	event_im_displayed_sent,
	event_im_displayed_rcvd
};

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_signal_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

	'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.
	
	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.

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, char *room

	'gc' is the connection that joined the room.
	'room' is the chat room that you have just joined.

event_chat_leave:
	struct gaim_connection *gc, char *room

	'gc' is the connection that joined the room.
	'room' is the chat room that you have just left.

event_chat_buddy_join:
	struct gaim_connection *gc, char *room, char *who

	'gc' is the connection that the chat room is attached to.
	'room' is 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, char *room, char *who

	'gc' is the connection that the chat room is attached to.
	'room' is the room the person left.
	'who' is the screenname of the person who left.

event_chat_recv:
	struct gaim_connection *gc, char *room, char *who, char *text

	'gc' is the connection that received the message.
	'room' should be obvious by now.
	'who' should be too.
	'text' is the message that got sent.

	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, char *room, char **text

	'gc' is the connection that the message is about to be sent on.
	'room'. Need I say more.
	'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_error:
	int error

	'error' is the number of the error as defined by the TOC PROTOCOL
	document, which can be found in the docs/ directory of the source
	tree. Note that if the person is using Oscar, this number is often
	plain wrong, and this event may not always be triggered on error.
	Experiment to find what is reliable.

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

	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.