# HG changeset patch # User Christian Hammond # Date 1061698969 0 # Node ID cf2cdf3f0abca870bd1c956497aa633a28b520ba # Parent 2f6850c7d98076bd0b6cf86c5a80aa3893610561 [gaim-migrate @ 7123] Removed the old PERL-HOWTO committer: Tailor Script diff -r 2f6850c7d980 -r cf2cdf3f0abc plugins/PERL-HOWTO --- 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 <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 (?) - 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. is the - message-style and works like that: - wflags==0: display message as if received by - wflags==1: display message as if sent by - 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