Mercurial > pidgin.yaz
view plugins/PERL-HOWTO @ 5205:fefad67de2c7
[gaim-migrate @ 5573]
I had a damn good commit message, but it was eaten. Let's try it again.
Announcing, Gaim Plugin API version 2.0, or GPAPIV2.0 for short.
There are lots'a cool thingies here.
Okay now, this isn't as cool as the previous message, but:
1) There's now a single entry function for all plugin types. It returns a
detailed information structure on the plugin. This removes a lot of the
ugliness from old plugins. Oh yeah, libicq wasn't converted to this, so
if you use it, well, you shouldn't have used it anyway, but now you
can't! bwahahaha. Use AIM/ICQ.
2) There are now 3 types of plugins: Standard, Loader, and Protocol
plugins.
Standard plugins are, well, standard, compiled plugins.
Loader plugins load other plugins. For example, the perl support is now
a loader plugin. It loads perl scripts. In the future, we'll have
Ruby and Python loader plugins.
Protocol plugins are, well, protocol plugins... yeah...
3) Plugins have unique IDs, so they can be referred to or automatically
updated from a plugin database in the future. Neat, huh?
4) Plugins will have dependency support in the future, and can be hidden,
so if you have, say, a logging core plugin, it won't have to show up,
but then you load the GTK+ logging plugin and it'll auto-load the core
plugin. Core/UI split plugins!
5) There will eventually be custom plugin signals and RPC of some sort, for
the core/ui split plugins.
So, okay, back up .gaimrc.
I'd like to thank my parents for their support, javabsp for helping convert
a bunch of protocol plugins, and Etan for helping convert a bunch of
standard plugins.
Have fun. If you have any problems, please let me know, but you probably
won't have anything major happen. You will have to convert your plugins,
though, and I'm not guaranteeing that all perl scripts will still work.
I'll end up changing the perl script API eventually, so I know they won't
down the road. Don't worry, though. It'll be mass cool.
faceprint wants me to just commit the damn code already. So, here we go!!!
..
..
I need a massage. From a young, cute girl. Are there any young, cute girls
in the audience? IM me plz k thx.
committer: Tailor Script <tailor@pidgin.im>
author | Christian Hammond <chipx86@chipx86.com> |
---|---|
date | Fri, 25 Apr 2003 06:47:33 +0000 |
parents | 283fb289c510 |
children |
line wrap: on
line source
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. <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