Mercurial > pidgin
annotate plugins/PERL-HOWTO @ 3572:bdd0bebd2d04
[gaim-migrate @ 3670]
Phase II. No longer do you have to worry about protocol plugins. When
Gaim probes plugins on load, it will detect protocol plugins and add them
to the list of available protocols. When you try to log an account on with
one of them, Gaim will automatically load the plugin--when no more accounts
need the protocol--Gaim will automatically unload it. Protocol plugins are
no longer available in the plugins ui, and no protocols are compiled statically
by default.
committer: Tailor Script <tailor@pidgin.im>
author | Sean Egan <seanegan@gmail.com> |
---|---|
date | Mon, 30 Sep 2002 01:05:18 +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 |