diff options
Diffstat (limited to 'e-util/e-plugin.h')
| -rw-r--r-- | e-util/e-plugin.h | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/e-util/e-plugin.h b/e-util/e-plugin.h new file mode 100644 index 0000000000..c6e132ac6f --- /dev/null +++ b/e-util/e-plugin.h @@ -0,0 +1,221 @@ + +#ifndef _E_PLUGIN_H +#define _E_PLUGIN_H + +#include <glib.h> +#include <glib-object.h> +#include <libxml/tree.h> + +/* ********************************************************************** */ + +typedef struct _EPlugin EPlugin; +typedef struct _EPluginClass EPluginClass; + +#define E_PLUGIN_CLASSID "com.ximian.evolution.plugin" + +/** + * struct _EPlugin - + * + * @object: Superclass. + * @description: A description of the plugin's purpose. + * @name: The name of the plugin. + * @domain: The translation domain for this plugin. + * @hooks: A list of the EPluginHooks this plugin requires. + * @enabled: Whether the plugin is enabled or not. This is not fully + * implemented. + * + * The base EPlugin object is used to represent each plugin directly. + * All of the plugin's hooks are loaded and managed through this + * object. + **/ +struct _EPlugin { + GObject object; + + char *description; + char *name; + char *domain; + GSList *hooks; + + int enabled:1; +}; + +/** + * struct _EPluginClass - + * + * @class: Superclass. + * @type: The plugin type. This is used by the plugin loader to + * determine which plugin object to instantiate to handle the plugin. + * This must be overriden by each subclass to provide a unique name. + * @construct: The construct virtual method scans the XML tree to + * initialise itself. + * @invoke: The invoke virtual method loads the plugin code, resolves + * the function name, and marshals a simple pointer to execute the + * plugin. + * + * The EPluginClass represents each plugin type. The type of each class is + * registered in a global table and is used to instantiate a + * container for each plugin. + * + * It provides two main functions, to load the plugin definition, and + * to invoke a function. Each plugin class is used to handle mappings + * to different languages. + **/ +struct _EPluginClass { + GObjectClass class; + + const char *type; + + int (*construct)(EPlugin *, xmlNodePtr root); + void *(*invoke)(EPlugin *, const char *name, void *data); +}; + +GType e_plugin_get_type(void); + +int e_plugin_construct(EPlugin *ep, xmlNodePtr root); +void e_plugin_add_load_path(const char *); +int e_plugin_load_plugins(void); + +void e_plugin_register_type(GType type); + +void *e_plugin_invoke(EPlugin *ep, const char *name, void *data); +void e_plugin_enable(EPlugin *eph, int state); + +/* static helpers */ +/* maps prop or content to 'g memory' */ +char *e_plugin_xml_prop(xmlNodePtr node, const char *id); +char *e_plugin_xml_prop_domain(xmlNodePtr node, const char *id, const char *domain); +int e_plugin_xml_int(xmlNodePtr node, const char *id, int def); +char *e_plugin_xml_content(xmlNodePtr node); +char *e_plugin_xml_content_domain(xmlNodePtr node, const char *domain); + +/* ********************************************************************** */ +#include <gmodule.h> + +typedef struct _EPluginLib EPluginLib; +typedef struct _EPluginLibClass EPluginLibClass; + +/** + * struct _EPluginLib - + * + * @plugin: Superclass. + * @location: The filename of the shared object. + * @module: The GModule once it is loaded. + * + * This is a concrete EPlugin class. It loads and invokes dynamically + * loaded libraries using GModule. The shared object isn't loaded + * until the first callback is invoked. + **/ +struct _EPluginLib { + EPlugin plugin; + + char *location; + GModule *module; +}; + +/** + * struct _EPluginLibClass - + * + * @plugin_class: Superclass. + * + * The plugin library needs no additional class data. + **/ +struct _EPluginLibClass { + EPluginClass plugin_class; +}; + +GType e_plugin_lib_get_type(void); + +/* ********************************************************************** */ + +typedef struct _EPluginHook EPluginHook; +typedef struct _EPluginHookClass EPluginHookClass; + +/* utilities for subclasses to use */ +typedef struct _EPluginHookTargetMap EPluginHookTargetMap; +typedef struct _EPluginHookTargetKey EPluginHookTargetKey; + +/** + * struct _EPluginHookTargetKey - + * + * @key: Enumeration value as a string. + * @value: Enumeration value as an integer. + * + * A multi-purpose string to id mapping structure used with various + * helper functions to simplify plugin hook subclassing. + **/ +struct _EPluginHookTargetKey { + const char *key; + guint32 value; +}; + +/** + * struct _EPluginHookTargetMap - + * + * @type: The string id of the target. + * @id: The integer id of the target. Maps directly to the type field + * of the various plugin type target id's. + * @mask_bits: A zero-fill terminated array of EPluginHookTargetKeys. + * + * Used by EPluginHook to define mappings of target type enumerations + * to and from strings. Also used to define the mask option names + * when reading the XML plugin hook definitions. + **/ +struct _EPluginHookTargetMap { + const char *type; + int id; + const struct _EPluginHookTargetKey *mask_bits; /* null terminated array */ +}; + +/** + * struct _EPluginHook - A plugin hook. + * + * @object: Superclass. + * @plugin: The parent object. + * + * An EPluginHook is used as a container for each hook a given plugin + * is listening to. + **/ +struct _EPluginHook { + GObject object; + + struct _EPlugin *plugin; +}; + +/** + * struct _EPluginHookClass - + * + * @class: Superclass. + * @id: The plugin hook type. This must be overriden by each subclass + * and is used as a key when loading hook definitions. This string + * should contain a globally unique name followed by a : and a version + * specification. This is to ensure plugins only hook into hooks with + * the right API. + * @construct: Virtual method used to initialise the object when + * loaded. + * @enable: Virtual method used to enable or disable the hook. + * + * The EPluginHookClass represents each hook type. The type of the + * class is registered in a global table and is used to instantiate a + * container for each hook. + **/ +struct _EPluginHookClass { + GObjectClass class; + + const char *id; + + int (*construct)(EPluginHook *eph, EPlugin *ep, xmlNodePtr root); + void (*enable)(EPluginHook *eph, int state); +}; + +GType e_plugin_hook_get_type(void); + +void e_plugin_hook_register_type(GType type); + +EPluginHook * e_plugin_hook_new(EPlugin *ep, xmlNodePtr root); +void e_plugin_hook_enable(EPluginHook *eph, int state); + +/* static methods */ +guint32 e_plugin_hook_mask(xmlNodePtr root, const struct _EPluginHookTargetKey *map, const char *prop); +guint32 e_plugin_hook_id(xmlNodePtr root, const struct _EPluginHookTargetKey *map, const char *prop); + +#endif /* ! _E_PLUGIN_H */ |