annotate plugins/PERL-HOWTO @ 3952:07283934dedd

[gaim-migrate @ 4133] Ok, big commit with little functionality change. Most of it is me shuffling crap around because I'm one of them neat freaks. Lots of general code cleanup too. I'm trying to move to that whole "one-family-per-file" thing. The details... I added libfaim support for aim's new search family, 0x000f. I only tested this briefly, so if anyone uses it for anything, be aware that it could be buggy. I'll add oscar support sometime. Advantages of this family are... when you search for someone, you get the directory info for that person. So like, first name, middle name, last name, maiden name, city, state, country, zip, address, interests, nickname, and maybe some other stuff. Basically all the info that they've set in their directory info thing. Info. Oh, and I'm calling it "new search" because seach was already taken, and cookie monster ate my right brain. The reason I didn't add support to oscar.c... the new search family requires making a connection to another server. While moving stuff around I realized that I didn't really like how new connections are made. It's kind of sloppy. I'm thinking it would be nice to have an outgoing queue for each type of connection, and then let the client queue messages as much as they want. Then, if libfaim sees that there is a message for a certain type of connection, and there is no open connection of that type, it will connect, and then flush the queue when the connection is made. This seems a lot cleaner, but it also seems like a pain in the ass. I should do ssi for icq first, anyway :-) Also, I think it would be neat if there was an ICBM file that handled channels 1 through 4. Then im.c and chat.c could pass the ICBM part to the icbm stuff and it could get parsed there. im.c is really huge right now. I applied a patch from Graham Booker that paves the way for unicode in direct IMs. Thanks Graham. Now we just need Paco-Paco to git a little free time and write a patch for this. http://sourceforge.net/tracker/index.php?func=detail&aid=633589&group_id=235&atid=300235 I applied 2 patches from Will Mahan dealing with file transfer/oft/rendezous/whatever. Here's some info on them, from The Man himself: Patch 1 "Currently the Rendezvous code is rather messy; this patch attempts to bring it up to speed with the rest of the Oscar prpl. Its changes include: * Rewrite several ft.c functions to use bstreams. Apparently the code in question was written before bstreams were implemented. * Handle incoming Rendezvous packets through the rxqueue like FLAP packets, rather than handling them as a special case as soon as they are received. This takes advantage of the bstream cleanup to unify some code and simplify the aim_frame_t struct. * Change some names used to try to clarify the distinction between OFT, which refers specifically to file transfer, and Rendezvous, which encompasses OFT as well as other types of client-to-client connections." Patch 2 "* Add some comments I inadvertently left out of my last patch. * Fix a double-free that occurs when connections time out. * Correct a bug causing filenames to be truncated by 4 characters on some clients. * Preserve directory structure when sending multiple files. * Handle (throw away) resource forks sent by Mac clients." I also changed all indents to tabs in ft.c. And split all the bstream stuff from rxqueue.c and put it in bstream.c. It really is a separate thing. Especially since it can be used for outgoing connections. Also, I was going to look over the whole patch tonight to make sure it's all good, but it's like 6000 lines, so, uh, I'll do it later. committer: Tailor Script <[e-mail]>

So, you wanna write a perl script.

Perl scripts in Gaim can be very useful.  Although they can't directly manipulate
Gaim data like a plugin, or provide any sort of UI, they're portable, easy to develop
rapidly and extremely powerful when manipulating incoming and outgoing messages.

This document assumes you know perl--Gaim perl scripts work exactly like normal perl
scripts, with a few extra commands you can use.

The first thing Gaim will do with your plugin (provided it's in $prefix/lib/gaim or
$HOME/.gaim/) is look for and call a function called "description".  description()
gives Gaim the information it will use in the plugins dialog--script name, version,
your name--all sorts of good things.  Let's look at an example:

	sub description {
		my($a, $b, $c, $d, $e, $f) = @_;
		("Example", "1.0", "An example Gaim perl script that does nothing 
		particularly useful:\n\t-Show a dialog on load\n\t-Set user idle for 
		6,000 seconds\n\t-Greets people signing on with \"Hello\"\n\t-Informs 
		you when script has been loaded for one minute.", 
		"Eric Warmenhoven <eric\@warmenhoven.org>", "http://gaim.sf.net", 
		"/dev/null");
	}

This pushes what's needed to the perl stack.  What is all that stuff?
	$a - Name 
	$b - Version
	$c - Description
	$d - Authors
	$e - Webpage
	$f - Icon (this is the path to an icon Gaim will use for your script)

