plugin.h File Reference

Plugin API. More...

#include <glib.h>
#include <gmodule.h>
#include "signals.h"
#include "value.h"
#include "pluginpref.h"

Include dependency graph for plugin.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	_PurplePluginInfo
	Detailed information about a plugin. More...
struct	_PurplePluginLoaderInfo
	Extra information for loader plugins. More...
struct	_PurplePlugin
	A plugin handle. More...
struct	_PurplePluginUiInfo
struct	_PurplePluginAction
	The structure used in the actions member of PurplePluginInfo. More...
Defines
#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
#define	PURPLE_PLUGIN_LOADER_INFO(plugin) ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
#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)
#define	PURPLE_PLUGIN_HAS_ACTIONS(plugin) ((plugin)->info != NULL && (plugin)->info->actions != NULL)
#define	PURPLE_PLUGIN_ACTIONS(plugin, context)
#define	_FUNC_NAME(x) purple_init_##x##_plugin
	Handles the initialization of modules.
#define	PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo)
Typedefs
typedef struct _PurplePlugin	PurplePlugin
typedef struct _PurplePluginInfo	PurplePluginInfo
typedef struct _PurplePluginUiInfo	PurplePluginUiInfo
typedef struct _PurplePluginLoaderInfo	PurplePluginLoaderInfo
typedef struct _PurplePluginAction	PurplePluginAction
typedef int	PurplePluginPriority
	Plugin priority.
Enumerations
enum	PurplePluginType { PURPLE_PLUGIN_UNKNOWN = -1, PURPLE_PLUGIN_STANDARD = 0, PURPLE_PLUGIN_LOADER, PURPLE_PLUGIN_PROTOCOL }
	Plugin types. More...
Functions
PurplePluginAction *	purple_plugin_action_new (const char label, void(callback)(PurplePluginAction *))
	Allocates and returns a new PurplePluginAction.
void	purple_plugin_action_free (PurplePluginAction *action)
	Frees a PurplePluginAction.
Plugin API
PurplePlugin *	purple_plugin_new (gboolean native, const char *path)
	Creates a new plugin structure.
PurplePlugin *	purple_plugin_probe (const char *filename)
	Probes a plugin, retrieving the information on it and adding it to the list of available plugins.
gboolean	purple_plugin_register (PurplePlugin *plugin)
	Registers a plugin and prepares it for loading.
gboolean	purple_plugin_load (PurplePlugin *plugin)
	Attempts to load a previously probed plugin.
gboolean	purple_plugin_unload (PurplePlugin *plugin)
	Unloads the specified plugin.
void	purple_plugin_disable (PurplePlugin *plugin)
	Disable a plugin.
gboolean	purple_plugin_reload (PurplePlugin *plugin)
	Reloads a plugin.
void	purple_plugin_destroy (PurplePlugin *plugin)
	Unloads a plugin and destroys the structure from memory.
gboolean	purple_plugin_is_loaded (const PurplePlugin *plugin)
	Returns whether or not a plugin is currently loaded.
gboolean	purple_plugin_is_unloadable (const PurplePlugin *plugin)
	Returns whether or not a plugin is unloadable.
const gchar *	purple_plugin_get_id (const PurplePlugin *plugin)
	Returns a plugin's id.
const gchar *	purple_plugin_get_name (const PurplePlugin *plugin)
	Returns a plugin's name.
const gchar *	purple_plugin_get_version (const PurplePlugin *plugin)
	Returns a plugin's version.
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_author (const PurplePlugin *plugin)
	Returns a plugin's author.
const gchar *	purple_plugin_get_homepage (const PurplePlugin *plugin)
	Returns a plugin's homepage.
Plugin IPC API
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.
void	purple_plugin_ipc_unregister (PurplePlugin plugin, const char command)
	Unregisters an IPC command in a plugin.
void	purple_plugin_ipc_unregister_all (PurplePlugin *plugin)
	Unregisters all IPC commands in 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.
void *	purple_plugin_ipc_call (PurplePlugin plugin, const char command, gboolean *ok,...)
	Executes an IPC command.
Plugins API
void	purple_plugins_add_search_path (const char *path)
	Add a new directory to search for plugins.
GList *	purple_plugins_get_search_paths (void)
	Returns a list of plugin search paths.
void	purple_plugins_unload_all (void)
	Unloads all loaded plugins.
