Mercurial > pidgin
annotate src/plugin.h @ 5864:417b1001d2b1
[gaim-migrate @ 6295]
Rewrote the pounce API again. Now it's even MORE core/UI-split, and will
allow for loading/saving.
committer: Tailor Script <tailor@pidgin.im>
author | Christian Hammond <chipx86@chipx86.com> |
---|---|
date | Sat, 14 Jun 2003 11:14:49 +0000 |
parents | 8f5ccf9e590a |
children | 158196b2db19 |
rev | line source |
---|---|
5205 | 1 /** |
2 * @file plugin.h Plugin API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Copyright (C) 2003 Christian Hammond <chipx86@gnupdate.org> | |
8 * | |
9 * This program is free software; you can redistribute it and/or modify | |
10 * it under the terms of the GNU General Public License as published by | |
11 * the Free Software Foundation; either version 2 of the License, or | |
12 * (at your option) any later version. | |
13 * | |
14 * This program is distributed in the hope that it will be useful, | |
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 * GNU General Public License for more details. | |
18 * | |
19 * You should have received a copy of the GNU General Public License | |
20 * along with this program; if not, write to the Free Software | |
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
22 */ | |
23 #ifndef _GAIM_PLUGIN_H_ | |
24 #define _GAIM_PLUGIN_H_ | |
5224
5160333a80df
[gaim-migrate @ 5594]
Herman Bloggs <hermanator12002@yahoo.com>
parents:
5205
diff
changeset
|
25 #include <gmodule.h> |
5205 | 26 |
27 typedef enum _GaimPluginType GaimPluginType; /**< GaimPluginType */ | |
28 typedef struct _GaimPlugin GaimPlugin; /**< GaimPlugin */ | |
29 typedef struct _GaimPluginInfo GaimPluginInfo; /**< GaimPluginInfo */ | |
30 typedef struct _GaimPluginLoaderInfo GaimPluginLoaderInfo; | |
31 | |
32 typedef int GaimPluginPriority; /**< Plugin priority. */ | |
33 | |
34 /* XXX */ | |
35 #include "config.h" | |
36 #include "event.h" | |
37 | |
38 /** | |
39 * Plugin types. | |
40 */ | |
41 enum _GaimPluginType | |
42 { | |
43 GAIM_PLUGIN_UNKNOWN = -1, /**< Unknown type. */ | |
44 GAIM_PLUGIN_STANDARD = 0, /**< Standard plugin. */ | |
45 GAIM_PLUGIN_LOADER, /**< Loader plugin. */ | |
46 GAIM_PLUGIN_PROTOCOL /**< Protocol plugin. */ | |
47 }; | |
48 | |
49 #define GAIM_PRIORITY_DEFAULT 0 | |
50 #define GAIM_PRIORITY_HIGHEST 9999 | |
51 #define GAIM_PRIORITY_LOWEST -9999 | |
52 | |
53 #define GAIM_PLUGIN_ID_UNSET { 0, 0, 0, 0 } | |
54 | |
55 /** | |
56 * Detailed information about a plugin. | |
57 * | |
58 * This is used in the version 2.0 API and up. | |
59 */ | |
60 struct _GaimPluginInfo | |
61 { | |
62 unsigned int api_version; | |
63 GaimPluginType type; | |
64 char *ui_requirement; | |
65 unsigned long flags; | |
66 GList *dependencies; | |
67 GaimPluginPriority priority; | |
68 | |
69 char *id; | |
70 char *name; | |
71 char *version; | |
72 char *summary; | |
73 char *description; | |
74 char *author; | |
75 char *homepage; | |
76 | |
77 gboolean (*load)(GaimPlugin *plugin); | |
78 gboolean (*unload)(GaimPlugin *plugin); | |
79 void (*destroy)(GaimPlugin *plugin); | |
80 | |
81 void *ui_info; | |
82 void *extra_info; | |
83 }; | |
84 | |
85 /** | |
86 * Extra information for loader plugins. | |
87 */ | |
88 struct _GaimPluginLoaderInfo | |
89 { | |
90 GList *exts; | |
91 | |
92 gboolean (*probe)(GaimPlugin *plugin); | |
93 gboolean (*load)(GaimPlugin *plugin); | |
94 gboolean (*unload)(GaimPlugin *plugin); | |
95 void (*destroy)(GaimPlugin *plugin); | |
96 | |
97 GaimSignalBroadcastFunc broadcast; | |
98 }; | |
99 | |
100 /** | |
101 * A plugin handle. | |
102 */ | |
103 struct _GaimPlugin | |
104 { | |
105 gboolean native_plugin; /**< Native C plugin. */ | |
106 gboolean loaded; /**< The loaded state. */ | |
107 void *handle; /**< The module handle. */ | |
108 char *path; /**< The path to the plugin. */ | |
109 GaimPluginInfo *info; /**< The plugin information. */ | |
110 char *error; | |
111 void *extra; /**< Plugin-specific data. */ | |
112 }; | |
113 | |
114 #define GAIM_PLUGIN_LOADER_INFO(plugin) \ | |
115 ((GaimPluginLoaderInfo *)(plugin)->info->extra_info) | |
116 | |
117 /** | |
118 * Handles the initialization of modules. | |
119 */ | |
5449 | 120 #ifndef GAIM_PLUGINS |
5205 | 121 # define GAIM_INIT_PLUGIN(pluginname, initfunc, plugininfo) \ |
122 gboolean gaim_init_##pluginname##_plugin(void) { \ | |
123 GaimPlugin *plugin = gaim_plugin_new(TRUE, NULL); \ | |
124 plugin->info = &(plugininfo); \ | |
125 initfunc((plugin)); \ | |
126 return gaim_plugin_register(plugin); \ | |
127 } | |
5449 | 128 #else /* GAIM_PLUGINS */ |
5205 | 129 # define GAIM_INIT_PLUGIN(pluginname, initfunc, plugininfo) \ |
5224
5160333a80df
[gaim-migrate @ 5594]
Herman Bloggs <hermanator12002@yahoo.com>
parents:
5205
diff
changeset
|
130 G_MODULE_EXPORT gboolean gaim_init_plugin(GaimPlugin *plugin) { \ |
5205 | 131 plugin->info = &(plugininfo); \ |
132 initfunc((plugin)); \ | |
133 return gaim_plugin_register(plugin); \ | |
134 } | |
135 #endif | |
136 | |
137 /**************************************************************************/ | |
138 /** @name Plugin namespace */ | |
139 /**************************************************************************/ | |
140 /*@{*/ | |
141 | |
142 /** | |
143 * Creates a new plugin structure. | |
144 * | |
145 * @param native Whether or not the plugin is native. | |
146 * @param path The path to the plugin, or @c NULL if statically compiled. | |
147 * | |
148 * @return A new GaimPlugin structure. | |
149 */ | |
150 GaimPlugin *gaim_plugin_new(gboolean native, const char *path); | |
151 | |
152 /** | |
153 * Probes a plugin, retrieving the information on it and adding it to the | |
154 * list of available plugins. | |
155 * | |
156 * @param filename The plugin's filename. | |
157 * | |
158 * @return The plugin handle. | |
159 * | |
160 * @see gaim_plugin_load() | |
161 * @see gaim_plugin_destroy() | |
162 */ | |
163 GaimPlugin *gaim_plugin_probe(const char *filename); | |
164 | |
165 /** | |
166 * Registers a plugin and prepares it for loading. | |
167 * | |
168 * This shouldn't be called by anything but the internal module code. | |
169 * | |
170 * @param plugin The plugin to register. | |
171 */ | |
172 gboolean gaim_plugin_register(GaimPlugin *plugin); | |
173 | |
174 /** | |
175 * Attempts to load a previously probed plugin. | |
176 * | |
177 * @param filename The plugin's filename. | |
178 * | |
179 * @return @c TRUE if successful, or @c FALSE otherwise. | |
180 * | |
181 * @see gaim_plugin_reload() | |
182 * @see gaim_plugin_unload() | |
183 */ | |
184 gboolean gaim_plugin_load(GaimPlugin *plugin); | |
185 | |
186 /** | |
187 * Unloads the specified plugin. | |
188 * | |
189 * @param plugin The plugin handle. | |
190 * | |
191 * @return @c TRUE if successful, or @c FALSE otherwise. | |
192 * | |
193 * @see gaim_plugin_load() | |
194 * @see gaim_plugin_reload() | |
195 */ | |
196 gboolean gaim_plugin_unload(GaimPlugin *plugin); | |
197 | |
198 /** | |
199 * Reloads a plugin. | |
200 * | |
201 * @param plugin The old plugin handle. | |
202 * | |
203 * @return @c TRUE if successful, or @c FALSE otherwise. | |
204 * | |
205 * @see gaim_plugin_load() | |
206 * @see gaim_plugin_unload() | |
207 */ | |
208 gboolean gaim_plugin_reload(GaimPlugin *plugin); | |
209 | |
210 /** | |
211 * Unloads a plugin and destroys the structure from memory. | |
212 * | |
213 * @param plugin The plugin handle. | |
214 */ | |
215 void gaim_plugin_destroy(GaimPlugin *plugin); | |
216 | |
217 /** | |
218 * Returns whether or not a plugin is currently loaded. | |
219 * | |
220 * @param plugin The plugin. | |
221 * | |
222 * @return TRUE if loaded, or FALSE otherwise. | |
223 */ | |
224 gboolean gaim_plugin_is_loaded(const GaimPlugin *plugin); | |
225 | |
226 /*@}*/ | |
227 | |
228 /**************************************************************************/ | |
229 /** @name Plugins namespace */ | |
230 /**************************************************************************/ | |
231 /*@{*/ | |
232 | |
233 /** | |
234 * Sets the search paths for plugins. | |
235 * | |
236 * @param count The number of search paths. | |
237 * @param paths The search paths. | |
238 */ | |
239 void gaim_plugins_set_search_paths(size_t count, char **paths); | |
240 | |
241 /** | |
5242
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
242 * Unloads all loaded plugins. |
5205 | 243 */ |
244 void gaim_plugins_unload_all(void); | |
245 | |
5242
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
246 |
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
247 /** |
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
248 * Destroys all registered plugins. |
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
249 */ |
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
250 void gaim_plugins_destroy_all(void); |
fd81a00480ac
[gaim-migrate @ 5613]
Christian Hammond <chipx86@chipx86.com>
parents:
5224
diff
changeset
|
251 |
5205 | 252 /** |
5838 | 253 * Attempts to load all the plugins that were loaded when gaim last quit |
254 */ | |
5840 | 255 void gaim_plugins_load_saved(void); |
5838 | 256 |
257 /** | |
5205 | 258 * Probes for plugins in the registered module paths. |
259 * | |
260 * @param ext The extension type to probe for, or @c NULL for all. | |
261 * | |
262 * @see gaim_plugin_set_probe_path() | |
263 */ | |
264 void gaim_plugins_probe(const char *ext); | |
265 | |
266 /** | |
267 * Returns whether or not plugin support is enabled. | |
268 * | |
269 * @return TRUE if plugin support is enabled, or FALSE otherwise. | |
270 */ | |
271 gboolean gaim_plugins_enabled(void); | |
272 | |
273 /** | |
274 * Registers a function that will be called when probing is finished. | |
275 * | |
276 * @param func The callback function. | |
277 * @param data Data to pass to the callback. | |
278 */ | |
279 void gaim_plugins_register_probe_notify_cb(void (*func)(void *), void *data); | |
280 | |
281 /** | |
282 * Unregisters a function that would be called when probing is finished. | |
283 * | |
284 * @param func The callback function. | |
285 */ | |
286 void gaim_plugins_unregister_probe_notify_cb(void (*func)(void *)); | |
287 | |
288 /** | |
289 * Registers a function that will be called when a plugin is loaded. | |
290 * | |
291 * @param func The callback functino. | |
292 * @param data Data to pass to the callback. | |
293 */ | |
294 void gaim_plugins_register_load_notify_cb(void (*func)(GaimPlugin *, void *), | |
295 void *data); | |
296 | |
297 /** | |
298 * Unregisters a function that would be called when a plugin is loaded. | |
299 * | |
300 * @param func The callback functino. | |
301 */ | |
302 void gaim_plugins_unregister_load_notify_cb(void (*func)(GaimPlugin *, void *)); | |
303 | |
304 /** | |
305 * Registers a function that will be called when a plugin is unloaded. | |
306 * | |
307 * @param func The callback functino. | |
308 * @param data Data to pass to the callback. | |
309 */ | |
310 void gaim_plugins_register_unload_notify_cb(void (*func)(GaimPlugin *, void *), | |
311 void *data); | |
312 | |
313 /** | |
314 * Unregisters a function that would be called when a plugin is unloaded. | |
315 * | |
316 * @param func The callback functino. | |
317 */ | |
318 void gaim_plugins_unregister_unload_notify_cb(void (*func)(GaimPlugin *, | |
319 void *)); | |
320 | |
321 /** | |
322 * Finds a plugin with the specified name. | |
323 * | |
324 * @param name The plugin name. | |
325 * | |
326 * @return The plugin if found, or @c NULL if not found. | |
327 */ | |
328 GaimPlugin *gaim_plugins_find_with_name(const char *name); | |
329 | |
330 /** | |
331 * Finds a plugin with the specified filename. | |
332 * | |
333 * @param filename The plugin filename. | |
334 * | |
335 * @return The plugin if found, or @c NULL if not found. | |
336 */ | |
337 GaimPlugin *gaim_plugins_find_with_filename(const char *filename); | |
338 | |
339 /** | |
340 * Finds a plugin with the specified plugin ID. | |
341 * | |
342 * @param id The plugin ID. | |
343 * | |
344 * @return The plugin if found, or @c NULL if not found. | |
345 */ | |
346 GaimPlugin *gaim_plugins_find_with_id(const char *id); | |
347 | |
348 /** | |
349 * Returns a list of all loaded plugins. | |
350 * | |
5573
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
351 * @return A list of all loaded plugins. |
5205 | 352 */ |
353 GList *gaim_plugins_get_loaded(void); | |
354 | |
355 /** | |
5573
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
356 * Returns a list of all protocol plugins. |
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
357 * |
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
358 * @return A list of all protocol plugins. |
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
359 */ |
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
360 GList *gaim_plugins_get_protocols(void); |
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
361 |
5e7de337a053
[gaim-migrate @ 5976]
Christian Hammond <chipx86@chipx86.com>
parents:
5449
diff
changeset
|
362 /** |
5205 | 363 * Returns a list of all plugins, whether loaded or not. |
364 * | |
365 * @return A list of all plugins. | |
366 */ | |
367 GList *gaim_plugins_get_all(void); | |
368 | |
369 /*@}*/ | |
370 | |
371 #endif /* _GAIM_PLUGIN_H_ */ |