annotate doc/PERL-HOWTO.dox @ 10330:4f5a7ddd3161

[gaim-migrate @ 11537] Get rid of 3 goto's. Can someone please let me know if this doesn't compile? Herman, I hope this changes are ok with you... if not, feel free to revert it. committer: Tailor Script <tailor@pidgin.im>
author Mark Doliner <mark@kingant.net>
date Thu, 09 Dec 2004 00:24:30 +0000
parents f17e538bf9e0
children f53c59c95f03
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
1 /** @page perl-howto Perl Scripting HOWTO
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
2
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
3 @section Introduction
10161
f17e538bf9e0 [gaim-migrate @ 11247]
Luke Schierer <lschiere@pidgin.im>
parents: 9433
diff changeset
4 THERE ARE SIGNIFICANT BUGS IN THIS CODE. HOWEVER, IT _MOSTLY_ WORKS _IF_
f17e538bf9e0 [gaim-migrate @ 11247]
Luke Schierer <lschiere@pidgin.im>
parents: 9433
diff changeset
5 YOU ARE VERY CAREFUL. DO _NOT_ COMPLAIN ABOUT THIS API. SUBMIT A PATCH.
f17e538bf9e0 [gaim-migrate @ 11247]
Luke Schierer <lschiere@pidgin.im>
parents: 9433
diff changeset
6
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
7 Perl is the first scripting language compatible with Gaim, and has been a
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
8 valuable aid to developers wishing to write scripts to modify the behavior
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
9 of their favorite instant messenger. A perl script acts like a normal
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
10 plugin, and appears in the list of plugins in Gaim's preferences pane.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
11 Until now, they have been very basic, and consisted of only a few
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
12 functions. However, with the latest changes to Gaim's perl API, a much
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
13 larger part of Gaim is now open. In time, even such things as Gtk+
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
14 preference panes for perl scripts will be possible.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
15
6603
21084026030b [gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents: 6602
diff changeset
16 @section first-script Writing your first perl script
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
17 Enough of that. You want to know how to write a perl script, right?
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
18
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
19 First off, we're going to assume here that you are familiar with perl. Perl
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
20 scripts in Gaim are just normal perl scripts, which happen to use Gaim's
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
21 loadable perl module.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
22
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
23 Now, you're going to want to place your script in $HOME/.gaim/plugins/.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
24 That's the place where all plugins and scripts go, regardless of language.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
25
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
26 The first thing you're going to write in your script is the necessary code
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
27 to actually register and initialize your script, which looks something like
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
28 this:
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
29
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
30
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
31 @code
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
32 use Gaim;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
33
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
34 %PLUGIN_INFO = (
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
35 perl_api_version => 2,
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
36 name => "Your Plugin's Name",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
37 version => "0.1",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
38 summary => "Brief summary of your plugin.",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
39 description => "Detailed description of what your plugin does.",
9433
775ee46b67a2 [gaim-migrate @ 10253]
Ethan Blanton <elb@pidgin.im>
parents: 7668
diff changeset
40 author => "Your Name <email\@address>",
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
41 url => "http://yoursite.com/",
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
42
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
43 load => "plugin_load",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
44 unload => "plugin_unload"
7182
65acffe70a6d [gaim-migrate @ 7750]
Christian Hammond <chipx86@chipx86.com>
parents: 6720
diff changeset
45 );
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
46
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
47 sub plugin_init {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
48 return %PLUGIN_INFO;
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
49 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
50
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
51 sub plugin_load {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
52 my $plugin = shift;
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
53 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
54
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
55 sub plugin_unload {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
56 my $plugin = shift;
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
57 }
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
58 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
59
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
60
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
61 The first thing you see is a hash called @c @%PLUGIN_INFO. It contains
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
62 the basic information on your plugin. In the future, additional fields
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
63 may be allowed, such as ones to setup a Gtk+ preferences pane.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
64
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
65 The @c plugin_init function is required in all perl scripts. Its job
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
66 is to return the @c @%PLUGIN_INFO hash, which Gaim will use to register
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
67 and initialize your plugin.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
68
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
69 The @c plugin_load function is called when the user loads your plugin
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
70 from the preferences, or on startup. It is passed one variable, which
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
71 is a handle to the plugin. This must be used when registering signal
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
72 handlers or timers.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
73
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
74 The @c plugin_unload function is called when the user is unloading your
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
75 plugin. Its job is to clean up anything that must be dealt with before
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
76 unloading, such as removing temporary files or saving configuration
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
77 information. It does @em not have to unregister signal handlers or timers,
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
78 as Gaim will do that for you.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
79
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
80 @warning Do @b NOT put any executable code outside of these functions
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
81 or your own user-defined functions. Variable declarations are
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
82 okay, as long as they're set to be local. Bad Things (TM) can
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
83 happen if you don't follow this simple instruction.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
84
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
85
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
86 @section Timeouts
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
87 One feature useful to many perl plugin writers are timeouts. Timeouts allow
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
88 code to be ran after a specified number of seconds, and are rather
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
89 simple to setup. Here's one way of registering a timeout.
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
90
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
91
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
92 @code
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
93 sub timeout_cb {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
94 my $data = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
95
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
96 Gaim::debug_info("my perl plugin",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
97 "Timeout callback called! data says: $data\n");
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
98 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
99
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
100 sub plugin_load {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
101 my $plugin = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
102
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
103 # Start a timeout for 5 seconds.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
104 Gaim::timeout_add($plugin, 5, \&timeout_cb, "Hello!");
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
105 }
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
106 @endcode
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
107
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
108
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
109 Here's another way of calling a timeout:
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
110
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
111
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
112 @code
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
113 sub plugin_load {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
114 my $plugin = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
115
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
116 # Start a timeout for 5 seconds.
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
117 Gaim::timeout_add($plugin, 5,
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
118 sub {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
119 my $data = shift;
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
120
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
121 Gaim::debug_info("my perl plugin",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
122 "Timeout callback called! data says: $data\n");
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
123 }, "Hello!");
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
124 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
125 @endcode
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
126
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
127
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
128 A timeout automatically unregisters when it reaches 0 (which is also
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
129 when the callback is called). If you want a timeout to call a function
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
130 every specified number of seconds, just re-register the timeout
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
131 at the end of the callback.
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
132
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
133 The data parameter is optional. If you don't have data to pass to the
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
134 callback, simply omit the parameter.
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
135
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
136 @section Signals
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
137 Signals are how gaim plugins get events. There are a number of
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
138 @ref Signals signals available.
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
139
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
140 A signal is registered by connecting a signal name owned by an
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
141 instance handle to a callback on the plugin handle. This is best
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
142 illustrated with an example.
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
143
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
144
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
145 @code
7668
90ed8fcca27c [gaim-migrate @ 8312]
Mark Doliner <mark@kingant.net>
parents: 7335
diff changeset
146 sub signed_on_cb {
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
147 my ($gc, $data) = @_;
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
148 my $account = $gc->get_account();
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
149
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
150 Gaim::debug_info("my perl plugin",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
151 "Account " . $account->get_username() . " signed on.\n");
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
152 }
6603
21084026030b [gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents: 6602
diff changeset
153
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
154 sub plugin_load {
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
155 my $plugin = shift;
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
156 my $data = "";
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
157
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
158 Gaim::signal_connect(Gaim::Connections::handle, "signed-on",
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
159 $plugin, \&signed_on_cb, $data);
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
160 }
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
161 @endcode
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
162
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
163
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
164 Like timeouts, the callback can be an embedded subroutine, and also
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
165 like timeouts, the data parameter can be omitted.
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
166
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
167 @section Notes
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
168 The API in perl is very similar to Gaim's C API. The functions have been
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
169 gathered into packages, but most are the same, and the documentation can
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
170 be a big help at times.
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
171
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
172 @section Resources
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
173 @see Signals
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
174 @see Perl API Reference
6602
76683fe3c96d [gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents: 6598
diff changeset
175
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
176 */
7335
3c3039aa7259 [gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents: 7182
diff changeset
177
6598
2f6850c7d980 [gaim-migrate @ 7122]
Christian Hammond <chipx86@chipx86.com>
parents:
diff changeset
178 // vim: syntax=c tw=75 et