annotate plugins/PERL-HOWTO @ 802:1afe98d2461e

[gaim-migrate @ 812] ha, i'm smart. i should commit to things. committer: Tailor Script <tailor@pidgin.im>
author Eric Warmenhoven <eric@warmenhoven.org>
date Wed, 30 Aug 2000 23:27:04 +0000
parents dc9ad68fc30e
children 67bdecdecbb7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
1 This is really the wrong place for a HOWTO on writing perl scripts for gaim,
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
2 but there didn't seem to be a much better place.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
3
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
4 If you've ever written a perl script for X-Chat then you've basically written
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
5 one for gaim as well. perl.c in gaim's source is basically an exact copy of
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
6 X-Chat's perl.c file, with small modifications to suit AIM rather than IRC.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
7
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
8 Basically the reason for including perl is based on the experience with the
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
9 plugins. X-Chat's docs on Perl Scripting sums it up nicely:
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
10 it's not quite as simple to stick a module together in C and make it
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
11 stable compared to the development time of perl code
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
12
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
13 Plugins are more powerful as they can directly access gaim's functions and
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
14 variables; as such they should be used for things like modifying the UI or
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
15 when something takes quite a bit of trickery not offered by perl. But for
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
16 the most part things should be written in Perl. It's more stable than
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
17 plugins.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
18
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
19 Everything available in normal perl scripts should be available in gaim's
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
20 perl interface, so I'm not going to bother describing that. The important
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
21 things are the functions provided by gaim's internal AIM module, which is
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
22 what most of this document is about. So, onto the functions.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
23
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
24 AIM::register(name, version, shutdownroutine, unused)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
25 Just like X-Chat. This is the first function your script should call.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
26 shutdownroutine is a function that will be called when the script
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
27 gets unloaded (like when gaim gets closed). This function returns
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
28 gaim's version number.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
29
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
30 AIM::get_info(integer)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
31 This function returns different information based on the integer passed
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
32 to it.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
33 0 - the version of gaim you're running ("0.10.0" for example).
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
34 1 - the screenname to last attempt to sign on
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
35 2 - either "Offline", "TOC", or "Oscar"
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
36
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
37 AIM::print(title, message)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
38 This displays a nice little dialog window.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
39
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
40
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
41 AIM::buddy_list()
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
42 This returns the buddy list (no groups, just the names of the buddies)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
43
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
44 AIM::online_list()
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
45 This returns the list of online buddies.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
46
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
47 AIM::deny_list()
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
48 This returns the deny list. This is probably going to be modified before
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
49 0.10.0 is released to return either the deny or the permit list and the
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
50 current mode.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
51
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
52
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
53 AIM::command(command, ...)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
54 This sends commands to the server, and each command takes various
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
55 arguments. The command should be self-explanatory:
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
56 "signon" - no args.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
57 "signoff" - no args.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
58 "away" - the second arg is the away message
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
59 "back" - no args.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
60 "idle" - the second arg is how long (in seconds) to set the idle time
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
61 "warn" - the second arg is the name of the person to warn
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
62
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
63 AIM::user_info(nick)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
64 Returns 7 data items:
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
65 the screenname of the buddy
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
66 "Online" or "Offline"
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
67 their warning level
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
68 signon time, in seconds since the epoch
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
69 idle time, in seconds (?)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
70 user class, an integer with bit values
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
71 AOL 1
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
72 ADMIN 2
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
73 UNCONFIRMED 4
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
74 NORMAL 8
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
75 AWAY 16
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
76 their capabilites, an integer with bit values
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
77 BUDDYICON 1
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
78 VOICE 2
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
79 IMIMAGE 4
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
80 CHAT 8
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
81 GETFILE 16
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
82 SENDFILE 32
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
83
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
84 This is probably going to change before 0.10.0 is released to
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
85 also return the alias of the buddy.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
86
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
87 AIM::print_to_conv(who, what)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
88 This should be obvious. If you can't figure this out on your own, you
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
89 shouldn't be using a computer.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
90
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
91 AIM::print_to_chat(room, what)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
92 This should be just as obvious as the last command.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
93
802
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
94
785
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
95 AIM::add_event_handler(event, function)
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
96 This is the most important of them all. This is basically exactly like
802
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
97 gaim_signal_connect for plugins. You pass which event you want to connect to
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
98 (a string with the same name as the events for plugins, see SIGNALS), and a
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
99 string with the name of the function you want called. Simple enough?
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
100
802
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
101 When this is triggered, the arguments will be passed in @_ and are not
785
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
102 broken into a list, but left as one long string. You'll have to parse those
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
103 yourself with split. (Sounding exactly like X-Chat yet?) The arguments are
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
104 the exact same as those passed to the plugins, and are passed after the
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
105 plugins have had their way with them. Perl scripts cannot modify the values
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
106 so that gaim knows what the changes are. Unlike X-Chat, perl scripts cannot
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
107 short-circut gaim (that is, your script will be called in order it was added,
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
108 despite what other scripts do, and afterwards, execution will continue as
802
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
109 normal). Names of buddies and chat rooms will be in quotes, and all other
1afe98d2461e [gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 785
diff changeset
110 values (like text messages) will not be.
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
111
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
112 AIM::add_timeout_handler(integer, function)
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
113 This calls function after integer number of seconds. It only calls function
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
114 once, so if you want to keep calling function, keep reading the handler.