This is really the wrong place for a HOWTO on writing perl scripts for gaim, but there didn't seem to be a much better place. If you've ever written a perl script for X-Chat then you've basically written one for gaim as well. perl.c in gaim's source is basically an exact copy of X-Chat's perl.c file, with small modifications to suit Gaim rather than IRC. Basically the reason for including perl is based on the experience with the plugins. X-Chat's docs on Perl Scripting sums it up nicely: it's not quite as simple to stick a module together in C and make it stable compared to the development time of perl code Plugins are more powerful as they can directly access gaim's functions and variables; as such they should be used for things like modifying the UI or when something takes quite a bit of trickery not offered by perl. But for the most part things should be written in Perl. It's more stable than plugins. 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 what most of this document is about. So, onto the functions. 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. 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. 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(event, function) This is the most important of them all. This is basically exactly like gaim_signal_connect for plugins. You pass 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, and event_chat_recv). 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::add_timeout_handler(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.