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