Mercurial > pidgin3 / file comparison

comparison: src/plugin.h

src/plugin.h

changeset 5205
242b8aa81328
child 5224
8cb89f5b912a
equal deleted inserted replaced
5204:deed98aa3181 5205:242b8aa81328
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_
25
26 typedef enum _GaimPluginType GaimPluginType; /**< GaimPluginType */
27 typedef struct _GaimPlugin GaimPlugin; /**< GaimPlugin */
28 typedef struct _GaimPluginInfo GaimPluginInfo; /**< GaimPluginInfo */
29 typedef struct _GaimPluginLoaderInfo GaimPluginLoaderInfo;
30
31 typedef int GaimPluginPriority; /**< Plugin priority. */
32
33 /* XXX */
34 #include "config.h"
35 #include "event.h"
36
37 /**
38 * Plugin types.
39 */
40 enum _GaimPluginType
41 {
42 GAIM_PLUGIN_UNKNOWN = -1, /**< Unknown type. */
43 GAIM_PLUGIN_STANDARD = 0, /**< Standard plugin. */
44 GAIM_PLUGIN_LOADER, /**< Loader plugin. */
45 GAIM_PLUGIN_PROTOCOL /**< Protocol plugin. */
46 };
47
48 #define GAIM_PRIORITY_DEFAULT 0
49 #define GAIM_PRIORITY_HIGHEST 9999
50 #define GAIM_PRIORITY_LOWEST -9999
51
52 #define GAIM_PLUGIN_ID_UNSET { 0, 0, 0, 0 }
53
54 /**
55 * Detailed information about a plugin.
56 *
57 * This is used in the version 2.0 API and up.
58 */
59 struct _GaimPluginInfo
60 {
61 unsigned int api_version;
62 GaimPluginType type;
63 char *ui_requirement;
64 unsigned long flags;
65 GList *dependencies;
66 GaimPluginPriority priority;
67
68 char *id;
69 char *name;
70 char *version;
71 char *summary;
72 char *description;
73 char *author;
74 char *homepage;
75
76 gboolean (*load)(GaimPlugin *plugin);
77 gboolean (*unload)(GaimPlugin *plugin);
78 void (*destroy)(GaimPlugin *plugin);
79
80 void *ui_info;
81 void *extra_info;
82 };
83
84 /**
85 * Extra information for loader plugins.
86 */
87 struct _GaimPluginLoaderInfo
88 {
89 GList *exts;
90
91 gboolean (*probe)(GaimPlugin *plugin);
92 gboolean (*load)(GaimPlugin *plugin);
93 gboolean (*unload)(GaimPlugin *plugin);
94 void (*destroy)(GaimPlugin *plugin);
95
96 GaimSignalBroadcastFunc broadcast;
97 };
98
99 /**
100 * A plugin handle.
101 */
102 struct _GaimPlugin
103 {
104 gboolean native_plugin; /**< Native C plugin. */
105 gboolean loaded; /**< The loaded state. */
106 void *handle; /**< The module handle. */
107 char *path; /**< The path to the plugin. */
108 GaimPluginInfo *info; /**< The plugin information. */
109 char *error;
110 void *extra; /**< Plugin-specific data. */
111 };
112
113 #define GAIM_PLUGIN_LOADER_INFO(plugin) \
114 ((GaimPluginLoaderInfo *)(plugin)->info->extra_info)
115
116 /**
117 * Handles the initialization of modules.
118 */
119 #ifdef STATIC_MODULE
120 # define GAIM_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
121 gboolean gaim_init_##pluginname##_plugin(void) { \
122 GaimPlugin *plugin = gaim_plugin_new(TRUE, NULL); \
123 plugin->info = &(plugininfo); \
124 initfunc((plugin)); \
125 return gaim_plugin_register(plugin); \
126 }
127 #else /* if !STATIC_MODULE */
128 # define GAIM_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
129 gboolean gaim_init_plugin(GaimPlugin *plugin) { \
130 plugin->info = &(plugininfo); \
131 initfunc((plugin)); \
132 return gaim_plugin_register(plugin); \
133 }
134 #endif
135
136 /**************************************************************************/
137 /** @name Plugin namespace */
138 /**************************************************************************/
139 /*@{*/
140
141 /**
142 * Creates a new plugin structure.
143 *
144 * @param native Whether or not the plugin is native.
145 * @param path The path to the plugin, or @c NULL if statically compiled.
146 *
147 * @return A new GaimPlugin structure.
148 */
149 GaimPlugin *gaim_plugin_new(gboolean native, const char *path);
150
151 /**
152 * Probes a plugin, retrieving the information on it and adding it to the
153 * list of available plugins.
154 *
155 * @param filename The plugin's filename.
156 *
157 * @return The plugin handle.
158 *
159 * @see gaim_plugin_load()
160 * @see gaim_plugin_destroy()
161 */
162 GaimPlugin *gaim_plugin_probe(const char *filename);
163
164 /**
165 * Registers a plugin and prepares it for loading.
166 *
167 * This shouldn't be called by anything but the internal module code.
168 *
169 * @param plugin The plugin to register.
170 */
171 gboolean gaim_plugin_register(GaimPlugin *plugin);
172
173 /**
174 * Attempts to load a previously probed plugin.
175 *
176 * @param filename The plugin's filename.
177 *
178 * @return @c TRUE if successful, or @c FALSE otherwise.
179 *
180 * @see gaim_plugin_reload()
181 * @see gaim_plugin_unload()
182 */
183 gboolean gaim_plugin_load(GaimPlugin *plugin);
184
185 /**
186 * Unloads the specified plugin.
187 *
188 * @param plugin The plugin handle.
189 *
190 * @return @c TRUE if successful, or @c FALSE otherwise.
191 *
192 * @see gaim_plugin_load()
193 * @see gaim_plugin_reload()
194 */
195 gboolean gaim_plugin_unload(GaimPlugin *plugin);
196
197 /**
198 * Reloads a plugin.
199 *
200 * @param plugin The old plugin handle.
201 *
202 * @return @c TRUE if successful, or @c FALSE otherwise.
203 *
204 * @see gaim_plugin_load()
205 * @see gaim_plugin_unload()
206 */
207 gboolean gaim_plugin_reload(GaimPlugin *plugin);
208
209 /**
210 * Unloads a plugin and destroys the structure from memory.
211 *
212 * @param plugin The plugin handle.
213 */
214 void gaim_plugin_destroy(GaimPlugin *plugin);
215
216 /**
217 * Returns whether or not a plugin is currently loaded.
218 *
219 * @param plugin The plugin.
220 *
221 * @return TRUE if loaded, or FALSE otherwise.
222 */
223 gboolean gaim_plugin_is_loaded(const GaimPlugin *plugin);
224
225 /*@}*/
226
227 /**************************************************************************/
228 /** @name Plugins namespace */
229 /**************************************************************************/
230 /*@{*/
231
232 /**
233 * Sets the search paths for plugins.
234 *
235 * @param count The number of search paths.
236 * @param paths The search paths.
237 */
238 void gaim_plugins_set_search_paths(size_t count, char **paths);
239
240 /**
241 * Unloads all registered plugins.
242 */
243 void gaim_plugins_unload_all(void);
244
245 /**
246 * Probes for plugins in the registered module paths.
247 *
248 * @param ext The extension type to probe for, or @c NULL for all.
249 *
250 * @see gaim_plugin_set_probe_path()
251 */
252 void gaim_plugins_probe(const char *ext);
253
254 /**
255 * Returns whether or not plugin support is enabled.
256 *
257 * @return TRUE if plugin support is enabled, or FALSE otherwise.
258 */
259 gboolean gaim_plugins_enabled(void);
260
261 /**
262 * Registers a function that will be called when probing is finished.
263 *
264 * @param func The callback function.
265 * @param data Data to pass to the callback.
266 */
267 void gaim_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
268
269 /**
270 * Unregisters a function that would be called when probing is finished.
271 *
272 * @param func The callback function.
273 */
274 void gaim_plugins_unregister_probe_notify_cb(void (*func)(void *));
275
276 /**
277 * Registers a function that will be called when a plugin is loaded.
278 *
279 * @param func The callback functino.
280 * @param data Data to pass to the callback.
281 */
282 void gaim_plugins_register_load_notify_cb(void (*func)(GaimPlugin *, void *),
283 void *data);
284
285 /**
286 * Unregisters a function that would be called when a plugin is loaded.
287 *
288 * @param func The callback functino.
289 */
290 void gaim_plugins_unregister_load_notify_cb(void (*func)(GaimPlugin *, void *));
291
292 /**
293 * Registers a function that will be called when a plugin is unloaded.
294 *
295 * @param func The callback functino.
296 * @param data Data to pass to the callback.
297 */
298 void gaim_plugins_register_unload_notify_cb(void (*func)(GaimPlugin *, void *),
299 void *data);
300
301 /**
302 * Unregisters a function that would be called when a plugin is unloaded.
303 *
304 * @param func The callback functino.
305 */
306 void gaim_plugins_unregister_unload_notify_cb(void (*func)(GaimPlugin *,
307 void *));
308
309 /**
310 * Finds a plugin with the specified name.
311 *
312 * @param name The plugin name.
313 *
314 * @return The plugin if found, or @c NULL if not found.
315 */
316 GaimPlugin *gaim_plugins_find_with_name(const char *name);
317
318 /**
319 * Finds a plugin with the specified filename.
320 *
321 * @param filename The plugin filename.
322 *
323 * @return The plugin if found, or @c NULL if not found.
324 */
325 GaimPlugin *gaim_plugins_find_with_filename(const char *filename);
326
327 /**
328 * Finds a plugin with the specified plugin ID.
329 *
330 * @param id The plugin ID.
331 *
332 * @return The plugin if found, or @c NULL if not found.
333 */
334 GaimPlugin *gaim_plugins_find_with_id(const char *id);
335
336 /**
337 * Returns a list of all loaded plugins.
338 *
339 * @return A list of all plugins.
340 */
341 GList *gaim_plugins_get_loaded(void);
342
343 /**
344 * Returns a list of all plugins, whether loaded or not.
345 *
346 * @return A list of all plugins.
347 */
348 GList *gaim_plugins_get_all(void);
349
350 /*@}*/
351
352 #endif /* _GAIM_PLUGIN_H_ */

Mercurial Repository: pidgin3

mercurial