Mercurial > pidgin.yaz
annotate plugins/PERL-HOWTO @ 1401:bf041349b11e
[gaim-migrate @ 1411]
abliity to set accounts away independent of each other. also allows for all the other states (like in yahoo and icq). probably breaks MSN, so don't use it until rob fixes it.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Wed, 10 Jan 2001 22:15:24 +0000 |
parents | 0ef4386edc29 |
children | dd78a230aa06 |
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 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
6 X-Chat's perl.c file, with small modifications to suit GAIM rather than IRC. |
750 | 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 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
24 things are the functions provided by gaim's internal GAIM module, which is |
750 | 25 what most of this document is about. So, onto the functions. |
26 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
27 GAIM::register(name, version, shutdownroutine, unused) |
750 | 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 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
33 GAIM::get_info(integer, ...) |
750 | 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). | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
37 1 - the list of currently online screennames |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
38 2 - given a screenname, the protocol(s) it(/they) use(s) (as ints) |
750 | 39 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
40 GAIM::print(title, message) |
750 | 41 This displays a nice little dialog window. |
42 | |
43 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
44 GAIM::buddy_list(name) |
750 | 45 This returns the buddy list (no groups, just the names of the buddies) |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
46 for the specified account |
750 | 47 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
48 GAIM::online_list(name) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
49 This returns the list of online buddies for the specified account. |
750 | 50 |
51 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
52 GAIM::command(command, ...) |
750 | 53 This sends commands to the server, and each command takes various |
54 arguments. The command should be self-explanatory: | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
55 "signon" - the second arg is the screenname to sign on |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
56 "signoff" - the optional second arg is who to sign off. if no args are |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
57 given, all names are signed off. |
750 | 58 "away" - the second arg is the away message |
59 "back" - no args. | |
60 "idle" - the second arg is how long (in seconds) to set the idle time | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
61 (this sets the idle time for all connections) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
62 "warn" - the second arg is the name of the person to warn. this is |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
63 especially evil since it warns the person from every connection. |
750 | 64 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
65 GAIM::user_info(nick) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
66 Returns 8 data items: |
750 | 67 the screenname of the buddy |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
68 the alias of the buddy |
750 | 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 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
86 Since buddy lists are per-connection this goes through the connections |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
87 until it finds a matching buddy name. |
750 | 88 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
89 GAIM::print_to_conv(who, what) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
90 The question is not what does this do, it's who does this do it as. The |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
91 answer is "whatever the default is". It uses whichever connection is |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
92 selected in the conversation window's menu. If the conversation window |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
93 didn't exist beforehand, then it's the default (first) connection. |
750 | 94 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
95 GAIM::print_to_chat(room, what) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
96 This goes through each connection. If it finds a room matching the name, |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
97 it'll print the message to that room. |
750 | 98 |
802
1afe98d2461e
[gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
785
diff
changeset
|
99 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
100 GAIM::add_event_handler(event, function) |
785
dc9ad68fc30e
[gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
750
diff
changeset
|
101 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
|
102 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
|
103 (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
|
104 string with the name of the function you want called. Simple enough? |
750 | 105 |
802
1afe98d2461e
[gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
785
diff
changeset
|
106 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
|
107 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
|
108 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
|
109 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
|
110 plugins have had their way with them. Perl scripts cannot modify the values |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
111 so that gaim knows what the changes are. |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
112 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
113 Perl scripts can short-circuit certain events (namely event_im_send, |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
114 event_im_recv, event_chat_send, and event_chat_recv). To short-circuit an |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
115 event simply return a non-0 value. This will cause all subsequent scripts |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
116 and the event itself to never happen (i.e. the user won't see it happen, |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
117 and _send events won't actually send). |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
118 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
119 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
|
120 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
|
121 better feel for this, or better yet, look at the bottom of plugins.c.) |
750 | 122 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
123 GAIM::add_timeout_handler(integer, function) |
750 | 124 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
|
125 once, so if you want to keep calling function, keep readding the handler. |