plugins/PERL-HOWTO

   1 So, you wanna write a perl script.
   2
   3 Perl scripts in Gaim can be very useful.  Although they can't directly manipulate
   4 Gaim data like a plugin, or provide any sort of UI, they're portable, easy to develop
   5 rapidly and extremely powerful when manipulating incoming and outgoing messages.
   6
   7 This document assumes you know perl--Gaim perl scripts work exactly like normal perl
   8 scripts, with a few extra commands you can use.
   9
  10 The first thing Gaim will do with your plugin (provided it's in $prefix/lib/gaim or
  11 $HOME/.gaim/) is look for and call a function called "description".  description()
  12 gives Gaim the information it will use in the plugins dialog--script name, version,
  13 your name--all sorts of good things.  Let's look at an example:
  14
  15         sub description {
  16                 my($a, $b, $c, $d, $e, $f) = @_;
  17                 ("Example", "1.0", "An example Gaim perl script that does nothing
  18                 particularly useful:\n\t-Show a dialog on load\n\t-Set user idle for
  19                 6,000 seconds\n\t-Greets people signing on with \"Hello\"\n\t-Informs
  20                 you when script has been loaded for one minute.",
  21                 "Eric Warmenhoven &lt;eric\@warmenhoven.org>", "http://gaim.sf.net",
  22                 "/dev/null");
  23         }
  24
  25 This pushes what's needed to the perl stack.  What is all that stuff?
  26         $a - Name
  27         $b - Version
  28         $c - Description
  29         $d - Authors
  30         $e - Webpage
  31         $f - Icon (this is the path to an icon Gaim will use for your script)
  32
  33 It should be noted that this information will be formatted according to Pango's
  34 markup language--a language akin to HTML.  This is neat in that it lets you bold
  35 and italicize your description and stuff, but it's important you take care to
  36 properly escape stuff (notice the &lt; in $d).
  37
  38 Now, for the Gaim-specific perl functions (if you know x-chat scripts, you'll
  39 feel right at home):
  40
  41 GAIM::register(name, version, shutdownroutine, unused)
  42         Just like X-Chat. This is the first function your script should call.
  43         shutdownroutine is a function that will be called when the script
  44         gets unloaded (like when gaim gets closed). This function returns
  45         gaim's version number.  This function MUST use the same Name and Version
  46         given in description()--the plugin won't work otherwise.  This returns a
  47         handle--you want to hold on to this.
  48
  49         The handle is what Gaim will use to distinguish your script from any others
  50         running.  It's actually a string--the path to the script, but you'll probably
  51         never need to know that.  As long as you just hold on to it and don't change it
  52         everything should work fine.  You need it for GAIM::add_event_handler and
  53         GAIM::add_timeout_handler.
  54
  55 GAIM::get_info(integer, ...)
  56         This function returns different information based on the integer passed
  57         to it.
  58         0 - the version of gaim you're running ("0.10.0" for example).
  59         1 - the list of connection ids
  60         2 - given a connection index, the protocol it uses (as an int)
  61         3 - given a connection index, the screenname of the person
  62         4 - given a connection index, the index in the users list
  63         5 - the list of names of users
  64         6 - the list of protocols of the users
  65         7 - given a connection index, the name of the protocol (as a string)
  66
  67 GAIM::print(title, message)
  68         This displays a nice little dialog window.
  69
  70
  71 GAIM::buddy_list(index)
  72         This returns the buddy list (no groups, just the names of the buddies)
  73         for the specified connection.
  74
  75 GAIM::online_list(index)
  76         This returns the list of online buddies for the specified connection.
  77
  78
  79 GAIM::command(command, ...)
  80         This sends commands to the server, and each command takes various
  81         arguments. The command should be self-explanatory:
  82         "signon" - the second arg is the index of the user to sign on
  83         "signoff" - the optional second arg is the connection index to sign off.
  84                     if no args are given, all connections are signed off.
  85         "away" - the second arg is the away message
  86         "back" - no args.
  87         "idle" - the second arg is how long (in seconds) to set the idle time
  88                  (this sets the idle time for all connections)
  89         "warn" - the second arg is the name of the person to warn. this is
  90                  especially evil since it warns the person from every
  91                  connection.  The third argument is 1 if you want to warn
  92                  anonymously.  If 0 or ommitted, it will warn normally.
  93         "info" - the second arg is the connection index whose info you want to set,
  94                  and the third arg is what you want to set your profile to.
  95
  96 GAIM::user_info(index, nick)
  97         Returns 8 data items:
  98                 the screenname of the buddy
  99                 the alias of the buddy
 100                 "Online" or "Offline"
 101                 their warning level
 102                 signon time, in seconds since the epoch
 103                 idle time, in seconds (?)
 104                 user class, an integer with bit values
 105                         AOL             1
 106                         ADMIN           2
 107                         UNCONFIRMED     4
 108                         NORMAL          8
 109                         AWAY            16
 110                 their capabilites, an integer with bit values
 111                         BUDDYICON       1
 112                         VOICE           2
 113                         IMIMAGE         4
 114                         CHAT            8
 115                         GETFILE         16
 116                         SENDFILE        32
 117         Since buddy lists are per-connection this goes through the connections
 118         until it finds a matching buddy name.
 119
 120 GAIM::write_to_conv(to, wflags, what, who)
 121         This displays a message into a conversation window. <wflags> is the
 122         message-style and works like that:
 123                 wflags==0: display message as if received by <who>
 124                 wflags==1: display message as if sent by <who>
 125                 wflags==2: display system message
 126
 127 GAIM::serv_send_im(index, who, what, auto)
 128         Sends what from the connection index to who. :)
 129
 130 GAIM::print_to_conv(index, who, what, auto)
 131         Convenience function; combination of write_to_conv and serv_send_im.
 132
 133 GAIM::print_to_chat(index, room, what)
 134         Room is actually an int. Read SIGNALS to find out why.
 135
 136 GAIM::add_event_handler(handle, event, function)
 137         This is the most important of them all. This is basically exactly like
 138         gaim_signal_connect for plugins. You pass the handle returned by GAIM::register,
 139         which event you want to connect to (a string with the same name as the events for
 140         plugins, see SIGNALS), and a string with the name of the function you want called.
 141         Simple enough?
 142
 143         When this is triggered, the arguments will be passed in @_ and are broken
 144         into a list. This is different from all previous versions of Gaim, where you
 145         had to parse the arguments yourself. The arguments are quite different from
 146         what's passed to the plugins, though they are very similar, and you should
 147         read perl.c to figure out what they are. The arguments are passed after the
 148         plugins have had their way with them. Perl scripts cannot modify the values
 149         so that gaim knows what the changes are.
 150
 151         Perl scripts can short-circuit certain events (namely event_im_send,
 152         event_im_recv, event_chat_send, event_chat_recv and event_set_info). To
 153         short-circuit an event simply return a non-0 value. This will cause all
 154         subsequent scripts and the event itself to never happen (i.e. the user
 155         won't see it happen, and _send events won't actually send).
 156
 157 GAIM::remove_event_handler(event, function)
 158         This removes the event handler for the specified event that
 159         calls "function" as its handler.  The event handler must have been
 160         previously added with GAIM::add_event_handler.
 161
 162 GAIM::add_timeout_handler(handle, integer, function, args)
 163         This calls function after integer number of seconds. It only calls function
 164         once, so if you want to keep calling function, keep readding the handler.
 165         Args is a string that you'd like to have passed to your timeout handler; it's
 166         optional.  Handle is the handle returned by GAIM::register--it is not optional.
 167
 168 GAIM::play_sound(int sound)
 169         Plays a sound using whatever method the user has selected. The argument is
 170         one of the following numbers:
 171
 172         0       Buddy logs in
 173         1       Buddy logs out
 174         2       Message received
 175         3       Message received begins conversation
 176         4       Message sent
 177         5       Person enters chat
 178         6       Person leaves chat
 179         7       You talk in chat
 180         8       Others talk in chat
 181         9       Default buddy pounce sound
 182         10      Someone says your name in chat