plugin.h
Go to the documentation of this file.
1
9 /* purple
10 *
11 * Purple is the legal property of its developers, whose names are too numerous
12 * to list here. Please refer to the COPYRIGHT file distributed with this
13 * source distribution.
14 *
15 * This program is free software; you can redistribute it and/or modify
16 * it under the terms of the GNU General Public License as published by
17 * the Free Software Foundation; either version 2 of the License, or
18 * (at your option) any later version.
19 *
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public License
26 * along with this program; if not, write to the Free Software
27 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
28 */
29 #ifndef _PURPLE_PLUGIN_H_
30 #define _PURPLE_PLUGIN_H_
31
32 #include <glib.h>
33 #include <gmodule.h>
34 #include "signals.h"
35 #include "value.h"
36
38 typedef struct _PurplePlugin PurplePlugin;
40 typedef struct _PurplePluginInfo PurplePluginInfo;
42 typedef struct _PurplePluginUiInfo PurplePluginUiInfo;
44 typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo;
45
47 typedef struct _PurplePluginAction PurplePluginAction;
48
49 typedef int PurplePluginPriority;
51 #include "pluginpref.h"
52
56 typedef enum
57 {
58 PURPLE_PLUGIN_UNKNOWN = -1,
59 PURPLE_PLUGIN_STANDARD = 0,
60 PURPLE_PLUGIN_LOADER,
61 PURPLE_PLUGIN_PROTOCOL
63 } PurplePluginType;
64
65 #define PURPLE_PRIORITY_DEFAULT 0
66 #define PURPLE_PRIORITY_HIGHEST 9999
67 #define PURPLE_PRIORITY_LOWEST -9999
68
69 #define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01
70
71 #define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */
72
78 struct _PurplePluginInfo
79 {
80 unsigned int magic;
81 unsigned int major_version;
82 unsigned int minor_version;
83 PurplePluginType type;
84 char *ui_requirement;
85 unsigned long flags;
86 GList *dependencies;
87 PurplePluginPriority priority;
88
89 char *id;
90 char *name;
91 char *version;
92 char *summary;
93 char *description;
94 char *author;
95 char *homepage;
96
101 gboolean (*load)(PurplePlugin *plugin);
102 gboolean (*unload)(PurplePlugin *plugin);
103 void (*destroy)(PurplePlugin *plugin);
104
105 void *ui_info;
106 void *extra_info;
107 PurplePluginUiInfo *prefs_info;
122 GList *(*actions)(PurplePlugin *plugin, gpointer context);
123
124 void (*_purple_reserved1)(void);
125 void (*_purple_reserved2)(void);
126 void (*_purple_reserved3)(void);
127 void (*_purple_reserved4)(void);
128 };
129
133 struct _PurplePluginLoaderInfo
134 {
135 GList *exts;
136
137 gboolean (*probe)(PurplePlugin *plugin);
138 gboolean (*load)(PurplePlugin *plugin);
139 gboolean (*unload)(PurplePlugin *plugin);
140 void (*destroy)(PurplePlugin *plugin);
141
142 void (*_purple_reserved1)(void);
143 void (*_purple_reserved2)(void);
144 void (*_purple_reserved3)(void);
145 void (*_purple_reserved4)(void);
146 };
147
151 struct _PurplePlugin
152 {
153 gboolean native_plugin;
154 gboolean loaded;
155 void *handle;
156 char *path;
157 PurplePluginInfo *info;
158 char *error;
159 void *ipc_data;
160 void *extra;
161 gboolean unloadable;
162 GList *dependent_plugins;
164 void (*_purple_reserved1)(void);
165 void (*_purple_reserved2)(void);
166 void (*_purple_reserved3)(void);
167 void (*_purple_reserved4)(void);
168 };
169
170 #define PURPLE_PLUGIN_LOADER_INFO(plugin) \
171 ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
172
173 struct _PurplePluginUiInfo {
174 PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin);
175
176 int page_num;
177 PurplePluginPrefFrame *frame;
179 void (*_purple_reserved1)(void);
180 void (*_purple_reserved2)(void);
181 void (*_purple_reserved3)(void);
182 void (*_purple_reserved4)(void);
183 };
184
185 #define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \
186 ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
187
188 #define PURPLE_PLUGIN_UI_INFO(plugin) \
189 ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
190
191
195 struct _PurplePluginAction {
196 char *label;
197 void (*callback)(PurplePluginAction *);
198
200 PurplePlugin *plugin;
201
204 gpointer context;
205
206 gpointer user_data;
207 };
208
209 #define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \
210 ((plugin)->info != NULL && (plugin)->info->actions != NULL)
211
212 #define PURPLE_PLUGIN_ACTIONS(plugin, context) \
213 (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
214 (plugin)->info->actions(plugin, context): NULL)
215
216
220 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
221 # define _FUNC_NAME(x) purple_init_##x##_plugin
222 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
223 gboolean _FUNC_NAME(pluginname)(void);\
224 gboolean _FUNC_NAME(pluginname)(void) { \
225 PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
226 plugin->info = &(plugininfo); \
227 initfunc((plugin)); \
228 purple_plugin_load((plugin)); \
229 return purple_plugin_register(plugin); \
230 }
231 #else /* PURPLE_PLUGINS && !PURPLE_STATIC_PRPL */
232 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
233 G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \
234 G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \
235 plugin->info = &(plugininfo); \
236 initfunc((plugin)); \
237 return purple_plugin_register(plugin); \
238 }
239 #endif
240
241
242 #ifdef __cplusplus
243 extern "C" {
244 #endif
245
246 /**************************************************************************/
248 /**************************************************************************/
259 PurplePlugin *purple_plugin_new(gboolean native, const char *path);
260
272 PurplePlugin *purple_plugin_probe(const char *filename);
273
287 gboolean purple_plugin_register(PurplePlugin *plugin);
288
299 gboolean purple_plugin_load(PurplePlugin *plugin);
300
311 gboolean purple_plugin_unload(PurplePlugin *plugin);
312
323 void purple_plugin_disable(PurplePlugin *plugin);
324
335 gboolean purple_plugin_reload(PurplePlugin *plugin);
336
342 void purple_plugin_destroy(PurplePlugin *plugin);
343
351 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
352
365 gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin);
366
374 const gchar *purple_plugin_get_id(const PurplePlugin *plugin);
375
383 const gchar *purple_plugin_get_name(const PurplePlugin *plugin);
384
392 const gchar *purple_plugin_get_version(const PurplePlugin *plugin);
393
401 const gchar *purple_plugin_get_summary(const PurplePlugin *plugin);
402
410 const gchar *purple_plugin_get_description(const PurplePlugin *plugin);
411
419 const gchar *purple_plugin_get_author(const PurplePlugin *plugin);
420
428 const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin);
429
432 /**************************************************************************/
434 /**************************************************************************/
451 gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command,
452 PurpleCallback func,
453 PurpleSignalMarshalFunc marshal,
454 PurpleValue *ret_value, int num_params, ...);
455
462 void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command);
463
469 void purple_plugin_ipc_unregister_all(PurplePlugin *plugin);
470
482 gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command,
483 PurpleValue **ret_value, int *num_params,
484 PurpleValue ***params);
485
497 void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command,
498 gboolean *ok, ...);
499
502 /**************************************************************************/
504 /**************************************************************************/
512 void purple_plugins_add_search_path(const char *path);
513
521 GList *purple_plugins_get_search_paths(void);
522
526 void purple_plugins_unload_all(void);
527
531 void purple_plugins_unload(PurplePluginType type);
532
536 void purple_plugins_destroy_all(void);
537
543 void purple_plugins_save_loaded(const char *key);
544
551 void purple_plugins_load_saved(const char *key);
552
560 void purple_plugins_probe(const char *ext);
561
567 gboolean purple_plugins_enabled(void);
568
569 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
570
577 void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
578 #endif
579
580 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
581
587 void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
588 #endif
589
590 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
591
598 void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *),
599 void *data);
600 #endif
601
602 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
603
609 void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *));
610 #endif
611
612 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
613
620 void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *),
621 void *data);
622 #endif
623
624 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
625
631 void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *,
632 void *));
633 #endif
634
642 PurplePlugin *purple_plugins_find_with_name(const char *name);
643
651 PurplePlugin *purple_plugins_find_with_filename(const char *filename);
652
660 PurplePlugin *purple_plugins_find_with_basename(const char *basename);
661
669 PurplePlugin *purple_plugins_find_with_id(const char *id);
670
676 GList *purple_plugins_get_loaded(void);
677
686 GList *purple_plugins_get_protocols(void);
687
693 GList *purple_plugins_get_all(void);
694
697 /**************************************************************************/
699 /**************************************************************************/
707 void *purple_plugins_get_handle(void);
708
712 void purple_plugins_init(void);
713
717 void purple_plugins_uninit(void);
718
727 PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
728
734 void purple_plugin_action_free(PurplePluginAction *action);
735
736 #ifdef __cplusplus
737 }
738 #endif
739
740 #endif /* _PURPLE_PLUGIN_H_ */
_PurplePluginAction::context
gpointer context
NULL for plugin actions menu, set to the PurpleConnection for account actions menu.
Definition: plugin.h:204
_PurplePlugin::ipc_data
void * ipc_data
IPC data.
Definition: plugin.h:159
_PurplePlugin::loaded
gboolean loaded
The loaded state.
Definition: plugin.h:154
PurplePluginType
PurplePluginType
Plugin types.
Definition: plugin.h:56
purple_plugins_register_unload_notify_cb
void purple_plugins_register_unload_notify_cb(void(*func)(PurplePlugin *, void *), void *data)
Registers a function that will be called when a plugin is unloaded.
_PurplePlugin::dependent_plugins
GList * dependent_plugins
Plugins depending on this.
Definition: plugin.h:162
purple_plugins_find_with_filename
PurplePlugin * purple_plugins_find_with_filename(const char *filename)
Finds a plugin with the specified filename (filename with a path).
purple_plugins_register_probe_notify_cb
void purple_plugins_register_probe_notify_cb(void(*func)(void *), void *data)
Registers a function that will be called when probing is finished.
purple_plugin_ipc_get_params
gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command, PurpleValue **ret_value, int *num_params, PurpleValue ***params)
Returns a list of value types used for an IPC command.
purple_plugins_unload_all
void purple_plugins_unload_all(void)
Unloads all loaded plugins.
purple_plugin_disable
void purple_plugin_disable(PurplePlugin *plugin)
Disable a plugin.
purple_plugin_get_name
const gchar * purple_plugin_get_name(const PurplePlugin *plugin)
Returns a plugin&#39;s name.
purple_plugin_action_free
void purple_plugin_action_free(PurplePluginAction *action)
Frees a PurplePluginAction.
purple_plugin_is_loaded
gboolean purple_plugin_is_loaded(const PurplePlugin *plugin)
Returns whether or not a plugin is currently loaded.
PURPLE_PLUGIN_LOADER
Loader plugin.
Definition: plugin.h:60
purple_plugins_enabled
gboolean purple_plugins_enabled(void)
Returns whether or not plugin support is enabled.
purple_plugin_destroy
void purple_plugin_destroy(PurplePlugin *plugin)
Unloads a plugin and destroys the structure from memory.
purple_plugin_new
PurplePlugin * purple_plugin_new(gboolean native, const char *path)
Creates a new plugin structure.
purple_plugins_find_with_basename
PurplePlugin * purple_plugins_find_with_basename(const char *basename)
Finds a plugin with the specified basename (filename without a path).
purple_plugin_ipc_call
void * purple_plugin_ipc_call(PurplePlugin *plugin, const char *command, gboolean *ok,...)
Executes an IPC command.
purple_plugin_is_unloadable
gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin)
Returns whether or not a plugin is unloadable.
_PurplePlugin::unloadable
gboolean unloadable
Unloadable.
Definition: plugin.h:161
_PurplePluginUiInfo::frame
PurplePluginPrefFrame * frame
Reserved.
Definition: plugin.h:177
purple_plugins_unregister_load_notify_cb
void purple_plugins_unregister_load_notify_cb(void(*func)(PurplePlugin *, void *))
Unregisters a function that would be called when a plugin is loaded.
_PurplePlugin::extra
void * extra
Plugin-specific data.
Definition: plugin.h:160
_PurplePlugin
A plugin handle.
Definition: plugin.h:151
purple_plugins_load_saved
void purple_plugins_load_saved(const char *key)
Attempts to load all the plugins in the specified preference key that were loaded when purple last qu...
purple_plugins_unregister_unload_notify_cb
void purple_plugins_unregister_unload_notify_cb(void(*func)(PurplePlugin *, void *))
Unregisters a function that would be called when a plugin is unloaded.
purple_plugin_load
gboolean purple_plugin_load(PurplePlugin *plugin)
Attempts to load a previously probed plugin.
purple_plugin_get_homepage
const gchar * purple_plugin_get_homepage(const PurplePlugin *plugin)
Returns a plugin&#39;s homepage.
_PurplePluginLoaderInfo
Extra information for loader plugins.
Definition: plugin.h:133
purple_plugins_unload
void purple_plugins_unload(PurplePluginType type)
Unloads all plugins of a specific type.
purple_plugins_register_load_notify_cb
void purple_plugins_register_load_notify_cb(void(*func)(PurplePlugin *, void *), void *data)
Registers a function that will be called when a plugin is loaded.
_PurplePluginInfo::ui_info
void * ui_info
Used only by UI-specific plugins to build a preference screen with a custom UI.
Definition: plugin.h:105
purple_plugin_get_id
const gchar * purple_plugin_get_id(const PurplePlugin *plugin)
Returns a plugin&#39;s id.
purple_plugins_uninit
void purple_plugins_uninit(void)
Uninitializes the plugin subsystem.
_PurplePluginAction
The structure used in the actions member of PurplePluginInfo.
Definition: plugin.h:195
purple_plugins_init
void purple_plugins_init(void)
Initializes the plugin subsystem.
purple_plugin_register
gboolean purple_plugin_register(PurplePlugin *plugin)
Registers a plugin and prepares it for loading.
purple_plugins_save_loaded
void purple_plugins_save_loaded(const char *key)
Saves the list of loaded plugins to the specified preference key.
_PurplePluginAction::plugin
PurplePlugin * plugin
set to the owning plugin
Definition: plugin.h:200
purple_plugins_get_search_paths
GList * purple_plugins_get_search_paths(void)
Returns a list of plugin search paths.
purple_plugin_get_author
const gchar * purple_plugin_get_author(const PurplePlugin *plugin)
Returns a plugin&#39;s author.
purple_plugin_unload
gboolean purple_plugin_unload(PurplePlugin *plugin)
Unloads the specified plugin.
purple_plugin_get_version
const gchar * purple_plugin_get_version(const PurplePlugin *plugin)
Returns a plugin&#39;s version.
purple_plugins_get_protocols
GList * purple_plugins_get_protocols(void)
Returns a list of all valid protocol plugins.
purple_plugins_probe
void purple_plugins_probe(const char *ext)
Probes for plugins in the registered module paths.
purple_plugin_probe
PurplePlugin * purple_plugin_probe(const char *filename)
Probes a plugin, retrieving the information on it and adding it to the list of available plugins...
purple_plugins_destroy_all
void purple_plugins_destroy_all(void)
Destroys all registered plugins.
purple_plugins_find_with_id
PurplePlugin * purple_plugins_find_with_id(const char *id)
Finds a plugin with the specified plugin ID.
purple_plugin_reload
gboolean purple_plugin_reload(PurplePlugin *plugin)
Reloads a plugin.
purple_plugin_ipc_unregister
void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command)
Unregisters an IPC command in a plugin.
_PurplePluginInfo::prefs_info
PurplePluginUiInfo * prefs_info
Used by any plugin to display preferences.
Definition: plugin.h:107
purple_plugin_ipc_unregister_all
void purple_plugin_ipc_unregister_all(PurplePlugin *plugin)
Unregisters all IPC commands in a plugin.
purple_plugin_get_summary
const gchar * purple_plugin_get_summary(const PurplePlugin *plugin)
Returns a plugin&#39;s summary.
PurpleValue
A wrapper for a type, subtype, and specific type of value.
Definition: value.h:89
purple_plugins_add_search_path
void purple_plugins_add_search_path(const char *path)
Add a new directory to search for plugins.
PURPLE_PLUGIN_UNKNOWN
Unknown type.
Definition: plugin.h:58
PURPLE_PLUGIN_STANDARD
Standard plugin.
Definition: plugin.h:59
_PurplePlugin::handle
void * handle
The module handle.
Definition: plugin.h:155
pluginpref.h
Plugin Preferences API.
signals.h
Signal API.
_PurplePluginUiInfo
Definition: plugin.h:173
_PurplePlugin::info
PurplePluginInfo * info
The plugin information.
Definition: plugin.h:157
purple_plugins_find_with_name
PurplePlugin * purple_plugins_find_with_name(const char *name)
Finds a plugin with the specified name.
value.h
Value wrapper API.
purple_plugins_unregister_probe_notify_cb
void purple_plugins_unregister_probe_notify_cb(void(*func)(void *))
Unregisters a function that would be called when probing is finished.
_PurplePluginInfo
Detailed information about a plugin.
Definition: plugin.h:78
purple_plugins_get_all
GList * purple_plugins_get_all(void)
Returns a list of all plugins, whether loaded or not.
purple_plugins_get_loaded
GList * purple_plugins_get_loaded(void)
Returns a list of all loaded plugins.
PURPLE_PLUGIN_PROTOCOL
Protocol plugin.
Definition: plugin.h:61
_PurplePlugin::path
char * path
The path to the plugin.
Definition: plugin.h:156
purple_plugin_get_description
const gchar * purple_plugin_get_description(const PurplePlugin *plugin)
Returns a plugin&#39;s description.
_PurplePlugin::native_plugin
gboolean native_plugin
Native C plugin.
Definition: plugin.h:153
purple_plugins_get_handle
void * purple_plugins_get_handle(void)
Returns the plugin subsystem handle.
PurplePluginPriority
int PurplePluginPriority
Plugin priority.
Definition: plugin.h:49
_PurplePluginUiInfo::page_num
int page_num
Reserved.
Definition: plugin.h:176
_PurplePluginInfo::load
gboolean(* load)(PurplePlugin *plugin)
If a plugin defines a &#39;load&#39; function, and it returns FALSE, then the plugin will not be loaded...
Definition: plugin.h:101
purple_plugin_action_new
PurplePluginAction * purple_plugin_action_new(const char *label, void(*callback)(PurplePluginAction *))
Allocates and returns a new PurplePluginAction.
purple_plugin_ipc_register
gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command, PurpleCallback func, PurpleSignalMarshalFunc marshal, PurpleValue *ret_value, int num_params,...)
Registers an IPC command in a plugin.