Merged notzed-eplugin-2-branch to head.

svn path=/trunk/; revision=27300

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 */