Mercurial > pidgin
annotate plugins/PERL-HOWTO @ 4418:3270d3536e12
[gaim-migrate @ 4691]
paco-paco got gaim to compile on solaris :-)
(23:18:49) Paco-Paco: Fixes getopt handling and libsocket detection on Solaris
committer: Tailor Script <tailor@pidgin.im>
author | Luke Schierer <lschiere@pidgin.im> |
---|---|
date | Sun, 26 Jan 2003 04:18:46 +0000 |
parents | e120097bbd72 |
children | 283fb289c510 |
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 | |
3563 | 45 gaim's version number. This function MUST use the same Name and Version |
46 given in description()--the plugin won't work otherwise. This returns a | |
47 handle--you want to hold on to this. | |
48 | |
49 The handle is what Gaim will use to distinguish your script from any others | |
50 running. It's actually a string--the path to the script, but you'll probably | |
51 never need to know that. As long as you just hold on to it and don't change it | |
52 everything should work fine. You need it for GAIM::add_event_handler and | |
53 GAIM::add_timeout_handler. | |
750 | 54 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
55 GAIM::get_info(integer, ...) |
750 | 56 This function returns different information based on the integer passed |
57 to it. | |
58 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
|
59 1 - the list of connection ids |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
60 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
|
61 3 - given a connection index, the screenname of the person |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
62 4 - given a connection index, the index in the users list |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
63 5 - the list of names of users |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
64 6 - the list of protocols of the users |
2355
571971659533
[gaim-migrate @ 2368]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2345
diff
changeset
|
65 7 - given a connection index, the name of the protocol (as a string) |
750 | 66 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
67 GAIM::print(title, message) |
750 | 68 This displays a nice little dialog window. |
69 | |
70 | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
71 GAIM::buddy_list(index) |
750 | 72 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
|
73 for the specified connection. |
750 | 74 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
75 GAIM::online_list(index) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
76 This returns the list of online buddies for the specified connection. |
750 | 77 |
78 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
79 GAIM::command(command, ...) |
750 | 80 This sends commands to the server, and each command takes various |
81 arguments. The command should be self-explanatory: | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
82 "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
|
83 "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
|
84 if no args are given, all connections are signed off. |
750 | 85 "away" - the second arg is the away message |
86 "back" - no args. | |
87 "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
|
88 (this sets the idle time for all connections) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
89 "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
|
90 especially evil since it warns the person from every |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
91 connection. The third argument is 1 if you want to warn |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
92 anonymously. If 0 or ommitted, it will warn normally. |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
93 "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
|
94 and the third arg is what you want to set your profile to. |
750 | 95 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
96 GAIM::user_info(index, nick) |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
97 Returns 8 data items: |
750 | 98 the screenname of the buddy |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
99 the alias of the buddy |
750 | 100 "Online" or "Offline" |
101 their warning level | |
102 signon time, in seconds since the epoch | |
103 idle time, in seconds (?) | |
104 user class, an integer with bit values | |
105 AOL 1 | |
106 ADMIN 2 | |
107 UNCONFIRMED 4 | |
108 NORMAL 8 | |
109 AWAY 16 | |
110 their capabilites, an integer with bit values | |
111 BUDDYICON 1 | |
112 VOICE 2 | |
113 IMIMAGE 4 | |
114 CHAT 8 | |
115 GETFILE 16 | |
116 SENDFILE 32 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
117 Since buddy lists are per-connection this goes through the connections |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
118 until it finds a matching buddy name. |
750 | 119 |
2261
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
120 GAIM::write_to_conv(to, wflags, what, who) |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
121 This displays a message into a conversation window. <wflags> is the |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
122 message-style and works like that: |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
123 wflags==0: display message as if received by <who> |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
124 wflags==1: display message as if sent by <who> |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
125 wflags==2: display system message |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
126 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
127 GAIM::serv_send_im(index, who, what, auto) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
128 Sends what from the connection index to who. :) |
750 | 129 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
130 GAIM::print_to_conv(index, who, what, auto) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
131 Convenience function; combination of write_to_conv and serv_send_im. |
750 | 132 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
133 GAIM::print_to_chat(index, room, what) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
134 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
|
135 |
3563 | 136 GAIM::add_event_handler(handle, event, function) |
785
dc9ad68fc30e
[gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
750
diff
changeset
|
137 This is the most important of them all. This is basically exactly like |
3563 | 138 gaim_signal_connect for plugins. You pass the handle returned by GAIM::register, |
139 which event you want to connect to (a string with the same name as the events for | |
140 plugins, see SIGNALS), and a string with the name of the function you want called. | |
141 Simple enough? | |
750 | 142 |
2511
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
143 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
|
144 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
|
145 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
|
146 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
|
147 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
|
148 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
|
149 so that gaim knows what the changes are. |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
150 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
151 Perl scripts can short-circuit certain events (namely event_im_send, |
3456 | 152 event_im_recv, event_chat_send, event_chat_recv and event_set_info). To |
153 short-circuit an event simply return a non-0 value. This will cause all | |
154 subsequent scripts and the event itself to never happen (i.e. the user | |
155 won't see it happen, and _send events won't actually send). | |
156 | |
157 GAIM::remove_event_handler(event, function) | |
158 This removes the event handler for the specified event that | |
159 calls "function" as its handler. The event handler must have been | |
160 previously added with GAIM::add_event_handler. | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
161 |
3563 | 162 GAIM::add_timeout_handler(handle, integer, function, args) |
750 | 163 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
|
164 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
|
165 Args is a string that you'd like to have passed to your timeout handler; it's |
3563 | 166 optional. Handle is the handle returned by GAIM::register--it is not optional. |
3280 | 167 |
168 GAIM::play_sound(int sound) | |
169 Plays a sound using whatever method the user has selected. The argument is | |
170 one of the following numbers: | |
171 | |
172 0 Buddy logs in | |
173 1 Buddy logs out | |
174 2 Message received | |
175 3 Message received begins conversation | |
176 4 Message sent | |
177 5 Person enters chat | |
178 6 Person leaves chat | |
179 7 You talk in chat | |
180 8 Others talk in chat | |
181 9 Default buddy pounce sound | |
182 10 Someone says your name in chat |