annotate plugins/PERL-HOWTO @ 5676:dae79aefac8d

[gaim-migrate @ 6094] I've been meaning to do this for a LONG time. The conversation API now follows the naming convention of the rest of the new APIs. I'll get some g_return_*_if_fail() checks in there soon. committer: Tailor Script <tailor@pidgin.im>
author Christian Hammond <chipx86@chipx86.com>
date Mon, 02 Jun 2003 21:51:06 +0000
parents 283fb289c510
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3551
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
1 So, you wanna write a perl script.
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
2
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
3 Perl scripts in Gaim can be very useful. Although they can't directly manipulate
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
4 Gaim data like a plugin, or provide any sort of UI, they're portable, easy to develop
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
5 rapidly and extremely powerful when manipulating incoming and outgoing messages.
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
6
3551
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
7 This document assumes you know perl--Gaim perl scripts work exactly like normal perl
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
8 scripts, with a few extra commands you can use.
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
9
3551
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
10 The first thing Gaim will do with your plugin (provided it's in $prefix/lib/gaim or
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
11 $HOME/.gaim/) is look for and call a function called "description". description()
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
12 gives Gaim the information it will use in the plugins dialog--script name, version,
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
13 your name--all sorts of good things. Let's look at an example:
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
14
3551
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
15 sub description {
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
16 my($a, $b, $c, $d, $e, $f) = @_;
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
17 ("Example", "1.0", "An example Gaim perl script that does nothing
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
18 particularly useful:\n\t-Show a dialog on load\n\t-Set user idle for
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
19 6,000 seconds\n\t-Greets people signing on with \"Hello\"\n\t-Informs
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
20 you when script has been loaded for one minute.",
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
21 "Eric Warmenhoven &lt;eric\@warmenhoven.org>", "http://gaim.sf.net",
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
22 "/dev/null");
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
23 }
806
67bdecdecbb7 [gaim-migrate @ 816]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 802
diff changeset
24
3551
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
25 This pushes what's needed to the perl stack. What is all that stuff?
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
26 $a - Name
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
27 $b - Version
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
28 $c - Description
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
29 $d - Authors
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
30 $e - Webpage
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
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
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
33 It should be noted that this information will be formatted according to Pango's
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
34 markup language--a language akin to HTML. This is neat in that it lets you bold
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
35 and italicize your description and stuff, but it's important you take care to
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
36 properly escape stuff (notice the &lt; in $d).
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
37
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
38 Now, for the Gaim-specific perl functions (if you know x-chat scripts, you'll
cd938f18f3f8 [gaim-migrate @ 3626]
Sean Egan <seanegan@gmail.com>
parents: 3456
diff changeset
39 feel right at home):
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
40
1101
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
41 GAIM::register(name, version, shutdownroutine, unused)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
42 Just like X-Chat. This is the first function your script should call.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
43 shutdownroutine is a function that will be called when the script
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
44 gets unloaded (like when gaim gets closed). This function returns
3563
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
45 gaim's version number. This function MUST use the same Name and Version
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
46 given in description()--the plugin won't work otherwise. This returns a
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
47 handle--you want to hold on to this.
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
48
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
49 The handle is what Gaim will use to distinguish your script from any others
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
50 running. It's actually a string--the path to the script, but you'll probably
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
51 never need to know that. As long as you just hold on to it and don't change it
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
52 everything should work fine. You need it for GAIM::add_event_handler and
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
53 GAIM::add_timeout_handler.
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
54
1101
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
55 GAIM::get_info(integer, ...)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
56 This function returns different information based on the integer passed
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
57 to it.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
66
1101
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
67 GAIM::print(title, message)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
68 This displays a nice little dialog window.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
69
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
70
2345
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
71 GAIM::buddy_list(index)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
77
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
78
1101
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
79 GAIM::command(command, ...)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
80 This sends commands to the server, and each command takes various
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
85 "away" - the second arg is the away message
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
86 "back" - no args.
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
100 "Online" or "Offline"
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
101 their warning level
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
102 signon time, in seconds since the epoch
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
103 idle time, in seconds (?)
1101
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
104 Since buddy lists are per-connection this goes through the connections
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
105 until it finds a matching buddy name.
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
106
2261
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
107 GAIM::write_to_conv(to, wflags, what, who)
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
108 This displays a message into a conversation window. <wflags> is the
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
109 message-style and works like that:
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
110 wflags==0: display message as if received by <who>
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
111 wflags==1: display message as if sent by <who>
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
112 wflags==2: display system message
e243bf60f2d6 [gaim-migrate @ 2271]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1776
diff changeset
113
2345
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
114 GAIM::serv_send_im(index, who, what, auto)
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
115 Sends what from the connection index to who. :)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
116
2345
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
117 GAIM::print_to_conv(index, who, what, auto)
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
118 Convenience function; combination of write_to_conv and serv_send_im.
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
119
2345
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
120 GAIM::print_to_chat(index, room, what)
a49e8f1afbc4 [gaim-migrate @ 2358]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2261
diff changeset
121 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
122
3563
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
123 GAIM::add_event_handler(handle, event, function)
785
dc9ad68fc30e [gaim-migrate @ 795]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 750
diff changeset
124 This is the most important of them all. This is basically exactly like
3563
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
125 gaim_signal_connect for plugins. You pass the handle returned by GAIM::register,
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
126 which event you want to connect to (a string with the same name as the events for
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
127 plugins, see SIGNALS), and a string with the name of the function you want called.
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
128 Simple enough?
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
129
2511
a83b4a5ffcd6 [gaim-migrate @ 2524]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2355
diff changeset
130 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
131 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
132 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
133 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
134 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
135 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
136 so that gaim knows what the changes are.
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
137
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
138 Perl scripts can short-circuit certain events (namely event_im_send,
3456
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
139 event_im_recv, event_chat_send, event_chat_recv and event_set_info). To
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
140 short-circuit an event simply return a non-0 value. This will cause all
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
141 subsequent scripts and the event itself to never happen (i.e. the user
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
142 won't see it happen, and _send events won't actually send).
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
143
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
144 GAIM::remove_event_handler(event, function)
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
145 This removes the event handler for the specified event that
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
146 calls "function" as its handler. The event handler must have been
b48065e52337 [gaim-migrate @ 3503]
Sean Egan <seanegan@gmail.com>
parents: 3280
diff changeset
147 previously added with GAIM::add_event_handler.
1101
0ef4386edc29 [gaim-migrate @ 1111]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 806
diff changeset
148
3563
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
149 GAIM::add_timeout_handler(handle, integer, function, args)
750
c4c4a18bb2f9 [gaim-migrate @ 760]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
150 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
151 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
152 Args is a string that you'd like to have passed to your timeout handler; it's
3563
e120097bbd72 [gaim-migrate @ 3658]
Sean Egan <seanegan@gmail.com>
parents: 3551
diff changeset
153 optional. Handle is the handle returned by GAIM::register--it is not optional.
3280
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
154
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
155 GAIM::play_sound(int sound)
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
156 Plays a sound using whatever method the user has selected. The argument is
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
157 one of the following numbers:
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
158
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
159 0 Buddy logs in
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
160 1 Buddy logs out
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
161 2 Message received
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
162 3 Message received begins conversation
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
163 4 Message sent
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
164 5 Person enters chat
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
165 6 Person leaves chat
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
166 7 You talk in chat
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
167 8 Others talk in chat
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
168 9 Default buddy pounce sound
c98c1e0281ff [gaim-migrate @ 3298]
Sean Egan <seanegan@gmail.com>
parents: 2536
diff changeset
169 10 Someone says your name in chat