Mercurial > pidgin

--- a/plugins/PERL-HOWTO	Sun Aug 24 04:22:06 2003 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,169 +0,0 @@
-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 &lt;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 &lt; 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 (?)
-	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