plugin.h File Reference

Plugin API. More...

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

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

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

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.
void purple_plugins_unload_all (void)
 Unloads all loaded plugins.
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

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 208 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 198 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.

typedef struct _PurplePluginUiInfo PurplePluginUiInfo

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

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.