Mercurial > pidgin
annotate plugins/PERL-HOWTO @ 3554:cf00549c53d7
[gaim-migrate @ 3644]
A long annoying patch by one Robert McQueen.
committer: Tailor Script <tailor@pidgin.im>
author | Sean Egan <seanegan@gmail.com> |
---|---|
date | Thu, 26 Sep 2002 15:23:33 +0000 |
parents | cd938f18f3f8 |
children | e120097bbd72 |
rev | line source |
---|---|
3551 | 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. | |
750 | 6 |
3551 | 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. | |
750 | 9 |
3551 | 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: | |
750 | 14 |
3551 | 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 <eric\@warmenhoven.org>", "http://gaim.sf.net", | |
22 "/dev/null"); | |
23 } | |
806
67bdecdecbb7
[gaim-migrate @ 816]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
802
diff
changeset
|
24 |
3551 | 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) | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
32 |
3551 | 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 < in $d). | |
37 | |
38 Now, for the Gaim-specific perl functions (if you know x-chat scripts, you'll | |
39 feel right at home): | |
750 | 40 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
41 GAIM::register(name, version, shutdownroutine, unused) |
750 | 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. | |
46 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
47 GAIM::get_info(integer, ...) |
750 | 48 This function returns different information based on the integer passed |
49 to it. | |
50 0 - the version of gaim you're running ("0.10.0" for example). | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
51 1 - the list of connection ids |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
52 2 - given a connection index, the protocol it uses (as an int) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
53 3 - given a connection index, the screenname of the person |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
54 4 - given a connection index, the index in the users list |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
55 5 - the list of names of users |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
56 6 - the list of protocols of the users |
2355
571971659533
[gaim-migrate @ 2368]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2345
diff
changeset
|
57 7 - given a connection index, the name of the protocol (as a string) |
750 | 58 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
59 GAIM::print(title, message) |
750 | 60 This displays a nice little dialog window. |
61 | |
62 | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
63 GAIM::buddy_list(index) |
750 | 64 This returns the buddy list (no groups, just the names of the buddies) |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
65 for the specified connection. |
750 | 66 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
67 GAIM::online_list(index) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
68 This returns the list of online buddies for the specified connection. |
750 | 69 |
70 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
71 GAIM::command(command, ...) |
750 | 72 This sends commands to the server, and each command takes various |
73 arguments. The command should be self-explanatory: | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
74 "signon" - the second arg is the index of the user to sign on |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
75 "signoff" - the optional second arg is the connection index to sign off. |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
76 if no args are given, all connections are signed off. |
750 | 77 "away" - the second arg is the away message |
78 "back" - no args. | |
79 "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
|
80 (this sets the idle time for all connections) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
81 "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
|
82 especially evil since it warns the person from every |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
83 connection. The third argument is 1 if you want to warn |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
84 anonymously. If 0 or ommitted, it will warn normally. |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
85 "info" - the second arg is the connection index whose info you want to set, |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
86 and the third arg is what you want to set your profile to. |
750 | 87 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
88 GAIM::user_info(index, nick) |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
89 Returns 8 data items: |
750 | 90 the screenname of the buddy |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
91 the alias of the buddy |
750 | 92 "Online" or "Offline" |
93 their warning level | |
94 signon time, in seconds since the epoch | |
95 idle time, in seconds (?) | |
96 user class, an integer with bit values | |
97 AOL 1 | |
98 ADMIN 2 | |
99 UNCONFIRMED 4 | |
100 NORMAL 8 | |
101 AWAY 16 | |
102 their capabilites, an integer with bit values | |
103 BUDDYICON 1 | |
104 VOICE 2 | |
105 IMIMAGE 4 | |
106 CHAT 8 | |
107 GETFILE 16 | |
108 SENDFILE 32 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
109 Since buddy lists are per-connection this goes through the connections |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
110 until it finds a matching buddy name. |
750 | 111 |
2261
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
112 GAIM::write_to_conv(to, wflags, what, who) |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
113 This displays a message into a conversation window. <wflags> is the |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
114 message-style and works like that: |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
115 wflags==0: display message as if received by <who> |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
116 wflags==1: display message as if sent by <who> |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
117 wflags==2: display system message |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
118 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
119 GAIM::serv_send_im(index, who, what, auto) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
120 Sends what from the connection index to who. :) |
750 | 121 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
122 GAIM::print_to_conv(index, who, what, auto) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
123 Convenience function; combination of write_to_conv and serv_send_im. |
750 | 124 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
125 GAIM::print_to_chat(index, room, what) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
126 Room is actually an int. Read SIGNALS to find out why. |
802
1afe98d2461e
[gaim-migrate @ 812]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
785
diff
changeset
|
127 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
128 GAIM::add_event_handler(event, function) |
785
dc9ad68fc30e
[gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
750
diff
changeset
|
129 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
|
130 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
|
131 (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
|
132 string with the name of the function you want called. Simple enough? |
750 | 133 |
2511
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
134 When this is triggered, the arguments will be passed in @_ and are broken |
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
135 into a list. This is different from all previous versions of Gaim, where you |
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
136 had to parse the arguments yourself. The arguments are quite different from |
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
137 what's passed to the plugins, though they are very similar, and you should |
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
138 read perl.c to figure out what they are. The arguments are passed after the |
785
dc9ad68fc30e
[gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
750
diff
changeset
|
139 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
|
140 so that gaim knows what the changes are. |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
141 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
142 Perl scripts can short-circuit certain events (namely event_im_send, |
3456 | 143 event_im_recv, event_chat_send, event_chat_recv and event_set_info). To |
144 short-circuit an event simply return a non-0 value. This will cause all | |
145 subsequent scripts and the event itself to never happen (i.e. the user | |
146 won't see it happen, and _send events won't actually send). | |
147 | |
148 GAIM::remove_event_handler(event, function) | |
149 This removes the event handler for the specified event that | |
150 calls "function" as its handler. The event handler must have been | |
151 previously added with GAIM::add_event_handler. | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
152 |
2512
bf7ec3874810
[gaim-migrate @ 2525]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2511
diff
changeset
|
153 GAIM::add_timeout_handler(integer, function, args) |
750 | 154 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
|
155 once, so if you want to keep calling function, keep readding the handler. |
2512
bf7ec3874810
[gaim-migrate @ 2525]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2511
diff
changeset
|
156 Args is a string that you'd like to have passed to your timeout handler; it's |
bf7ec3874810
[gaim-migrate @ 2525]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2511
diff
changeset
|
157 optional. |
3280 | 158 |
159 GAIM::play_sound(int sound) | |
160 Plays a sound using whatever method the user has selected. The argument is | |
161 one of the following numbers: | |
162 | |
163 0 Buddy logs in | |
164 1 Buddy logs out | |
165 2 Message received | |
166 3 Message received begins conversation | |
167 4 Message sent | |
168 5 Person enters chat | |
169 6 Person leaves chat | |
170 7 You talk in chat | |
171 8 Others talk in chat | |
172 9 Default buddy pounce sound | |
173 10 Someone says your name in chat |