/**

 * @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_ */