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:

Go to the source code of 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...

Macros
#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 */
#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
	A plugin handle.
typedef struct _PurplePluginInfo	PurplePluginInfo
	Detailed information about a plugin.
typedef struct _PurplePluginUiInfo	PurplePluginUiInfo
typedef struct _PurplePluginLoaderInfo	PurplePluginLoaderInfo
	Extra information for loader plugins.
typedef struct _PurplePluginAction	PurplePluginAction
	The structure used in the actions member of PurplePluginInfo.
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
Plugin API <br>
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 <br>
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 <br>
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 <br>
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.
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.

Detailed Description

Plugin API.

See also

Plugin Signals

Plugin IDs

Third Party Plugin Translation Support

Definition in file plugin.h.

Macro Definition Documentation

_FUNC_NAME

#define _FUNC_NAME

(

x

)

purple_init_##x##_plugin

Handles the initialization of modules.

Definition at line 221 of file plugin.h.

PURPLE_INIT_PLUGIN

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

PURPLE_PLUGIN_ACTIONS

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

PURPLE_PLUGIN_FLAG_INVISIBLE

#define PURPLE_PLUGIN_FLAG_INVISIBLE   0x01

Definition at line 69 of file plugin.h.

PURPLE_PLUGIN_HAS_ACTIONS

#define PURPLE_PLUGIN_HAS_ACTIONS

(

plugin

)

((plugin)->info != NULL && (plugin)->info->actions != NULL)

Definition at line 209 of file plugin.h.

PURPLE_PLUGIN_HAS_PREF_FRAME

#define PURPLE_PLUGIN_HAS_PREF_FRAME

(

plugin

)

((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)

Definition at line 185 of file plugin.h.

PURPLE_PLUGIN_LOADER_INFO

#define PURPLE_PLUGIN_LOADER_INFO

(

plugin

)

((PurplePluginLoaderInfo *)(plugin)->info->extra_info)

Definition at line 170 of file plugin.h.

PURPLE_PLUGIN_MAGIC

#define PURPLE_PLUGIN_MAGIC   5 /* once we hit 6.0.0 I think we can remove this */

Definition at line 71 of file plugin.h.

PURPLE_PLUGIN_UI_INFO

#define PURPLE_PLUGIN_UI_INFO

(

plugin

)

((PurplePluginUiInfo*)(plugin)->info->prefs_info)

Definition at line 188 of file plugin.h.

PURPLE_PRIORITY_DEFAULT

#define PURPLE_PRIORITY_DEFAULT   0

Definition at line 65 of file plugin.h.

PURPLE_PRIORITY_HIGHEST

#define PURPLE_PRIORITY_HIGHEST   9999

Definition at line 66 of file plugin.h.

PURPLE_PRIORITY_LOWEST

#define PURPLE_PRIORITY_LOWEST   -9999

Definition at line 67 of file plugin.h.

Typedef Documentation

PurplePlugin

typedef struct _PurplePlugin PurplePlugin

A plugin handle.

Definition at line 38 of file plugin.h.

PurplePluginAction

typedef struct _PurplePluginAction PurplePluginAction

The structure used in the actions member of PurplePluginInfo.

Definition at line 47 of file plugin.h.

PurplePluginInfo

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.

PurplePluginLoaderInfo

typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo

Extra information for loader plugins.

Definition at line 44 of file plugin.h.

PurplePluginPriority

typedef int PurplePluginPriority

Plugin priority.

Definition at line 49 of file plugin.h.

PurplePluginUiInfo

typedef struct _PurplePluginUiInfo PurplePluginUiInfo

Definition at line 42 of file plugin.h.

Enumeration Type Documentation

PurplePluginType

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

purple_plugin_action_free()

void purple_plugin_action_free

(

PurplePluginAction *

action

)

Frees a PurplePluginAction.

Parameters

action

The PurplePluginAction to free.

purple_plugin_action_new()

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.

purple_plugin_destroy()

void purple_plugin_destroy

(

PurplePlugin *

plugin

)

Unloads a plugin and destroys the structure from memory.

Parameters

plugin

The plugin handle.

purple_plugin_disable()

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

purple_plugin_get_author()

const gchar * purple_plugin_get_author

(

const PurplePlugin *

plugin

)

Returns a plugin's author.

Parameters

plugin

The plugin.

Returns

The plugin's author.

purple_plugin_get_description()

const gchar * purple_plugin_get_description

(

const PurplePlugin *

plugin

)

Returns a plugin's description.

Parameters

plugin

The plugin.

Returns

The plugin's description.

purple_plugin_get_homepage()

const gchar * purple_plugin_get_homepage

(

const PurplePlugin *

plugin

)

Returns a plugin's homepage.

Parameters

plugin

The plugin.

Returns

The plugin's homepage.

purple_plugin_get_id()

const gchar * purple_plugin_get_id

(

const PurplePlugin *

plugin

)

Returns a plugin's id.

Parameters

plugin

The plugin.

Returns

The plugin's id.

purple_plugin_get_name()

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.

purple_plugin_get_summary()

const gchar * purple_plugin_get_summary

(

const PurplePlugin *

plugin

)

Returns a plugin's summary.

Parameters

plugin

The plugin.

Returns

The plugin's summary.

purple_plugin_get_version()

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.

purple_plugin_ipc_call()

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.

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.

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.

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.

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.

purple_plugin_ipc_unregister()

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.

purple_plugin_ipc_unregister_all()

void purple_plugin_ipc_unregister_all

(

PurplePlugin *

plugin

)

Unregisters all IPC commands in a plugin.

Parameters

plugin

The plugin to unregister the commands from.

purple_plugin_is_loaded()

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.

purple_plugin_is_unloadable()

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

purple_plugin_load()

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()

purple_plugin_new()

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.

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.

Parameters

filename

The plugin's filename.

Returns

The plugin handle.

See also

purple_plugin_load()

purple_plugin_destroy()

purple_plugin_register()

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

purple_plugin_reload()

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()

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()

purple_plugins_add_search_path()

void purple_plugins_add_search_path

(

const char *

path

)

Add a new directory to search for plugins.

Parameters

path	The new search path.

purple_plugins_enabled()

gboolean purple_plugins_enabled

(

void

)

Returns whether or not plugin support is enabled.

Returns

TRUE if plugin support is enabled, or FALSE otherwise.

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

Parameters

basename

The plugin basename.

Returns

The plugin if found, or NULL if not found.

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

Parameters

filename

The plugin filename.

Returns

The plugin if found, or NULL if not found.

purple_plugins_find_with_id()

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.

purple_plugins_find_with_name()

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.

purple_plugins_get_all()

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.

purple_plugins_get_handle()

void * purple_plugins_get_handle

(

void

)

Returns the plugin subsystem handle.

Returns

The plugin sybsystem handle.

purple_plugins_get_loaded()

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.

purple_plugins_get_protocols()

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.

purple_plugins_get_search_paths()

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

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

Parameters

key	The preference key containing the list of plugins.

purple_plugins_probe()

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()

purple_plugins_register_load_notify_cb()

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.

purple_plugins_register_probe_notify_cb()

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.

purple_plugins_register_unload_notify_cb()

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.

purple_plugins_save_loaded()

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.

purple_plugins_unregister_load_notify_cb()

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.

purple_plugins_unregister_probe_notify_cb()

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.

purple_plugins_unregister_unload_notify_cb()

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.