void	purple_plugins_unload (PurplePluginType type)
	Unloads all plugins of a specific type.
void	purple_plugins_destroy_all (void)
	Destroys all registered plugins.
void	purple_plugins_save_loaded (const char *key)
	Saves the list of loaded plugins to the specified preference key.
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 quit.
void	purple_plugins_probe (const char *ext)
	Probes for plugins in the registered module paths.
gboolean	purple_plugins_enabled (void)
	Returns whether or not plugin support is enabled.
void	purple_plugins_register_probe_notify_cb (void(func)(void ), void *data)
	Registers a function that will be called when probing is finished.
void	purple_plugins_unregister_probe_notify_cb (void(func)(void ))
	Unregisters a function that would be called when probing is finished.
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_unregister_load_notify_cb (void(func)(PurplePlugin , void *))
	Unregisters a function that would be called when a plugin is 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_unregister_unload_notify_cb (void(func)(PurplePlugin , void *))
	Unregisters a function that would be called when a plugin is unloaded.
PurplePlugin *	purple_plugins_find_with_name (const char *name)
	Finds a plugin with the specified name.
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_basename (const char *basename)
	Finds a plugin with the specified basename (filename without a path).
PurplePlugin *	purple_plugins_find_with_id (const char *id)
	Finds a plugin with the specified plugin ID.
GList *	purple_plugins_get_loaded (void)
	Returns a list of all loaded plugins.
GList *	purple_plugins_get_protocols (void)
	Returns a list of all valid protocol plugins.
GList *	purple_plugins_get_all (void)
	Returns a list of all plugins, whether loaded or not.
Plugins SubSytem API
void *	purple_plugins_get_handle (void)
	Returns the plugin subsystem handle.
void	purple_plugins_init (void)
	Initializes the plugin subsystem.
void	purple_plugins_uninit (void)
	Uninitializes the plugin subsystem.

Detailed Description

Plugin API.

See also:

Plugin Signals

Plugin IDs

Third Party Plugin Translation Support

Definition in file plugin.h.

Define Documentation

#define PURPLE_INIT_PLUGIN	(	pluginname,
		initfunc,
		plugininfo	)

Value:

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); \
    }

Definition at line 222 of file plugin.h.

#define PURPLE_PLUGIN_ACTIONS	(	plugin,
		context		)

Value:

(PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
    (plugin)->info->actions(plugin, context): NULL)

Definition at line 212 of file plugin.h.

Typedef Documentation

typedef struct _PurplePlugin PurplePlugin

A plugin handle.

Definition at line 38 of file plugin.h.

typedef struct _PurplePluginAction PurplePluginAction

The structure used in the actions member of PurplePluginInfo.

Definition at line 47 of file plugin.h.

typedef struct _PurplePluginInfo PurplePluginInfo

Detailed information about a plugin.

This is used in the version 2.0 API and up.

Definition at line 40 of file plugin.h.

typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo

Extra information for loader plugins.

Definition at line 44 of file plugin.h.

typedef int PurplePluginPriority

Plugin priority.

Definition at line 49 of file plugin.h.

typedef struct _PurplePluginUiInfo PurplePluginUiInfo

Definition at line 42 of file plugin.h.

Enumeration Type Documentation

enum PurplePluginType

Plugin types.

Enumerator:

PURPLE_PLUGIN_UNKNOWN	Unknown type.
PURPLE_PLUGIN_STANDARD	Standard plugin.
PURPLE_PLUGIN_LOADER	Loader plugin.
PURPLE_PLUGIN_PROTOCOL	Protocol plugin.

Definition at line 56 of file plugin.h.

Function Documentation

void purple_plugin_action_free ( PurplePluginAction * action )

Frees a PurplePluginAction.

Parameters:

action

The PurplePluginAction to free.

PurplePluginAction* purple_plugin_action_new	(	const char *	label,
		void()(PurplePluginAction )	callback
	)

Allocates and returns a new PurplePluginAction.

Parameters:

	label	The description of the action to show to the user.
	callback	The callback to call when the user selects this action.

void purple_plugin_destroy ( PurplePlugin * plugin )

Unloads a plugin and destroys the structure from memory.

Parameters:

plugin

The plugin handle.

