[Gaim-commits] CVS: gaim/plugins PERL-HOWTO,1.8,1.9 SIGNALS,1.24,1.25

[Eric W. <war...@us...>]

Update of /cvsroot/gaim/gaim/plugins
In directory usw-pr-cvs1:/tmp/cvs-serv3080/plugins

Modified Files:
	PERL-HOWTO SIGNALS 
Log Message:
you say potato, i say potato
you say tomato, i say tomato
potato, potato
tomato, tomato
let's call the whole thing off.

*sigh*. it just doesn't work as well when it's typed. but you wouldn't want to hear me sing it.


Index: PERL-HOWTO
===================================================================
RCS file: /cvsroot/gaim/gaim/plugins/PERL-HOWTO,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- PERL-HOWTO	2001/09/10 22:27:47	1.8
+++ PERL-HOWTO	2001/09/22 09:14:27	1.9
@@ -19,6 +19,11 @@
 There's a really quick simple perl script in this directory, gaim.pl, that
 should show most of the functions. Most things should be self-explanatory.
 
+There's one thing you need to be aware of in perl scripts for gaim. Gaim
+supports multiple connections, and perl deals with them by using a unique
+identifier for each of them (that's a fancy way of saying that perl scripts
+use the memory address of the connection). 
+
 Everything available in normal perl scripts should be available in gaim's
 perl interface, so I'm not going to bother describing that. The important
 things are the functions provided by gaim's internal GAIM module, which is
@@ -34,27 +39,31 @@
 	This function returns different information based on the integer passed
 	to it.
 	0 - the version of gaim you're running ("0.10.0" for example).
-	1 - the list of currently online screennames
-	2 - given a screenname, the protocol(s) it(/they) use(s) (as ints)
+	1 - the list of connection ids
+	2 - given a connection index, the protocol it uses (as an int)
+	3 - given a connection index, the screenname of the person
+	4 - given a connection index, the index in the users list
+	5 - the list of names of users
+	6 - the list of protocols of the users
 
 GAIM::print(title, message)
 	This displays a nice little dialog window.
 
 
-GAIM::buddy_list(name)
+GAIM::buddy_list(index)
 	This returns the buddy list (no groups, just the names of the buddies)
-	for the specified account
+	for the specified connection.
 
-GAIM::online_list(name)
-	This returns the list of online buddies for the specified account.
+GAIM::online_list(index)
+	This returns the list of online buddies for the specified connection.
 
 
 GAIM::command(command, ...)
 	This sends commands to the server, and each command takes various
 	arguments. The command should be self-explanatory:
-	"signon" - the second arg is the screenname to sign on
-	"signoff" - the optional second arg is who to sign off. if no args are
-		    given, all names are signed off.
+	"signon" - the second arg is the index of the user to sign on
+	"signoff" - the optional second arg is the connection index to sign off.
+		    if no args are given, all connections are signed off.
 	"away" - the second arg is the away message
 	"back" - no args.
 	"idle" - the second arg is how long (in seconds) to set the idle time
@@ -63,9 +72,10 @@
 		 especially evil since it warns the person from every 
 		 connection.  The third argument is 1 if you want to warn
 		 anonymously.  If 0 or ommitted, it will warn normally.
-	"info" - the second arg is what you want to set your profile to.
+	"info" - the second arg is the connection index whose info you want to set,
+	         and the third arg is what you want to set your profile to.
 
-GAIM::user_info(nick)
+GAIM::user_info(index, nick)
 	Returns 8 data items:
 		the screenname of the buddy
 		the alias of the buddy
@@ -96,20 +106,14 @@
 		wflags==1: display message as if sent by <who>
 		wflags==2: display system message
 
-GAIM::print_to_conv(who, what, auto)
-	The question is not what does this do, it's who does this do it as. The
-	answer is "whatever the default is". It uses whichever connection is
-	selected in the conversation window's menu. If the conversation window
-	didn't exist beforehand, then it's the default (first) connection.  If
-	auto is one, it will send as an auto (read: away) message.  If 0 or
-	ommitted, it will send normally.
+GAIM::serv_send_im(index, who, what, auto)
+	Sends what from the connection index to who. :)
 
-GAIM::print_to_chat(room, what)
-	This goes through each connection. If it finds a room matching the name,
-	it'll print the message to that room.
+GAIM::print_to_conv(index, who, what, auto)
+	Convenience function; combination of write_to_conv and serv_send_im.
 
-GAIM::serv_send_im(who, what, auto)
-	Same as print_to_conv, but it does not display the message.
+GAIM::print_to_chat(index, room, what)
+	Room is actually an int. Read SIGNALS to find out why.
 
 GAIM::add_event_handler(event, function)
 	This is the most important of them all. This is basically exactly like

Index: SIGNALS
===================================================================
RCS file: /cvsroot/gaim/gaim/plugins/SIGNALS,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -d -r1.24 -r1.25
--- SIGNALS	2001/09/12 21:29:32	1.24
+++ SIGNALS	2001/09/22 09:14:27	1.25
@@ -20,13 +20,13 @@
 	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
+	event_im_displayed_rcvd,
+	event_chat_send_invite
 };
 
 To add a signal handler, call the fuction gaim_signal_connect with the
@@ -171,22 +171,29 @@
 	an empty string.
 
 event_chat_join:
-	struct gaim_connection *gc, char *room
+	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, char *room
+	struct gaim_connection *gc, int
 
 	'gc' is the connection that joined the room.
-	'room' is the chat room that you have just left.
+	'id' is the id of the chat room that you have just left.
 
 event_chat_buddy_join:
-	struct gaim_connection *gc, char *room, char *who
+	struct gaim_connection *gc, int id, char *who
 
 	'gc' is the connection that the chat room is attached to.
-	'room' is the room the person joined.
+	'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
@@ -196,28 +203,29 @@
 	for though.)
 
 event_chat_buddy_leave:
-	struct gaim_connection *gc, char *room, char *who
+	struct gaim_connection *gc, int id, char *who
 
 	'gc' is the connection that the chat room is attached to.
-	'room' is the room the person left.
+	'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, char *room, char *who, char *text
+	struct gaim_connection *gc, int id, 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.
+	'id' is the id of the room that received the message (see
+	event_chat_join)
 
 	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
+	struct gaim_connection *gc, int id, char **text
 
 	'gc' is the connection that the message is about to be sent on.
-	'room'. Need I say more.
+	'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.
 
@@ -234,15 +242,6 @@
 	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)
 
@@ -302,3 +301,15 @@
 	'who' is who sent the message.
 	'what' is what was sent.
 	'flags' is flags on the message.
+
+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.