plugin.h File Reference

Plugin API. More...

#include <glib/glist.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  _PurplePlugin
 A plugin handle. More...
struct  _PurplePluginAction
 The structure used in the actions member of PurplePluginInfo. More...
struct  _PurplePluginInfo
 Detailed information about a plugin. More...
struct  _PurplePluginLoaderInfo
 Extra information for loader plugins. More...
struct  _PurplePluginUiInfo

Defines

#define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo)
 Handles the initialization of modules.
#define PURPLE_PLUGIN_ACTIONS(plugin, context)
#define PURPLE_PLUGIN_FLAG_INVISIBLE   0x01
#define PURPLE_PLUGIN_HAS_ACTIONS(plugin)   ((plugin)->info != NULL && (plugin)->info->actions != NULL)
#define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin)   ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
#define PURPLE_PLUGIN_LOADER_INFO(plugin)   ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
#define PURPLE_PLUGIN_MAGIC   5
#define PURPLE_PLUGIN_UI_INFO(plugin)   ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
#define PURPLE_PRIORITY_DEFAULT   0
#define PURPLE_PRIORITY_HIGHEST   9999
#define PURPLE_PRIORITY_LOWEST   -9999

Typedefs

typedef _PurplePlugin PurplePlugin
typedef _PurplePluginAction PurplePluginAction
typedef _PurplePluginInfo PurplePluginInfo
typedef _PurplePluginLoaderInfo PurplePluginLoaderInfo
typedef int PurplePluginPriority
 Plugin priority.
typedef _PurplePluginUiInfo PurplePluginUiInfo

Enumerations

enum  PurplePluginType { PURPLE_PLUGIN_UNKNOWN = -1, PURPLE_PLUGIN_STANDARD = 0, PURPLE_PLUGIN_LOADER, PURPLE_PLUGIN_PROTOCOL }
 Plugin types. More...

Functions

void purple_plugin_action_free (PurplePluginAction *action)
 Frees a PurplePluginAction.
PurplePluginActionpurple_plugin_action_new (const char *label, void(*callback)(PurplePluginAction *))
 Allocates and returns a new PurplePluginAction.
Plugin API
void purple_plugin_destroy (PurplePlugin *plugin)
 Unloads a plugin and destroys the structure from memory.
const gchar * purple_plugin_get_author (const PurplePlugin *plugin)
 Returns a plugin's author.
const gchar * purple_plugin_get_description (const PurplePlugin *plugin)
 Returns a plugin's description.
const gchar * purple_plugin_get_homepage (const PurplePlugin *plugin)
 Returns a plugin's homepage.
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_summary (const PurplePlugin *plugin)
 Returns a plugin's summary.
const gchar * purple_plugin_get_version (const PurplePlugin *plugin)
 Returns a plugin's version.
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.
gboolean purple_plugin_load (PurplePlugin *plugin)
 Attempts to load a previously probed plugin.
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_reload (PurplePlugin *plugin)
 Reloads a plugin.
gboolean purple_plugin_unload (PurplePlugin *plugin)
 Unloads the specified plugin.
Plugin IPC API
void * purple_plugin_ipc_call (PurplePlugin *plugin, const char *command, gboolean *ok,...)
 Executes an IPC command.
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.
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.
Plugins API
void purple_plugins_add_search_path (const char *path)
 Add a new directory to search for plugins.
void purple_plugins_destroy_all (void)
 Destroys all registered plugins.
gboolean purple_plugins_enabled (void)
 Returns whether or not plugin support is enabled.
PurplePluginpurple_plugins_find_with_basename (const char *basename)
 Finds a plugin with the specified basename (filename without a path).
PurplePluginpurple_plugins_find_with_filename (const char *filename)
 Finds a plugin with the specified filename (filename with a path).
PurplePluginpurple_plugins_find_with_id (const char *id)
 Finds a plugin with the specified plugin ID.
PurplePluginpurple_plugins_find_with_name (const char *name)
 Finds a plugin with the specified name.
GList * purple_plugins_get_all (void)
 Returns a list of all plugins, whether loaded or not.
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.
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.
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_register_probe_notify_cb (void(*func)(void *), void *data)
 Registers a function that will be called when probing is finished.
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_save_loaded (const char *key)
 Saves the list of loaded plugins to the specified preference key.
void purple_plugins_unload_all (void)
 Unloads all loaded plugins.
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_unregister_probe_notify_cb (void(*func)(void *))
 Unregisters a function that would be called when probing is finished.
void purple_plugins_unregister_unload_notify_cb (void(*func)(PurplePlugin *, void *))
 Unregisters a function that would be called when a plugin is unloaded.
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.

purple

Purple is the legal property of its developers, whose names are too numerous to list here. Please refer to the COPYRIGHT file distributed with this source distribution.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Definition in file plugin.h.


Define Documentation

#define PURPLE_INIT_PLUGIN ( pluginname,
initfunc,
plugininfo   ) 

Value:

gboolean purple_init_##pluginname##_plugin(void);\
    gboolean purple_init_##pluginname##_plugin(void) { \
        PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
        plugin->info = &(plugininfo); \
        initfunc((plugin)); \
        purple_plugin_load((plugin)); \
        return purple_plugin_register(plugin); \
    }
Handles the initialization of modules.

Definition at line 201 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 192 of file plugin.h.


Typedef Documentation

typedef int PurplePluginPriority

Plugin priority.

Definition at line 40 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 47 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.