void purple_plugin_disable ( 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

const gchar* purple_plugin_get_author ( const PurplePlugin * plugin )

Returns a plugin's author.

Parameters:

plugin

The plugin.

Returns:: The plugin's author.

const gchar* purple_plugin_get_description ( const PurplePlugin * plugin )

Returns a plugin's description.

Parameters:

plugin

The plugin.

Returns:: The plugin's description.

const gchar* purple_plugin_get_homepage ( const PurplePlugin * plugin )

Returns a plugin's homepage.

Parameters:

plugin

The plugin.

Returns:: The plugin's homepage.

const gchar* purple_plugin_get_id ( const PurplePlugin * plugin )

Returns a plugin's id.

Parameters:

plugin

The plugin.

Returns:: The plugin's id.

const gchar* purple_plugin_get_name ( const PurplePlugin * plugin )

Returns a plugin's name.

Parameters:

plugin

The plugin.

Returns:: THe name of the plugin, or NULL.

const gchar* purple_plugin_get_summary ( const PurplePlugin * plugin )

Returns a plugin's summary.

Parameters:

plugin

The plugin.

Returns:: The plugin's summary.

const gchar* purple_plugin_get_version ( const PurplePlugin * plugin )

Returns a plugin's version.

Parameters:

plugin

The plugin.

Returns:: The plugin's version or NULL.

void* purple_plugin_ipc_call	(	PurplePlugin *	plugin,
		const char *	command,
		gboolean *	ok,
			...
	)

Executes an IPC command.

Parameters:

	plugin	The plugin to execute the command on.
	command	The name of the command.
	ok	TRUE if the call was successful, or FALSE otherwise.
	...	The parameters to pass.

Returns:: The return value, which will be NULL if the command doesn't return a value.

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.

Parameters:

	plugin	The plugin.
	command	The name of the command.
	ret_value	The returned return value.
	num_params	The returned number of parameters.
	params	The returned list of parameters.

Returns:: TRUE if the command was found, or FALSE otherwise.

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.

Parameters:

	plugin	The plugin to register the command with.
	command	The name of the command.
	func	The function to execute.
	marshal	The marshalling function.
	ret_value	The return value type.
	num_params	The number of parameters.
	...	The parameter types.

Returns:: TRUE if the function was registered successfully, or FALSE otherwise.

void purple_plugin_ipc_unregister	(	PurplePlugin *	plugin,
		const char *	command
	)

Unregisters an IPC command in a plugin.

Parameters:

	plugin	The plugin to unregister the command from.
	command	The name of the command.

void purple_plugin_ipc_unregister_all ( PurplePlugin * plugin )

Unregisters all IPC commands in a plugin.

Parameters:

plugin

The plugin to unregister the commands from.

gboolean purple_plugin_is_loaded ( const PurplePlugin * plugin )

Returns whether or not a plugin is currently loaded.

Parameters:

plugin

The plugin.

Returns:: TRUE if loaded, or FALSE otherwise.

gboolean purple_plugin_is_unloadable ( const PurplePlugin * plugin )

Returns whether or not a plugin is unloadable.

If this returns TRUE, the plugin is guaranteed to not be loadable. However, a return value of FALSE does not guarantee the plugin is loadable.

Parameters:

plugin

The plugin.

Returns:: TRUE if the plugin is known to be unloadable,\ FALSE otherwise

gboolean purple_plugin_load ( PurplePlugin * plugin )

Attempts to load a previously probed plugin.

Parameters:

plugin

The plugin to load.

Returns:: TRUE if successful, or FALSE otherwise.

See also:: purple_plugin_reload()
purple_plugin_unload()

PurplePlugin* purple_plugin_new	(	gboolean	native,
		const char *	path
	)

Creates a new plugin structure.

Parameters:

	native	Whether or not the plugin is native.
	path	The path to the plugin, or `NULL` if statically compiled.

Returns:: A new PurplePlugin structure.

PurplePlugin* purple_plugin_probe ( const char * filename )

Probes a plugin, retrieving the information on it and adding it to the list of available plugins.

Parameters:

filename

The plugin's filename.

Returns:: The plugin handle.

See also:: purple_plugin_load()
purple_plugin_destroy()

gboolean purple_plugin_register ( PurplePlugin * plugin )

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.

Parameters:

plugin

The plugin to register.

Returns:: TRUE if the plugin was registered successfully. Otherwise FALSE is returned (this happens if the plugin does not contain the necessary information).

gboolean purple_plugin_reload ( PurplePlugin * plugin )

Reloads a plugin.

Parameters:

plugin

The old plugin handle.

Returns:: TRUE if successful, or FALSE otherwise.

See also:: purple_plugin_load()
purple_plugin_unload()

gboolean purple_plugin_unload ( PurplePlugin * plugin )

Unloads the specified plugin.

Parameters:

plugin

The plugin handle.

Returns:: TRUE if successful, or FALSE otherwise.

See also:: purple_plugin_load()
purple_plugin_reload()

void purple_plugins_add_search_path ( const char * path )

Add a new directory to search for plugins.

Parameters:

path

The new search path.

gboolean purple_plugins_enabled ( void )

Returns whether or not plugin support is enabled.

Returns:: TRUE if plugin support is enabled, or FALSE otherwise.

PurplePlugin* purple_plugins_find_with_basename ( const char * basename )

Finds a plugin with the specified basename (filename without a path).

Parameters:

basename

The plugin basename.

Returns:: The plugin if found, or NULL if not found.

PurplePlugin* purple_plugins_find_with_filename ( const char * filename )

Finds a plugin with the specified filename (filename with a path).

Parameters:

filename

The plugin filename.

Returns:: The plugin if found, or NULL if not found.

PurplePlugin* purple_plugins_find_with_id ( const char * id )

Finds a plugin with the specified plugin ID.

Parameters:

id

The plugin ID.

Returns:: The plugin if found, or NULL if not found.

PurplePlugin* purple_plugins_find_with_name ( const char * name )

Finds a plugin with the specified name.

Parameters:

name

The plugin name.

Returns:: The plugin if found, or NULL if not found.

GList* purple_plugins_get_all ( void )

Returns a list of all plugins, whether loaded or not.

Note:: The return value of this function must not be modified or freed.

Returns:: A list of all plugins.

void* purple_plugins_get_handle ( void )

Returns the plugin subsystem handle.

Returns:: The plugin sybsystem handle.

GList* purple_plugins_get_loaded ( void )

Returns a list of all loaded plugins.

Note:: The return value of this function must not be modified or freed.

Returns:: A list of all loaded plugins.

GList* purple_plugins_get_protocols ( 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.

Note:: The return value of this function must not be modified or freed.

Returns:: A list of all protocol plugins.

GList* purple_plugins_get_search_paths ( void )

Returns a list of plugin search paths.

Note:: The return value of this function must not be modified or freed.

Returns:: A list of searched paths.

Since:: 2.6.0

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 quit.

Parameters:

key

The preference key containing the list of plugins.

void purple_plugins_probe ( const char * ext )

Probes for plugins in the registered module paths.

Parameters:

ext The extension type to probe for, or NULL for all.

See also:: purple_plugin_set_probe_path()

void purple_plugins_register_load_notify_cb	(	void()(PurplePlugin , void *)	func,
		void *	data
	)

Registers a function that will be called when a plugin is loaded.

Parameters:

	func	The callback function.
	data	Data to pass to the callback.

Deprecated:: Use the plugin-load signal instead.

void purple_plugins_register_probe_notify_cb	(	void()(void )	func,
		void *	data
	)

Registers a function that will be called when probing is finished.

Parameters:

	func	The callback function.
	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_unload_notify_cb	(	void()(PurplePlugin , void *)	func,
		void *	data
	)

Registers a function that will be called when a plugin is unloaded.

Parameters:

	func	The callback function.
	data	Data to pass to the callback.

Deprecated:: Use the plugin-unload signal instead.

void purple_plugins_save_loaded ( const char * key )

Saves the list of loaded plugins to the specified preference key.

Parameters:

key

The preference key to save the list of plugins to.

void purple_plugins_unregister_load_notify_cb ( void(*)(PurplePlugin *, void *) func )

Unregisters a function that would be called when a plugin is loaded.

Parameters:

func

The callback function.

Deprecated:: Use the plugin-load signal instead.

void purple_plugins_unregister_probe_notify_cb ( void(*)(void *) func )

Unregisters a function that would be called when probing is finished.

Parameters:

func

The callback function.

Deprecated:: If you need this, ask for a plugin-probe signal to be added.

void purple_plugins_unregister_unload_notify_cb ( void(*)(PurplePlugin *, void *) func )

Unregisters a function that would be called when a plugin is unloaded.

Parameters:

func

The callback function.

Deprecated:: Use the plugin-unload signal instead.

Context Navigation

plugin.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation