Mercurial > pidgin
annotate plugins/PERL-HOWTO @ 3381:5df81b058690
[gaim-migrate @ 3400]
icon fix from faceprint.
committer: Tailor Script <tailor@pidgin.im>
author | Sean Egan <seanegan@gmail.com> |
---|---|
date | Wed, 07 Aug 2002 22:37:58 +0000 |
parents | c98c1e0281ff |
children | b48065e52337 |
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 | |
2536
0e0a54e5819a
[gaim-migrate @ 2549]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2512
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 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
22 There's one thing you need to be aware of in perl scripts for gaim. Gaim |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
23 supports multiple connections, and perl deals with them by using a unique |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
24 identifier for each of them (that's a fancy way of saying that perl scripts |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
25 use the memory address of the connection). |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
26 |
750 | 27 Everything available in normal perl scripts should be available in gaim's |
28 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
|
29 things are the functions provided by gaim's internal GAIM module, which is |
750 | 30 what most of this document is about. So, onto the functions. |
31 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
32 GAIM::register(name, version, shutdownroutine, unused) |
750 | 33 Just like X-Chat. This is the first function your script should call. |
34 shutdownroutine is a function that will be called when the script | |
35 gets unloaded (like when gaim gets closed). This function returns | |
36 gaim's version number. | |
37 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
38 GAIM::get_info(integer, ...) |
750 | 39 This function returns different information based on the integer passed |
40 to it. | |
41 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
|
42 1 - the list of connection ids |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
43 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
|
44 3 - given a connection index, the screenname of the person |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
45 4 - given a connection index, the index in the users list |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
46 5 - the list of names of users |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
47 6 - the list of protocols of the users |
2355
571971659533
[gaim-migrate @ 2368]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2345
diff
changeset
|
48 7 - given a connection index, the name of the protocol (as a string) |
750 | 49 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
50 GAIM::print(title, message) |
750 | 51 This displays a nice little dialog window. |
52 | |
53 | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
54 GAIM::buddy_list(index) |
750 | 55 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
|
56 for the specified connection. |
750 | 57 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
58 GAIM::online_list(index) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
59 This returns the list of online buddies for the specified connection. |
750 | 60 |
61 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
62 GAIM::command(command, ...) |
750 | 63 This sends commands to the server, and each command takes various |
64 arguments. The command should be self-explanatory: | |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
65 "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
|
66 "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
|
67 if no args are given, all connections are signed off. |
750 | 68 "away" - the second arg is the away message |
69 "back" - no args. | |
70 "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
|
71 (this sets the idle time for all connections) |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
72 "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
|
73 especially evil since it warns the person from every |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
74 connection. The third argument is 1 if you want to warn |
dd78a230aa06
[gaim-migrate @ 1744]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1101
diff
changeset
|
75 anonymously. If 0 or ommitted, it will warn normally. |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
76 "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
|
77 and the third arg is what you want to set your profile to. |
750 | 78 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
79 GAIM::user_info(index, nick) |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
80 Returns 8 data items: |
750 | 81 the screenname of the buddy |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
82 the alias of the buddy |
750 | 83 "Online" or "Offline" |
84 their warning level | |
85 signon time, in seconds since the epoch | |
86 idle time, in seconds (?) | |
87 user class, an integer with bit values | |
88 AOL 1 | |
89 ADMIN 2 | |
90 UNCONFIRMED 4 | |
91 NORMAL 8 | |
92 AWAY 16 | |
93 their capabilites, an integer with bit values | |
94 BUDDYICON 1 | |
95 VOICE 2 | |
96 IMIMAGE 4 | |
97 CHAT 8 | |
98 GETFILE 16 | |
99 SENDFILE 32 | |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
100 Since buddy lists are per-connection this goes through the connections |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
101 until it finds a matching buddy name. |
750 | 102 |
2261
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
103 GAIM::write_to_conv(to, wflags, what, who) |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
104 This displays a message into a conversation window. <wflags> is the |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
105 message-style and works like that: |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
106 wflags==0: display message as if received by <who> |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
107 wflags==1: display message as if sent by <who> |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
108 wflags==2: display system message |
e243bf60f2d6
[gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1776
diff
changeset
|
109 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
110 GAIM::serv_send_im(index, who, what, auto) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
111 Sends what from the connection index to who. :) |
750 | 112 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
113 GAIM::print_to_conv(index, who, what, auto) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
114 Convenience function; combination of write_to_conv and serv_send_im. |
750 | 115 |
2345
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
116 GAIM::print_to_chat(index, room, what) |
a49e8f1afbc4
[gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2261
diff
changeset
|
117 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
|
118 |
1101
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
119 GAIM::add_event_handler(event, function) |
785
dc9ad68fc30e
[gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
750
diff
changeset
|
120 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
|
121 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
|
122 (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
|
123 string with the name of the function you want called. Simple enough? |
750 | 124 |
2511
a83b4a5ffcd6
[gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2355
diff
changeset
|
125 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
|
126 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
|
127 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
|
128 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
|
129 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
|
130 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
|
131 so that gaim knows what the changes are. |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
132 |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
133 Perl scripts can short-circuit certain events (namely event_im_send, |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
134 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
|
135 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
|
136 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
|
137 and _send events won't actually send). |
0ef4386edc29
[gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
806
diff
changeset
|
138 |
2512
bf7ec3874810
[gaim-migrate @ 2525]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
2511
diff
changeset
|
139 GAIM::add_timeout_handler(integer, function, args) |
750 | 140 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
|
141 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
|
142 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
|
143 optional. |
3280 | 144 |
145 GAIM::play_sound(int sound) | |
146 Plays a sound using whatever method the user has selected. The argument is | |
147 one of the following numbers: | |
148 | |
149 0 Buddy logs in | |
150 1 Buddy logs out | |
151 2 Message received | |
152 3 Message received begins conversation | |
153 4 Message sent | |
154 5 Person enters chat | |
155 6 Person leaves chat | |
156 7 You talk in chat | |
157 8 Others talk in chat | |
158 9 Default buddy pounce sound | |
159 10 Someone says your name in chat |