It should be noted that this information will be formatted according to Pango's
markup language--a language akin to HTML.  This is neat in that it lets you bold
and italicize your description and stuff, but it's important you take care to 
properly escape stuff (notice the < in $d).

Now, for the Gaim-specific perl functions (if you know x-chat scripts, you'll
feel right at home):

GAIM::register(name, version, shutdownroutine, unused)
	Just like X-Chat. This is the first function your script should call.
	shutdownroutine is a function that will be called when the script
	gets unloaded (like when gaim gets closed). This function returns
	gaim's version number.  This function MUST use the same Name and Version
	given in description()--the plugin won't work otherwise.  This returns a
	handle--you want to hold on to this.

	The handle is what Gaim will use to distinguish your script from any others
	running.  It's actually a string--the path to the script, but you'll probably
	never need to know that.  As long as you just hold on to it and don't change it
	everything should work fine.  You need it for GAIM::add_event_handler and 
	GAIM::add_timeout_handler.

GAIM::get_info(integer, ...)
	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 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
	7 - given a connection index, the name of the protocol (as a string)

GAIM::print(title, message)
	This displays a nice little dialog window.


GAIM::buddy_list(index)
	This returns the buddy list (no groups, just the names of the buddies)
	for the specified connection.

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 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
		 (this sets the idle time for all connections)
	"warn" - the second arg is the name of the person to warn. this is
		 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 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(index, nick)
	Returns 8 data items:
		the screenname of the buddy
		the alias of the buddy
		"Online" or "Offline"
		their warning level
		signon time, in seconds since the epoch
		idle time, in seconds (?)
		user class, an integer with bit values
			AOL		1
			ADMIN		2
			UNCONFIRMED	4
			NORMAL		8
			AWAY		16
		their capabilites, an integer with bit values
			BUDDYICON	1
			VOICE		2
			IMIMAGE		4
			CHAT		8
			GETFILE		16
			SENDFILE	32
	Since buddy lists are per-connection this goes through the connections
	until it finds a matching buddy name.

GAIM::write_to_conv(to, wflags, what, who)
	This displays a message into a conversation window. <wflags> is the
	message-style and works like that:
		wflags==0: display message as if received by <who>
		wflags==1: display message as if sent by <who>
		wflags==2: display system message

GAIM::serv_send_im(index, who, what, auto)
	Sends what from the connection index to who. :)

GAIM::print_to_conv(index, who, what, auto)
	Convenience function; combination of write_to_conv and serv_send_im.

GAIM::print_to_chat(index, room, what)
	Room is actually an int. Read SIGNALS to find out why.

GAIM::add_event_handler(handle, event, function)
	This is the most important of them all. This is basically exactly like
	gaim_signal_connect for plugins. You pass the handle returned by GAIM::register,
	which event you want to connect to (a string with the same name as the events for 
	plugins, see SIGNALS), and a string with the name of the function you want called. 
	Simple enough?

	When this is triggered, the arguments will be passed in @_ and are broken
	into a list. This is different from all previous versions of Gaim, where you
	had to parse the arguments yourself. The arguments are quite different from
	what's passed to the plugins, though they are very similar, and you should
	read perl.c to figure out what they are. The arguments are passed after the
	plugins have had their way with them. Perl scripts cannot modify the values
	so that gaim knows what the changes are.

	Perl scripts can short-circuit certain events (namely event_im_send,
	event_im_recv, event_chat_send, event_chat_recv and event_set_info). To
	short-circuit an event simply return a non-0 value. This will cause all
	subsequent scripts and the event itself to never happen (i.e. the user
	won't see it happen, and _send events won't actually send).

GAIM::remove_event_handler(event, function)
	This removes the event handler for the specified event that
	calls "function" as its handler.  The event handler must have been
	previously added with GAIM::add_event_handler.

GAIM::add_timeout_handler(handle, integer, function, args)
	This calls function after integer number of seconds. It only calls function
	once, so if you want to keep calling function, keep readding the handler.
	Args is a string that you'd like to have passed to your timeout handler; it's
	optional.  Handle is the handle returned by GAIM::register--it is not optional.

GAIM::play_sound(int sound)
	Plays a sound using whatever method the user has selected. The argument is
	one of the following numbers:

	0	Buddy logs in
	1	Buddy logs out
	2	Message received
	3	Message received begins conversation
	4	Message sent
	5	Person enters chat
	6	Person leaves chat
	7	You talk in chat
	8	Others talk in chat
	9	Default buddy pounce sound
	10	Someone says your name in chat