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

PurplePluginActionpurple_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
PurplePluginpurple_plugin_new (gboolean native, const char *path)
 Creates a new plugin structure.
PurplePluginpurple_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.
PurplePluginpurple_plugins_find_with_name (const char *name)
 Finds a plugin with the specified name.
PurplePluginpurple_plugins_find_with_filename (const char *filename)
 Finds a plugin with the specified filename (filename with a path).
PurplePluginpurple_plugins_find_with_basename (const char *basename)
 Finds a plugin with the specified basename (filename without a path).
PurplePluginpurple_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

Macro Definition 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.

The structure used in the actions member of PurplePluginInfo.

Definition at line 47 of file plugin.h.

Detailed information about a plugin.

This is used in the version 2.0 API and up.

Definition at line 40 of file plugin.h.

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.

Definition at line 42 of file plugin.h.

Enumeration Type Documentation

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
actionThe PurplePluginAction to free.
PurplePluginAction* purple_plugin_action_new ( const char *  label,
void(*)(PurplePluginAction *)  callback 
)

Allocates and returns a new PurplePluginAction.

Parameters
labelThe description of the action to show to the user.
callbackThe 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
pluginThe 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
pluginThe plugin.
Returns
The plugin's author.
const gchar* purple_plugin_get_description ( const PurplePlugin plugin)

Returns a plugin's description.

Parameters
pluginThe plugin.
Returns
The plugin's description.
const gchar* purple_plugin_get_homepage ( const PurplePlugin plugin)

Returns a plugin's homepage.

Parameters
pluginThe plugin.
Returns
The plugin's homepage.
const gchar* purple_plugin_get_id ( const PurplePlugin plugin)

Returns a plugin's id.

Parameters
pluginThe plugin.
Returns
The plugin's id.
const gchar* purple_plugin_get_name ( const PurplePlugin plugin)

Returns a plugin's name.

Parameters
pluginThe plugin.
Returns
THe name of the plugin, or NULL.
const gchar* purple_plugin_get_summary ( const PurplePlugin plugin)

Returns a plugin's summary.

Parameters
pluginThe plugin.
Returns
The plugin's summary.
const gchar* purple_plugin_get_version ( const PurplePlugin plugin)

Returns a plugin's version.

Parameters
pluginThe 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
pluginThe plugin to execute the command on.
commandThe name of the command.
okTRUE 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
pluginThe plugin.
commandThe name of the command.
ret_valueThe returned return value.
num_paramsThe returned number of parameters.
paramsThe 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
pluginThe plugin to register the command with.
commandThe name of the command.
funcThe function to execute.
marshalThe marshalling function.
ret_valueThe return value type.
num_paramsThe 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
pluginThe plugin to unregister the command from.
commandThe name of the command.
void purple_plugin_ipc_unregister_all ( PurplePlugin plugin)

Unregisters all IPC commands in a plugin.

Parameters
pluginThe plugin to unregister the commands from.
gboolean purple_plugin_is_loaded ( const PurplePlugin plugin)

Returns whether or not a plugin is currently loaded.

Parameters
pluginThe 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
pluginThe 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
pluginThe 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
nativeWhether or not the plugin is native.
pathThe 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
filenameThe 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
pluginThe 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
pluginThe 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
pluginThe 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
pathThe 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
basenameThe 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
filenameThe 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
idThe 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
nameThe 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
keyThe preference key containing the list of plugins.
void purple_plugins_probe ( const char *  ext)

Probes for plugins in the registered module paths.

Parameters
extThe 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
funcThe callback function.
dataData 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
funcThe callback function.
dataData 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
funcThe callback function.
dataData 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
keyThe 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
funcThe 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
funcThe 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
funcThe callback function.
Deprecated:
Use the plugin-unload signal instead.
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!