improves plugin interface

This commit improves the names and the organisation of the
plugin interface for the developpers.

Change-Id: Iaf191efbf8fd5d248884304b648258f0770ec5f5
Signed-off-by: José Bollo <jose.bollo@iot.bzh>

1 files changed, 89 insertions, 38 deletions

diff --git a/include/afb/afb-plugin.h b/include/afb/afb-plugin.h
index 2cfe6289..d3f6423d 100644
--- a/include/afb/afb-plugin.h
+++ b/include/afb/afb-plugin.h
@@ -20,89 +20,140 @@
 #include <afb/afb-req-itf.h>
 #include <afb/afb-evmgr-itf.h>
 
-/* Plugin Type */
-enum  AFB_pluginE
+/*
+ * Definition of the versions of the plugin.
+ * The definition uses hashes.
+ */
+enum  AFB_plugin_version
+{
+       AFB_PLUGIN_VERSION_1 = 123456789        /* version 1 */
+};
+
+/*
+ * Enum for Session/Token/Authentication middleware.
+ * This enumeration is valid for plugins of type 1
+ */
+enum AFB_session_v1
 {
-	AFB_PLUGIN_JSON = 123456789,
-/*	AFB_PLUGIN_JSCRIPT = 987654321, */
-	AFB_PLUGIN_RAW = 987123546
+       AFB_SESSION_NONE = 0,   /* no session and no authentification required */
+       AFB_SESSION_CREATE = 1, /* requires authentification and first call of the session */
+       AFB_SESSION_CLOSE = 2,  /* closes the session after authentification */
+       AFB_SESSION_RENEW = 4,  /* refreshes the token after authentification */
+       AFB_SESSION_CHECK = 8,  /* enforce authentification */
+       AFB_SESSION_MASK = 15   /* convenient mask used internally, bit-or of the previous masks */
 };
 
-/* Enum for Session/Token/Authentication middleware */
-enum AFB_sessionE
+/*
+ * Description of one verb of the API provided by the plugin
+ * This enumeration is valid for plugins of type 1
+ */
+struct AFB_verb_desc_v1
 {
-	AFB_SESSION_NONE = 0,
-	AFB_SESSION_CREATE = 1,
-	AFB_SESSION_CLOSE = 2,
-	AFB_SESSION_RENEW = 4,
-	AFB_SESSION_CHECK = 8,
-	AFB_SESSION_MASK = 15
+       const char *name;                       /* name of the verb */
+       enum AFB_session_v1 session;            /* authorisation and session requirements of the verb */
+       void (*callback)(struct afb_req req);   /* callback function implementing the verb */
+       const char *info;                       /* textual description of the verb */
 };
 
-/* API definition */
-struct AFB_restapi
+/*
+ * Description of the plugins of type 1
+ */
+struct AFB_plugin_desc_v1
 {
-	const char *name;
-	enum AFB_sessionE session;
-	void (*callback)(struct afb_req req);
-	const char *info;
+       const char *info;                       /* textual information about the plugin */
+       const char *prefix;                     /* required prefix name for the plugin */
+       const struct AFB_verb_desc_v1 *verbs;   /* array of descriptions of verbs terminated by a NULL name */
 };
 
-/* Plugin definition */
+/*
+ * Description of a plugin
+ */
 struct AFB_plugin
 {
-	enum AFB_pluginE type;  
-	const char *info;
-	const char *prefix;
-	const struct AFB_restapi *apis;
+       enum AFB_plugin_version type; /* type of the plugin */
+       union {
+               struct AFB_plugin_desc_v1 v1;   /* description of the plugin of type 1 */
+       };
 };
 
-/* config mode */
+/*
+ * config mode
+ */
 enum AFB_Mode {
-	AFB_MODE_LOCAL = 0,
-	AFB_MODE_REMOTE,
-	AFB_MODE_GLOBAL
+       AFB_MODE_LOCAL = 0,     /* run locally */
+       AFB_MODE_REMOTE,        /* run remotely */
+       AFB_MODE_GLOBAL         /* run either remotely or locally (DONT USE! reserved for future) */
 };
 
+/* declaration of features of libsystemd */
 struct sd_event;
 struct sd_bus;
 
+/*
+ * Definition of the facilities provided by the daemon.
+ */
 struct afb_daemon_itf {
-	struct afb_evmgr (*get_evmgr)(void *closure);
-	struct sd_event *(*get_event_loop)(void *closure);
-	struct sd_bus *(*get_user_bus)(void *closure);
-	struct sd_bus *(*get_system_bus)(void *closure);
+       struct afb_evmgr (*get_evmgr)(void *closure);           /* get the event manager */
+       struct sd_event *(*get_event_loop)(void *closure);      /* get the common systemd's event loop */
+       struct sd_bus *(*get_user_bus)(void *closure);          /* get the common systemd's user d-bus */
+       struct sd_bus *(*get_system_bus)(void *closure);        /* get the common systemd's system d-bus */
 };
 
+/*
+ * Structure for accessing daemon.
+ * See also: afb_daemon_get_evmgr, afb_daemon_get_event_loop, afb_daemon_get_user_bus, afb_daemon_get_system_bus
+ */
 struct afb_daemon {
-	const struct afb_daemon_itf *itf;
-	void *closure;
+       const struct afb_daemon_itf *itf;       /* the interfacing functions */
+       void *closure;                          /* the closure when calling these functions */
 };
 
+/*
+ * Interface between the daemon and the plugin.
+ */
 struct AFB_interface
 {
-	int verbosity;
-	enum AFB_Mode mode;
-	struct afb_daemon daemon;
+       struct afb_daemon daemon;       /* access to the daemon facilies */
+       int verbosity;                  /* level of verbosity */
+       enum AFB_Mode mode;             /* run mode (local or remote) */
 };
 
-extern const struct AFB_plugin *pluginRegister (const struct AFB_interface *interface);
+/*
+ * The function for registering the plugin to AFB
+ */
+extern const struct AFB_plugin *pluginAfbV1Register (const struct AFB_interface *interface);
 
+/*
+ * Retrieves the event sender of AFB
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ */
 static inline struct afb_evmgr afb_daemon_get_evmgr(struct afb_daemon daemon)
 {
 	return daemon.itf->get_evmgr(daemon.closure);
 }
 
+/*
+ * Retrieves the common systemd's event loop of AFB
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ */
 static inline struct sd_event *afb_daemon_get_event_loop(struct afb_daemon daemon)
 {
 	return daemon.itf->get_event_loop(daemon.closure);
 }
 
+/*
+ * Retrieves the common systemd's user/session d-bus of AFB
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ */
 static inline struct sd_bus *afb_daemon_get_user_bus(struct afb_daemon daemon)
 {
 	return daemon.itf->get_user_bus(daemon.closure);
 }
 
+/*
+ * Retrieves the common systemd's system d-bus of AFB
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ */
 static inline struct sd_bus *afb_daemon_get_system_bus(struct afb_daemon daemon)
 {
 	return daemon.itf->get_system_bus(daemon.closure);