Mercurial > pidgin

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