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 203 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 193 of file plugin.h.


Typedef Documentation

typedef int PurplePluginPriority

Plugin priority.

Definition at line 44 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 51 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.


Generated on Fri Jul 3 11:30:48 2009 for pidgin by  doxygen 1.5.5