annotate plugins/SIGNALS @ 836:15d005f8baaf

[gaim-migrate @ 846] better at informing the user of error now 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_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
};

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:
	(none)

	Note that you can get the username (which would probably be the only
	useful information here) from other places. (Read gaim.h for details.)

event_signoff:
	(none)

event_away:
	(none)

	Note that the away message that's being used can be retrieved from a
	global variable. (Read gaim.h for details.)

event_back:
	(none)

event_im_recv:
	char **who, char **text

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

event_im_send:
	char *who, char **text

	'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. (You are _not_ encouraged to
		do so ;-) .)

event_buddy_signon:
	char *who
	
	'who' is who signed on.

event_buddy_signoff:
	char *who

	'who' is who signed off.

event_buddy_away:
	char *who

	'who' is who went away.

event_buddy_back:
	char *who

	'who' is who is no longer away.

event_blist_update:
	(none)
	
	This event is called when the buddylist is updated (automatically every
	20 seconds)

event_chat_invited:
	char *who, char *room, char *message

	'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:
	char *room

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

event_chat_leave:
	char *room

	'room' is the chat room that you have just left.

event_chat_buddy_join:
	char *room, char *who

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

	'room' is the room the person left.
	'who' is the screenname of the person who left.

event_chat_recv:
	char *room, char *who, char *text

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

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

event_warned:
	char *who, int level

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