Mercurial > pidgin
annotate plugins/PERL-HOWTO @ 2232:14e8978f86bb
[gaim-migrate @ 2242]
heh.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Fri, 07 Sep 2001 08:58:24 +0000 |
parents | bf35d7227592 |
children | e243bf60f2d6 |
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 |
1734
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
63 especially evil since it warns the person from every |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
64 connection. The third argument is 1 if you want to warn |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
65 anonymously. If 0 or ommitted, it will warn normally. |
1776
bf35d7227592
[gaim-migrate @ 1786]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1734
diff
changeset
|
66 "info" - the second arg is what you want to set your profile to. |
750 | 67 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
68 GAIM::user_info(nick) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
69 Returns 8 data items: |
750 | 70 the screenname of the buddy |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
71 the alias of the buddy |
750 | 72 "Online" or "Offline" |
73 their warning level | |
74 signon time, in seconds since the epoch | |
75 idle time, in seconds (?) | |
76 user class, an integer with bit values | |
77 AOL 1 | |
78 ADMIN 2 | |
79 UNCONFIRMED 4 | |
80 NORMAL 8 | |
81 AWAY 16 | |
82 their capabilites, an integer with bit values | |
83 BUDDYICON 1 | |
84 VOICE 2 | |
85 IMIMAGE 4 | |
86 CHAT 8 | |
87 GETFILE 16 | |
88 SENDFILE 32 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
89 Since buddy lists are per-connection this goes through the connections |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
90 until it finds a matching buddy name. |
750 | 91 |
1734
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
92 GAIM::print_to_conv(who, what, auto) |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
93 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
|
94 answer is "whatever the default is". It uses whichever connection is |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
95 selected in the conversation window's menu. If the conversation window |
1734
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
96 didn't exist beforehand, then it's the default (first) connection. If |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
97 auto is one, it will send as an auto (read: away) message. If 0 or |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
98 ommitted, it will send normally. |
750 | 99 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
100 GAIM::print_to_chat(room, what) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
101 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
|
102 it'll print the message to that room. |
750 | 103 |
802
1afe98d2461e
[gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
785
diff
changeset
|
104 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
105 GAIM::add_event_handler(event, function) |
785
dc9ad68fc30e
[gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
750
diff
changeset
|
106 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
|
107 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
|
108 (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
|
109 string with the name of the function you want called. Simple enough? |
750 | 110 |
802
1afe98d2461e
[gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
785
diff
changeset
|
111 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
|
112 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
|
113 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
|
114 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
|
115 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
|
116 so that gaim knows what the changes are. |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
117 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
118 Perl scripts can short-circuit certain events (namely event_im_send, |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
119 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
|
120 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
|
121 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
|
122 and _send events won't actually send). |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
123 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
124 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
|
125 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
|
126 better feel for this, or better yet, look at the bottom of plugins.c.) |
750 | 127 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
128 GAIM::add_timeout_handler(integer, function) |
750 | 129 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
|
130 once, so if you want to keep calling function, keep readding the handler. |