Mercurial > pidgin.yaz

comparison doc/C-HOWTO.dox @ 10468:87d2f1a7f984

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[gaim-migrate @ 11750] a newwer plugin how to brought to you by grim committer: Tailor Script <tailor@pidgin.im>
author Luke Schierer <lschiere@pidgin.im>
date Mon, 03 Jan 2005 18:20:22 +0000
parents
children 51b87da4e9f0
comparison
equal deleted inserted replaced
10467:cbbf5af9e520 10468:87d2f1a7f984
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 */