pidgin  2.14.10
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;
45 
48 
49 typedef int PurplePluginPriority;
51 #include "pluginpref.h"
52 
56 typedef enum
57 {
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 
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;
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 
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 
152 {
153  gboolean native_plugin;
154  gboolean loaded;
155  void *handle;
156  char *path;
158  char *error;
159  void *ipc_data;
160  void *extra;
161  gboolean unloadable;
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 
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 
196  char *label;
197  void (*callback)(PurplePluginAction *);
198 
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 
288 
300 
312 
324 
336 
343 
351 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
352 
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 
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 
522 
527 
532 
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_)
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_)
587 void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
588 #endif
589 
590 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
599  void *data);
600 #endif
601 
602 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
610 #endif
611 
612 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
621  void *data);
622 #endif
623 
624 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
632  void *));
633 #endif
634 
643 
652 
661 
670 
677 
687 
694 
697 /**************************************************************************/
699 /**************************************************************************/
708 
713 
718 
727 PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
728 
735 
736 #ifdef __cplusplus
737 }
738 #endif
739 
740 #endif /* _PURPLE_PLUGIN_H_ */
GList * purple_plugins_get_protocols(void)
Returns a list of all valid protocol plugins.
void purple_plugins_unload(PurplePluginType type)
Unloads all plugins of a specific type.
PurplePlugin * purple_plugins_find_with_basename(const char *basename)
Finds a plugin with the specified basename (filename without a path).
PurplePluginType
Plugin types.
Definition: plugin.h:57
@ PURPLE_PLUGIN_STANDARD
Standard plugin.
Definition: plugin.h:59
@ PURPLE_PLUGIN_PROTOCOL
Protocol plugin.
Definition: plugin.h:61
@ PURPLE_PLUGIN_UNKNOWN
Unknown type.
Definition: plugin.h:58
@ PURPLE_PLUGIN_LOADER
Loader plugin.
Definition: plugin.h:60
void purple_plugins_uninit(void)
Uninitializes the plugin subsystem.
gboolean purple_plugin_register(PurplePlugin *plugin)
Registers a plugin and prepares it for loading.
gboolean purple_plugins_enabled(void)
Returns whether or not plugin support is enabled.
gboolean purple_plugin_unload(PurplePlugin *plugin)
Unloads the specified plugin.
void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command)
Unregisters an IPC command in a plugin.
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...
gboolean purple_plugin_reload(PurplePlugin *plugin)
Reloads a plugin.
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.
const gchar * purple_plugin_get_name(const PurplePlugin *plugin)
Returns a plugin's name.
GList * purple_plugins_get_all(void)
Returns a list of all plugins, whether loaded or not.
void purple_plugins_probe(const char *ext)
Probes for plugins in the registered module paths.
PurplePlugin * purple_plugin_new(gboolean native, const char *path)
Creates a new plugin structure.
void purple_plugin_ipc_unregister_all(PurplePlugin *plugin)
Unregisters all IPC commands in a plugin.
PurplePluginAction * purple_plugin_action_new(const char *label, void(*callback)(PurplePluginAction *))
Allocates and returns a new PurplePluginAction.
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.
gboolean purple_plugin_load(PurplePlugin *plugin)
Attempts to load a previously probed plugin.
void * purple_plugin_ipc_call(PurplePlugin *plugin, const char *command, gboolean *ok,...)
Executes an IPC command.
void purple_plugins_unregister_probe_notify_cb(void(*func)(void *))
Unregisters a function that would be called when probing is finished.
const gchar * purple_plugin_get_homepage(const PurplePlugin *plugin)
Returns a plugin's homepage.
GList * purple_plugins_get_loaded(void)
Returns a list of all loaded plugins.
void purple_plugin_action_free(PurplePluginAction *action)
Frees a PurplePluginAction.
const gchar * purple_plugin_get_author(const PurplePlugin *plugin)
Returns a plugin's author.
void purple_plugins_init(void)
Initializes the plugin subsystem.
void purple_plugins_unregister_unload_notify_cb(void(*func)(PurplePlugin *, void *))
Unregisters a function that would be called when a plugin is unloaded.
void purple_plugins_destroy_all(void)
Destroys all registered plugins.
PurplePlugin * purple_plugin_probe(const char *filename)
Probes a plugin, retrieving the information on it and adding it to the list of available plugins.
int PurplePluginPriority
Plugin priority.
Definition: plugin.h:49
gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin)
Returns whether or not a plugin is unloadable.
void purple_plugins_unregister_load_notify_cb(void(*func)(PurplePlugin *, void *))
Unregisters a function that would be called when a plugin is loaded.
void purple_plugin_destroy(PurplePlugin *plugin)
Unloads a plugin and destroys the structure from memory.
PurplePlugin * purple_plugins_find_with_filename(const char *filename)
Finds a plugin with the specified filename (filename with a path).
PurplePlugin * purple_plugins_find_with_id(const char *id)
Finds a plugin with the specified plugin ID.
void purple_plugins_unload_all(void)
Unloads all loaded plugins.
void purple_plugin_disable(PurplePlugin *plugin)
Disable a plugin.
void * purple_plugins_get_handle(void)
Returns the plugin subsystem handle.
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.
void purple_plugins_add_search_path(const char *path)
Add a new directory to search for plugins.
void purple_plugins_register_probe_notify_cb(void(*func)(void *), void *data)
Registers a function that will be called when probing is finished.
const gchar * purple_plugin_get_id(const PurplePlugin *plugin)
Returns a plugin's id.
GList * purple_plugins_get_search_paths(void)
Returns a list of plugin search paths.
const gchar * purple_plugin_get_summary(const PurplePlugin *plugin)
Returns a plugin's summary.
const gchar * purple_plugin_get_description(const PurplePlugin *plugin)
Returns a plugin's description.
const gchar * purple_plugin_get_version(const PurplePlugin *plugin)
Returns a plugin's version.
gboolean purple_plugin_is_loaded(const PurplePlugin *plugin)
Returns whether or not a plugin is currently loaded.
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.
void purple_plugins_save_loaded(const char *key)
Saves the list of loaded plugins to the specified preference key.
PurplePlugin * purple_plugins_find_with_name(const char *name)
Finds a plugin with the specified name.
Plugin Preferences API.
Signal API.
A wrapper for a type, subtype, and specific type of value.
Definition: value.h:90
The structure used in the actions member of PurplePluginInfo.
Definition: plugin.h:195
PurplePlugin * plugin
set to the owning plugin
Definition: plugin.h:200
gpointer context
NULL for plugin actions menu, set to the PurpleConnection for account actions menu.
Definition: plugin.h:204
Detailed information about a plugin.
Definition: plugin.h:79
PurplePluginUiInfo * prefs_info
Used by any plugin to display preferences.
Definition: plugin.h:107
void * ui_info
Used only by UI-specific plugins to build a preference screen with a custom UI.
Definition: plugin.h:105
gboolean(* load)(PurplePlugin *plugin)
If a plugin defines a 'load' function, and it returns FALSE, then the plugin will not be loaded.
Definition: plugin.h:101
Extra information for loader plugins.
Definition: plugin.h:134
int page_num
Reserved.
Definition: plugin.h:176
PurplePluginPrefFrame * frame
Reserved.
Definition: plugin.h:177
A plugin handle.
Definition: plugin.h:152
char * path
The path to the plugin.
Definition: plugin.h:156
void * ipc_data
IPC data.
Definition: plugin.h:159
gboolean loaded
The loaded state.
Definition: plugin.h:154
PurplePluginInfo * info
The plugin information.
Definition: plugin.h:157
void * handle
The module handle.
Definition: plugin.h:155
gboolean unloadable
Unloadable
Definition: plugin.h:161
GList * dependent_plugins
Plugins depending on this.
Definition: plugin.h:162
void * extra
Plugin-specific data.
Definition: plugin.h:160
gboolean native_plugin
Native C plugin.
Definition: plugin.h:153
Value wrapper API.