Mercurial > pidgin
view libpurple/plugin.h @ 32789:8331b45b6200
disapproval of revision '183ac4d83596ebf70192f4694b131e45a7a5a4c5'
author | Ethan Blanton <elb@pidgin.im> |
---|---|
date | Sat, 05 May 2012 17:11:58 +0000 |
parents | 552b5292f36f |
children | 4f6b06139734 3828a61c44da |
line wrap: on
line source
/** * @file plugin.h Plugin API * @ingroup core * @see @ref plugin-signals * @see @ref plugin-ids * @see @ref plugin-i18n */ /* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this * source distribution. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA */ #ifndef _PURPLE_PLUGIN_H_ #define _PURPLE_PLUGIN_H_ #include <glib.h> #include <gmodule.h> #include "signals.h" #include "value.h" /** @copydoc _PurplePlugin */ typedef struct _PurplePlugin PurplePlugin; /** @copydoc _PurplePluginInfo */ typedef struct _PurplePluginInfo PurplePluginInfo; /** @copydoc _PurplePluginUiInfo */ typedef struct _PurplePluginUiInfo PurplePluginUiInfo; /** @copydoc _PurplePluginLoaderInfo */ typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo; /** @copydoc _PurplePluginAction */ typedef struct _PurplePluginAction PurplePluginAction; typedef int PurplePluginPriority; /**< Plugin priority. */ #include "pluginpref.h" /** * Plugin types. */ typedef enum { PURPLE_PLUGIN_UNKNOWN = -1, /**< Unknown type. */ PURPLE_PLUGIN_STANDARD = 0, /**< Standard plugin. */ PURPLE_PLUGIN_LOADER, /**< Loader plugin. */ PURPLE_PLUGIN_PROTOCOL /**< Protocol plugin. */ } PurplePluginType; #define PURPLE_PRIORITY_DEFAULT 0 #define PURPLE_PRIORITY_HIGHEST 9999 #define PURPLE_PRIORITY_LOWEST -9999 #define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01 #define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */ /** * Detailed information about a plugin. * * This is used in the version 2.0 API and up. */ struct _PurplePluginInfo { unsigned int magic; unsigned int major_version; unsigned int minor_version; PurplePluginType type; char *ui_requirement; unsigned long flags; GList *dependencies; PurplePluginPriority priority; char *id; char *name; char *version; char *summary; char *description; char *author; char *homepage; /** * If a plugin defines a 'load' function, and it returns FALSE, * then the plugin will not be loaded. */ gboolean (*load)(PurplePlugin *plugin); gboolean (*unload)(PurplePlugin *plugin); void (*destroy)(PurplePlugin *plugin); void *ui_info; /**< Used only by UI-specific plugins to build a preference screen with a custom UI */ void *extra_info; PurplePluginUiInfo *prefs_info; /**< Used by any plugin to display preferences. If #ui_info has been specified, this will be ignored. */ /** * This callback has a different use depending on whether this * plugin type is PURPLE_PLUGIN_STANDARD or PURPLE_PLUGIN_PROTOCOL. * * If PURPLE_PLUGIN_STANDARD then the list of actions will show up * in the Tools menu, under a submenu with the name of the plugin. * context will be NULL. * * If PURPLE_PLUGIN_PROTOCOL then the list of actions will show up * in the Accounts menu, under a submenu with the name of the * account. context will be set to the PurpleConnection for that * account. This callback will only be called for online accounts. */ GList *(*actions)(PurplePlugin *plugin, gpointer context); void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); }; /** * Extra information for loader plugins. */ struct _PurplePluginLoaderInfo { GList *exts; gboolean (*probe)(PurplePlugin *plugin); gboolean (*load)(PurplePlugin *plugin); gboolean (*unload)(PurplePlugin *plugin); void (*destroy)(PurplePlugin *plugin); void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); }; /** * A plugin handle. */ struct _PurplePlugin { gboolean native_plugin; /**< Native C plugin. */ gboolean loaded; /**< The loaded state. */ void *handle; /**< The module handle. */ char *path; /**< The path to the plugin. */ PurplePluginInfo *info; /**< The plugin information. */ char *error; void *ipc_data; /**< IPC data. */ void *extra; /**< Plugin-specific data. */ gboolean unloadable; /**< Unloadable */ GList *dependent_plugins; /**< Plugins depending on this */ void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); }; #define PURPLE_PLUGIN_LOADER_INFO(plugin) \ ((PurplePluginLoaderInfo *)(plugin)->info->extra_info) struct _PurplePluginUiInfo { PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin); int page_num; /**< Reserved */ PurplePluginPrefFrame *frame; /**< Reserved */ void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); }; #define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \ ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL) #define PURPLE_PLUGIN_UI_INFO(plugin) \ ((PurplePluginUiInfo*)(plugin)->info->prefs_info) /** * The structure used in the actions member of PurplePluginInfo */ struct _PurplePluginAction { char *label; void (*callback)(PurplePluginAction *); /** set to the owning plugin */ PurplePlugin *plugin; /** NULL for plugin actions menu, set to the PurpleConnection for account actions menu */ gpointer context; gpointer user_data; }; #define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \ ((plugin)->info != NULL && (plugin)->info->actions != NULL) #define PURPLE_PLUGIN_ACTIONS(plugin, context) \ (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \ (plugin)->info->actions(plugin, context): NULL) /** * Handles the initialization of modules. */ #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL) # define _FUNC_NAME(x) purple_init_##x##_plugin # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \ gboolean _FUNC_NAME(pluginname)(void);\ gboolean _FUNC_NAME(pluginname)(void) { \ PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \ plugin->info = &(plugininfo); \ initfunc((plugin)); \ purple_plugin_load((plugin)); \ return purple_plugin_register(plugin); \ } #else /* PURPLE_PLUGINS && !PURPLE_STATIC_PRPL */ # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \ G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \ G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \ plugin->info = &(plugininfo); \ initfunc((plugin)); \ return purple_plugin_register(plugin); \ } #endif #ifdef __cplusplus extern "C" { #endif /**************************************************************************/ /** @name Plugin API */ /**************************************************************************/ /*@{*/ /** * Creates a new plugin structure. * * @param native Whether or not the plugin is native. * @param path The path to the plugin, or @c NULL if statically compiled. * * @return A new PurplePlugin structure. */ PurplePlugin *purple_plugin_new(gboolean native, const char *path); /** * Probes a plugin, retrieving the information on it and adding it to the * list of available plugins. * * @param filename The plugin's filename. * * @return The plugin handle. * * @see purple_plugin_load() * @see purple_plugin_destroy() */ PurplePlugin *purple_plugin_probe(const char *filename); /** * Registers a plugin and prepares it for loading. * * This shouldn't be called by anything but the internal module code. * Plugins should use the PURPLE_INIT_PLUGIN() macro to register themselves * with the core. * * @param plugin The plugin to register. * * @return @c TRUE if the plugin was registered successfully. Otherwise * @c FALSE is returned (this happens if the plugin does not contain * the necessary information). */ gboolean purple_plugin_register(PurplePlugin *plugin); /** * Attempts to load a previously probed plugin. * * @param plugin The plugin to load. * * @return @c TRUE if successful, or @c FALSE otherwise. * * @see purple_plugin_reload() * @see purple_plugin_unload() */ gboolean purple_plugin_load(PurplePlugin *plugin); /** * Unloads the specified plugin. * * @param plugin The plugin handle. * * @return @c TRUE if successful, or @c FALSE otherwise. * * @see purple_plugin_load() * @see purple_plugin_reload() */ gboolean purple_plugin_unload(PurplePlugin *plugin); /** * Disable a plugin. * * This function adds the plugin to a list of plugins to "disable at the next * startup" by excluding said plugins from the list of plugins to save. The * UI needs to call purple_plugins_save_loaded() after calling this for it * to have any effect. * * @since 2.3.0 */ void purple_plugin_disable(PurplePlugin *plugin); /** * Reloads a plugin. * * @param plugin The old plugin handle. * * @return @c TRUE if successful, or @c FALSE otherwise. * * @see purple_plugin_load() * @see purple_plugin_unload() */ gboolean purple_plugin_reload(PurplePlugin *plugin); /** * Unloads a plugin and destroys the structure from memory. * * @param plugin The plugin handle. */ void purple_plugin_destroy(PurplePlugin *plugin); /** * Returns whether or not a plugin is currently loaded. * * @param plugin The plugin. * * @return @c TRUE if loaded, or @c FALSE otherwise. */ gboolean purple_plugin_is_loaded(const PurplePlugin *plugin); /** * Returns whether or not a plugin is unloadable. * * If this returns @c TRUE, the plugin is guaranteed to not * be loadable. However, a return value of @c FALSE does not * guarantee the plugin is loadable. * * @param plugin The plugin. * * @return @c TRUE if the plugin is known to be unloadable,\ * @c FALSE otherwise */ gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin); /** * Returns a plugin's id. * * @param plugin The plugin. * * @return The plugin's id. */ const gchar *purple_plugin_get_id(const PurplePlugin *plugin); /** * Returns a plugin's name. * * @param plugin The plugin. * * @return THe name of the plugin, or @c NULL. */ const gchar *purple_plugin_get_name(const PurplePlugin *plugin); /** * Returns a plugin's version. * * @param plugin The plugin. * * @return The plugin's version or @c NULL. */ const gchar *purple_plugin_get_version(const PurplePlugin *plugin); /** * Returns a plugin's summary. * * @param plugin The plugin. * * @return The plugin's summary. */ const gchar *purple_plugin_get_summary(const PurplePlugin *plugin); /** * Returns a plugin's description. * * @param plugin The plugin. * * @return The plugin's description. */ const gchar *purple_plugin_get_description(const PurplePlugin *plugin); /** * Returns a plugin's author. * * @param plugin The plugin. * * @return The plugin's author. */ const gchar *purple_plugin_get_author(const PurplePlugin *plugin); /** * Returns a plugin's homepage. * * @param plugin The plugin. * * @return The plugin's homepage. */ const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin); /*@}*/ /**************************************************************************/ /** @name Plugin IPC API */ /**************************************************************************/ /*@{*/ /** * Registers an IPC command in a plugin. * * @param plugin The plugin to register the command with. * @param command The name of the command. * @param func The function to execute. * @param marshal The marshalling function. * @param ret_value The return value type. * @param num_params The number of parameters. * @param ... The parameter types. * * @return TRUE if the function was registered successfully, or * FALSE otherwise. */ gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command, PurpleCallback func, PurpleSignalMarshalFunc marshal, PurpleValue *ret_value, int num_params, ...); /** * Unregisters an IPC command in a plugin. * * @param plugin The plugin to unregister the command from. * @param command The name of the command. */ void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command); /** * Unregisters all IPC commands in a plugin. * * @param plugin The plugin to unregister the commands from. */ void purple_plugin_ipc_unregister_all(PurplePlugin *plugin); /** * Returns a list of value types used for an IPC command. * * @param plugin The plugin. * @param command The name of the command. * @param ret_value The returned return value. * @param num_params The returned number of parameters. * @param params The returned list of parameters. * * @return TRUE if the command was found, or FALSE otherwise. */ gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command, PurpleValue **ret_value, int *num_params, PurpleValue ***params); /** * Executes an IPC command. * * @param plugin The plugin to execute the command on. * @param command The name of the command. * @param ok TRUE if the call was successful, or FALSE otherwise. * @param ... The parameters to pass. * * @return The return value, which will be NULL if the command doesn't * return a value. */ void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command, gboolean *ok, ...); /*@}*/ /**************************************************************************/ /** @name Plugins API */ /**************************************************************************/ /*@{*/ /** * Add a new directory to search for plugins * * @param path The new search path. */ void purple_plugins_add_search_path(const char *path); /** * Returns a list of plugin search paths. * * @constreturn A list of searched paths. * * @since 2.6.0 */ GList *purple_plugins_get_search_paths(void); /** * Unloads all loaded plugins. */ void purple_plugins_unload_all(void); /** * Unloads all plugins of a specific type. */ void purple_plugins_unload(PurplePluginType type); /** * Destroys all registered plugins. */ void purple_plugins_destroy_all(void); /** * Saves the list of loaded plugins to the specified preference key * * @param key The preference key to save the list of plugins to. */ void purple_plugins_save_loaded(const char *key); /** * Attempts to load all the plugins in the specified preference key * that were loaded when purple last quit. * * @param key The preference key containing the list of plugins. */ void purple_plugins_load_saved(const char *key); /** * Probes for plugins in the registered module paths. * * @param ext The extension type to probe for, or @c NULL for all. * * @see purple_plugin_set_probe_path() */ void purple_plugins_probe(const char *ext); /** * Returns whether or not plugin support is enabled. * * @return TRUE if plugin support is enabled, or FALSE otherwise. */ gboolean purple_plugins_enabled(void); #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_) /** * Registers a function that will be called when probing is finished. * * @param func The callback function. * @param data Data to pass to the callback. * @deprecated If you need this, ask for a plugin-probe signal to be added. */ void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data); #endif #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_) /** * Unregisters a function that would be called when probing is finished. * * @param func The callback function. * @deprecated If you need this, ask for a plugin-probe signal to be added. */ void purple_plugins_unregister_probe_notify_cb(void (*func)(void *)); #endif #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_) /** * Registers a function that will be called when a plugin is loaded. * * @param func The callback function. * @param data Data to pass to the callback. * @deprecated Use the plugin-load signal instead. */ void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *), void *data); #endif #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_) /** * Unregisters a function that would be called when a plugin is loaded. * * @param func The callback function. * @deprecated Use the plugin-load signal instead. */ void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *)); #endif #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_) /** * Registers a function that will be called when a plugin is unloaded. * * @param func The callback function. * @param data Data to pass to the callback. * @deprecated Use the plugin-unload signal instead. */ void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *), void *data); #endif #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_) /** * Unregisters a function that would be called when a plugin is unloaded. * * @param func The callback function. * @deprecated Use the plugin-unload signal instead. */ void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *, void *)); #endif /** * Finds a plugin with the specified name. * * @param name The plugin name. * * @return The plugin if found, or @c NULL if not found. */ PurplePlugin *purple_plugins_find_with_name(const char *name); /** * Finds a plugin with the specified filename (filename with a path). * * @param filename The plugin filename. * * @return The plugin if found, or @c NULL if not found. */ PurplePlugin *purple_plugins_find_with_filename(const char *filename); /** * Finds a plugin with the specified basename (filename without a path). * * @param basename The plugin basename. * * @return The plugin if found, or @c NULL if not found. */ PurplePlugin *purple_plugins_find_with_basename(const char *basename); /** * Finds a plugin with the specified plugin ID. * * @param id The plugin ID. * * @return The plugin if found, or @c NULL if not found. */ PurplePlugin *purple_plugins_find_with_id(const char *id); /** * Returns a list of all loaded plugins. * * @constreturn A list of all loaded plugins. */ GList *purple_plugins_get_loaded(void); /** * Returns a list of all valid protocol plugins. A protocol * plugin is considered invalid if it does not contain the call * to the PURPLE_INIT_PLUGIN() macro, or if it was compiled * against an incompatable API version. * * @constreturn A list of all protocol plugins. */ GList *purple_plugins_get_protocols(void); /** * Returns a list of all plugins, whether loaded or not. * * @constreturn A list of all plugins. */ GList *purple_plugins_get_all(void); /*@}*/ /**************************************************************************/ /** @name Plugins SubSytem API */ /**************************************************************************/ /*@{*/ /** * Returns the plugin subsystem handle. * * @return The plugin sybsystem handle. */ void *purple_plugins_get_handle(void); /** * Initializes the plugin subsystem */ void purple_plugins_init(void); /** * Uninitializes the plugin subsystem */ void purple_plugins_uninit(void); /*@}*/ /** * Allocates and returns a new PurplePluginAction. * * @param label The description of the action to show to the user. * @param callback The callback to call when the user selects this action. */ PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *)); /** * Frees a PurplePluginAction * * @param action The PurplePluginAction to free. */ void purple_plugin_action_free(PurplePluginAction *action); #ifdef __cplusplus } #endif #endif /* _PURPLE_PLUGIN_H_ */