## SwamiPlugin SwamiPlugin |

## Synopsis

                        SwamiPluginInfo;
    gboolean            (*SwamiPluginInitFunc)              (SwamiPlugin *plugin,
                                                             GError **err);
    void                (*SwamiPluginExitFunc)              (SwamiPlugin *plugin);
    gboolean            (*SwamiPluginSaveXmlFunc)           (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);
    gboolean            (*SwamiPluginLoadXmlFunc)           (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);
                        SwamiPlugin;
    #define             SWAMI_PLUGIN_MAGIC
    #define             SWAMI_PLUGIN_INFO                   (init, exit)
    void                swami_plugin_add_path               (const char *path);
    void                swami_plugin_load_all               (void);
    gboolean            swami_plugin_load                   (const char *filename);
    gboolean            swami_plugin_load_absolute          (const char *filename);
    gboolean            swami_plugin_load_plugin            (SwamiPlugin *plugin);
    gboolean            swami_plugin_is_loaded              (SwamiPlugin *plugin);
    SwamiPlugin *       swami_plugin_find                   (const char *name);
    GList *             swami_plugin_get_list               (void);
    gboolean            swami_plugin_save_xml               (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);
    gboolean            swami_plugin_load_xml               (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----GTypeModule
             +----SwamiPlugin

## Implemented Interfaces

SwamiPlugin implements GTypePlugin.

## Properties

      "author"                   gchar*                : Read / Write
      "copyright"                gchar*                : Read / Write
      "descr"                    gchar*                : Read / Write
      "file-name"                gchar*                : Read
      "license"                  gchar*                : Read / Write
      "loaded"                   gboolean              : Read
      "module"                   gpointer              : Read
      "name"                     gchar*                : Read / Write
      "version"                  gchar*                : Read / Write

## Description

## Details

### SwamiPluginInfo

    typedef struct {
      char magic[4];		/* magic string to ensure sanity */
      char *swami_version;		/* version of Swami plugin compiled for */
      SwamiPluginInitFunc init;	/* called to initialize plugin */
      SwamiPluginExitFunc exit;	/* called before plugin is unloaded */
    } SwamiPluginInfo;

### SwamiPluginInitFunc ()

    gboolean            (*SwamiPluginInitFunc)              (SwamiPlugin *plugin,
                                                             GError **err);

A function type called after a plugin has been loaded.

`plugin` : | Plugin object being loaded
`err` : | Location to store error information
Returns : | Should return `TRUE` on success, `FALSE` otherwise (`err` should be set on failure).

### SwamiPluginExitFunc ()

    void                (*SwamiPluginExitFunc)              (SwamiPlugin *plugin);

A function type called before a plugin is unloaded.

`plugin` : | Plugin object being unloaded

### SwamiPluginSaveXmlFunc ()

    gboolean            (*SwamiPluginSaveXmlFunc)           (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);

An optional function type which is called to save a plugin's preference state to an XML tree. The passed in `xmlnode` is an XML node created for this plugin.

`plugin` : | Plugin object to save preference state of
`xmlnode` : | IpatchXmlNode tree to save preferences to
`err` : | Location to store error info to
Returns : | Should return `TRUE` on success, `FALSE` otherwise (in which case `err` should be set).

### SwamiPluginLoadXmlFunc ()

    gboolean            (*SwamiPluginLoadXmlFunc)           (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);

An optional function type which is called to load a plugin's preference state from an XML tree. The passed in `xmlnode` is an XML node for this plugin.

`plugin` : | Plugin object to load preference state to
`xmlnode` : | IpatchXmlNode tree to load preferences from
`err` : | Location to store error info to
Returns : | Should return `TRUE` on success, `FALSE` otherwise (in which case `err` should be set).

### SwamiPlugin

    typedef struct _SwamiPlugin SwamiPlugin;

### SWAMI_PLUGIN_MAGIC

    #define SWAMI_PLUGIN_MAGIC "SWMI"

### SWAMI_PLUGIN_INFO()

    #define             SWAMI_PLUGIN_INFO(init, exit)

### swami_plugin_add_path ()

    void                swami_plugin_add_path               (const char *path);

Add a directory to the path searched for plugins.

`path` : | The directory to add to the search path

### swami_plugin_load_all ()

    void                swami_plugin_load_all               (void);

Load all plugins in the plugin search path.

### swami_plugin_load ()

    gboolean            swami_plugin_load                   (const char *filename);

Load the named plugin. Name should be the plugin file name ("libplugin.so" on Linux for example).

`filename` : | File name of plugin to load
Returns : | Whether the plugin was loaded or not

### swami_plugin_load_absolute ()

    gboolean            swami_plugin_load_absolute          (const char *filename);

Load the named plugin. Name should be the full path and file name of the plugin to load.

`filename` : | Name of plugin to load
Returns : | whether the plugin was loaded or not

### swami_plugin_load_plugin ()

    gboolean            swami_plugin_load_plugin            (SwamiPlugin *plugin);

Load the given plugin.

`plugin` : | The plugin to load
Returns : | `TRUE` on success (loaded or already loaded), `FALSE` otherwise

### swami_plugin_is_loaded ()

    gboolean            swami_plugin_is_loaded              (SwamiPlugin *plugin);

Queries if the plugin is loaded into memory

`plugin` : | Plugin to query
Returns : | `TRUE` is loaded, `FALSE` otherwise

### swami_plugin_find ()

    SwamiPlugin *       swami_plugin_find                   (const char *name);

Search the list of registered plugins for one with the given plugin name (not file name).

`name` : | Name of plugin to find
Returns : | Pointer to the SwamiPlugin if found, `NULL` otherwise

### swami_plugin_get_list ()

    GList *             swami_plugin_get_list               (void);

get the currently loaded plugins

Returns : | a GList of SwamiPlugin elements which should be freed with g_list_free when finished with.

### swami_plugin_save_xml ()

    gboolean            swami_plugin_save_xml               (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);

Save a plugin's preferences state to XML. Not all plugins implement this method. Check if the xml_save field is set for `plugin` before calling, just returns `TRUE` if not implemented.

`plugin` : | Swami plugin
`xmlnode` : | XML node to save plugin state to
`err` : | Location to store error info or `NULL` to ignore
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set)

