10468
|
1 /** @page c-howto C Plugin HOWTO
|
|
2
|
|
3 @section Introduction
|
|
4 C plugins are native plugins. They have complete access to all of the api,
|
|
5 and can do basically whatever they want. All of the protocol plugins, as
|
|
6 well as the perl and tcl loader plugins are written in C.
|
|
7
|
|
8 @section getting_started Getting Started
|
|
9 To develop a plugin you need to have the gaim source code. It is generally a
|
|
10 good idea to compile against the same version of gaim that you are running.
|
|
11 You may also want to develop against CVS. While we do NOT recomend this for
|
|
12 normal users, but there is an exception for developers. A lot tends to
|
|
13 change between versions and it's much easier to fix your plugin as things
|
|
14 change rather than waiting until the release. But please do not abuse CVS.
|
|
15 Gaim puts a lot of strain on Source Forge's servers, and we do not need to
|
|
16 add anymore to it.
|
|
17
|
|
18 If you choose not to head my warnings and develop against a version of gaim
|
|
19 that is different from what you're running, then you're gaim source must at
|
|
20 the very least be configured. Note that just running configure will
|
|
21 generally set the prefix to /usr/local. This shouldn't be a problem, except
|
|
22 that most packages compile and install gaim with /usr as the prefix.
|
|
23
|
|
24 All plugins must have @c GAIM_PLUGINS defined. You can choose to include
|
|
25 @c internal.h to do this, but if you choose to do it this way it must be
|
|
26 included before any other gaim files. Likewise, if you choose to manually
|
|
27 define @c GAIM_PLUGINS, the definition must be before including any gaim
|
|
28 files. Failure to do so will produce the 'plugin foo could not be loaded for
|
|
29 an unknown reason'. This is one of the hardest unknown reasons to track
|
|
30 down, so let's try to avoid it at all costs ;)
|
|
31
|
|
32 @section hello_world Hello World!
|
|
33 I know every tutorial has a hello world, so why should gaim be any different?
|
|
34
|
|
35 @code
|
|
36 #define GAIM_PLUGINS
|
|
37
|
|
38 #include <glib.h>
|
|
39
|
|
40 #include "notify.h"
|
|
41 #include "plugin.h"
|
|
42 #include "version.h"
|
|
43
|
|
44 static gboolean
|
|
45 plugin_load(GaimPlugin *plugin) {
|
|
46 gaim_notify_message(plugin, GAIM_NOTIFY_MSG_INFO, "Hello World!",
|
|
47 "This is the Hello World! plugin :)", NULL, NULL, NULL);
|
|
48
|
|
49 return TRUE;
|
|
50 }
|
|
51
|
|
52 static GaimPluginInfo info = {
|
|
53 GAIM_PLUGIN_MAGIC,
|
|
54 GAIM_MAJOR_VERSION,
|
|
55 GAIM_MINOR_VERSION,
|
|
56 GAIM_PLUGIN_STANDARD,
|
|
57 NULL,
|
|
58 0,
|
|
59 NULL,
|
|
60 GAIM_PRIORITY_DEFAULT,
|
|
61
|
|
62 "core-hello_world",
|
|
63 "Hello World!",
|
|
64 VERSION,
|
|
65
|
|
66 "Hello World Plugin",
|
|
67 "Hello World Plugin",
|
|
68 NULL,
|
|
69 GAIM_WEBSITE,
|
|
70
|
|
71 plugin_load,
|
|
72 NULL,
|
|
73 NULL,
|
|
74
|
|
75 NULL,
|
|
76 NULL,
|
|
77 NULL,
|
|
78 NULL
|
|
79 };
|
|
80
|
|
81 static void
|
|
82 init_plugin(GaimPlugin *plugin) {
|
|
83 }
|
|
84
|
|
85 GAIM_INIT_PLUGIN(hello_world, init_plugin, info);
|
|
86
|
|
87 @endcode
|
|
88
|
|
89 Okay, so what does all this mean? We start off by defining @c GAIM_PLUGINS
|
|
90 like described before. Next we include glib.h, mainly for gboolean and the
|
|
91 glib wrappers of the standard c types. We could just use stdio and use
|
|
92 an int for the gboolean but since gaim uses glib internally, we might as
|
|
93 well do the same.
|
|
94
|
|
95 Next, we include plugin.h which has all the plugin specific stuff that we
|
|
96 need. For example @c GaimPlugin, @c GaimPluginInfo, @c GAIM_PLUGIN_MAGIC,
|
|
97 and @c GAIM_INIT_PLUGIN().
|
|
98
|
|
99 Our last include is version.h which defines @c GAIM_MAJOR_VERSION, and
|
|
100 @c GAIM_MINOR_VERSION. Theres not much you need to know about these, except
|
|
101 that they are required and will stop your plugin from crashing Gaim when
|
|
102 something has changed that you plugin does not know about yet.
|
|
103
|
|
104 plugin_load is not required. It is called when the plugin is loaded, so you
|
|
105 can initialize any variables and so on. But in this plugin we'll just use it
|
|
106 to display a message.
|
|
107
|
|
108 Next we have the @c GaimPluginInfo structure. Every plugin MUST have one of
|
|
109 these. Below is a code snipet of the same struct used in @c hello_world with
|
|
110 comments describing what each is.
|
|
111
|
|
112 @code
|
|
113 static GaimPluginInfo info = {
|
|
114 GAIM_PLUGIN_MAGIC, /* Plugin magic, this should always be
|
|
115 GAIM_PLUGIN_MAGIC. This value gets
|
|
116 incremented inside of gaim so that plugins
|
|
117 that haven't been updated yet, will fail to
|
|
118 load and avoid potential crashes while
|
|
119 loading old plugins.
|
|
120 */
|
|
121 GAIM_MAJOR_VERSION, /* This is also define in gaim. It helps
|
|
122 Gaim's plugin system tell what version of
|
|
123 this plugin was compiled for, and whether
|
|
124 or not loading it will cause problems
|
|
125 */
|
|
126 GAIM_MINOR_VERSION, /* See previous */
|
|
127 GAIM_PLUGIN_STANDARD, /* GaimPluginType, there are 4 different values
|
|
128 for this field. The first is
|
|
129 GAIM_PLUGIN_UNKNOWN, which should not be
|
|
130 used. The second is GAIM_PLUGIN_STANDARD,
|
|
131 this is the value most plugins will use.
|
|
132 Next we have GAIM_PLUGIN_LOADER, this is
|
|
133 the type you want to load if you're plugin
|
|
134 is going to make it possible to load non
|
|
135 native plugins. For example, perl and tcl.
|
|
136 Last, we have GAIM_PLUGIN_PROTOCOL. If
|
|
137 your plugin is going to allow the user to
|
|
138 connect to another network, this is the
|
|
139 type you'd want to use.
|
|
140 */
|
|
141 NULL, /* This field is the ui requirement. This
|
|
142 value should be a string. If you're
|
|
143 writing a core plugin, this should be NULL
|
|
144 and the plugin should not contain any ui
|
|
145 specific code. If you're writing a gtk
|
|
146 plugin, you can use the
|
|
147 GAIM_GTK_PLUGIN_TYPE macro. All other ui
|
|
148 plugins are dependent on their ui
|
|
149 implementation, and is outside the scope of
|
|
150 this howto.
|
|
151 */
|
|
152 0, /* This field is for plugin flags. Currently,
|
|
153 the only flag available to plugins is
|
|
154 invisible (GAIM_PLUGIN_FLAG_INVISIBLE).
|
|
155 The only plugins that current use this flag,
|
|
156 is the ssl plugin.
|
|
157 */
|
|
158 NULL, /* This is a glist of plugin dependencies. In
|
|
159 other words, a glist of plugin id's that
|
|
160 your plugin depends on. If your plugin
|
|
161 does not have any dependencies, set this
|
|
162 value to NULL
|
|
163 */
|
|
164 GAIM_PRIORITY_DEFAULT, /* This is the priority gaim with give your
|
|
165 plugin. There are three possible values
|
|
166 for this field, GAIM_PRIORITY_DEFAULT,
|
|
167 GAIM_PRIORITY_HIGHEST, and
|
|
168 GAIM_PRIORITY_LOWEST
|
|
169 */
|
|
170
|
|
171 "core-hello_world", /* This is your plugin's id. There is a whole
|
|
172 page dedicated to this in the
|
|
173 'related-pages' section of the doxygen api.
|
|
174 */
|
|
175 "Hello World!", /* This is your plugin name. This is what
|
|
176 will be displayed for your plugin in the ui.
|
|
177 */
|
|
178 VERSION, /* This is the version of your plugin. For
|
|
179 the sake of simplicity, I'm using the gaim
|
|
180 version.
|
|
181 */
|
|
182
|
|
183 "Hello World Plugin", /* This is the summary of your plugin. It
|
|
184 should be a short little blurb. The ui
|
|
185 determines where, if at all, to display
|
|
186 this.
|
|
187 */
|
|
188 "Hello World Plugin", /* This is the description of your plugin. It
|
|
189 can be as long and as descriptive as you
|
|
190 like. And like the summary, it's up to the
|
|
191 ui where, if at all, to display this.
|
|
192 */
|
|
193 NULL, /* This is where you can put your name and
|
|
194 email address. (You are the author right?)
|
|
195 */
|
|
196 GAIM_WEBSITE, /* This is the website for the plugin. This
|
|
197 is helpful if users find bugs in your
|
|
198 plugin so they can help to bring them to
|
|
199 your attention
|
|
200 */
|
|
201
|
|
202 plugin_load, /* This is a pointer to a function for gaim to
|
|
203 call when it is loading your plugin. It
|
|
204 should be in the form of:
|
|
205
|
|
206 gboolean function_name(GaimPlugin *plugin)
|
|
207
|
|
208 Returning TRUE will tell gaim to continue
|
|
209 loading your plugin, while FALSE will tell
|
|
210 gaim to stop trying to load it.
|
|
211 */
|
|
212 NULL, /* Same as above except it is called when
|
|
213 gaim tries to unload your plugin. It
|
|
214 should be in the form of:
|
|
215
|
|
216 gboolean function_name(GaimPlugin *plugin)
|
|
217
|
|
218 Where returning TRUE will tell gaim to
|
|
219 continue unloading and false to not continue
|
|
220 unloading your plugin.
|
|
221 */
|
|
222 NULL, /* Similar to the two above members, except
|
|
223 this is called when gaim tries to destory
|
|
224 the plugin. This is generally only called
|
|
225 when for some reason or another the plugin
|
|
226 fails to probe correctly. It should be in
|
|
227 the form of:
|
|
228
|
|
229 void function_name(GaimPlugin *plugin)
|
|
230 */
|
|
231
|
|
232 NULL, /* This is a pointer to a ui specific struct.
|
|
233 For a gtk plugin it will be a pointer to a
|
|
234 GaimGtkPluginUiInfo struct.
|
|
235 */
|
|
236 NULL, /* This is a pointer to either a
|
|
237 GaimPluginLoaderInfo struct or a
|
|
238 GaimPluginProtocolInfo struct, and is
|
|
239 beyond the scope of this document.
|
|
240 */
|
|
241 NULL, /* This is a pointer to a GaimPluginUiInfo
|
|
242 struct. It is a core/ui split way for
|
|
243 core plugins to have a ui configuration
|
|
244 frame. You can find an example of this
|
|
245 code in plugins/pluginpref_example.c
|
|
246 */
|
|
247 NULL /* Finally the last member of the structure,
|
|
248 is a function pointer where you can define
|
|
249 menu entries for 'Tools->Plugin Actions'.
|
|
250 It should be in the form of:
|
|
251
|
|
252 GList *function_name(GaimPlugin *plugin,
|
|
253 gpointer context)
|
|
254
|
|
255 It should return a GList of
|
|
256 GaimPluginActions.
|
|
257 */
|
|
258 };
|
|
259 @endcode
|
|
260
|
|
261 Finally we have @c init_plugin and @c GAIM_INIT_PLUGIN. @c init_plugin is a
|
|
262 function that gets called when Gaim probes the plugin. Most plugins will
|
|
263 add their preferences to the pref tree here, more about that later.
|
|
264 @GAIM_INIT_PLUGIN is a macro that EVERY plugin MUST have. @GAIM_INIT_PLUGIN
|
|
265 tells gaim some very basic things about your plugin, like what name to use
|
|
266 if the plugin is compiled staticly, the @c init_plugin function, and
|
|
267 the name of the @c GaimPluginInfo structure. As you may have guess this
|
|
268 also gets read when Gaim is probing your plugin. If this is missing you
|
|
269 will get the infamous "plugin unloadable for unknown reasons", so do not
|
|
270 forget it.
|
|
271 */
|