### swami_plugin_load_xml ()

    gboolean            swami_plugin_load_xml               (SwamiPlugin *plugin,
                                                             GNode *xmlnode,
                                                             GError **err);

Load a plugin's preferences state from XML. Not all plugins implement this method. Check if the xml_load field is set for `plugin` before calling, just returns `TRUE` if not implemented.

`plugin` : | Swami plugin
`xmlnode` : | XML node to load plugin state from
`err` : | Location to store error info or `NULL` to ignore
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set)

## Property Details

### The `"author"` property

      "author"                   gchar*                : Read / Write

Author of the plugin.

Default value: NULL

### The `"copyright"` property

      "copyright"                gchar*                : Read / Write

Copyright string.

Default value: NULL

### The `"descr"` property

      "descr"                    gchar*                : Read / Write

Description of plugin.

Default value: NULL

### The `"file-name"` property

      "file-name"                gchar*                : Read

Name of plugin file.

Default value: NULL

### The `"license"` property

      "license"                  gchar*                : Read / Write

Plugin license type.

Default value: NULL

### The `"loaded"` property

      "loaded"                   gboolean              : Read

Loaded state of plugin.

Default value: FALSE

### The `"module"` property

      "module"                   gpointer              : Read

GModule of plugin.

### The `"name"` property

      "name"                     gchar*                : Read / Write

Name of plugin.

Default value: NULL

### The `"version"` property

      "version"                  gchar*                : Read / Write

Plugin specific version.

Default value: NULL