Prepare migration to binding v2

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

5 files changed, 181 insertions, 119 deletions

diff --git a/include/afb/afb-binding-v1.h b/include/afb/afb-binding-v1.h
new file mode 100644
index 00000000..4fbe8f9b
--- /dev/null
+++ b/include/afb/afb-binding-v1.h
@@ -0,0 +1,109 @@
+/*
+ * Copyright (C) 2016, 2017 "IoT.bzh"
+ * Author: José Bollo <jose.bollo@iot.bzh>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+struct afb_binding_interface;
+
+/*
+ * Function for registering the binding
+ *
+ * A binding V1 MUST have an exported function of name
+ *
+ *              afbBindingV1Register
+ *
+ * This function is called during loading of the binding. It
+ * receives an 'interface' that should be recorded for later access to
+ * functions provided by the framework.
+ *
+ * This function MUST return the address of a structure that describes
+ * the binding and its implemented verbs.
+ *
+ * In case of initialisation error, NULL must be returned.
+ *
+ * Be aware that the given 'interface' is not fully functionnal
+ * because no provision is given to the name and description
+ * of the binding. Check the function 'afbBindingV1ServiceInit'
+ * defined in the file <afb/afb-service-itf.h> because when
+ * the function 'afbBindingV1ServiceInit' is called, the 'interface'
+ * is fully functionnal.
+ */
+extern const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *interface);
+
+/*
+ * Enum for Session/Token/Assurance middleware.
+ * This enumeration is valid for bindings of type 1
+ */
+enum afb_session_v1
+{
+       AFB_SESSION_NONE = 0,   /* nothing required */
+       AFB_SESSION_CREATE = 1, /* Obsolete */
+       AFB_SESSION_CLOSE = 2,  /* After token authentification, closes the session at end */
+       AFB_SESSION_RENEW = 4,  /* After token authentification, refreshes the token at end */
+       AFB_SESSION_CHECK = 8,  /* Requires token authentification */
+
+       AFB_SESSION_LOA_GE = 16, /* check that the LOA is greater or equal to the given value */
+       AFB_SESSION_LOA_LE = 32, /* check that the LOA is lesser or equal to the given value */
+       AFB_SESSION_LOA_EQ = 48, /* check that the LOA is equal to the given value */
+
+       AFB_SESSION_LOA_SHIFT = 6, /* shift for LOA */
+       AFB_SESSION_LOA_MASK = 7,  /* mask for LOA */
+
+       AFB_SESSION_LOA_0 = 0,   /* value for LOA of 0 */
+       AFB_SESSION_LOA_1 = 64,  /* value for LOA of 1 */
+       AFB_SESSION_LOA_2 = 128, /* value for LOA of 2 */
+       AFB_SESSION_LOA_3 = 192, /* value for LOA of 3 */
+       AFB_SESSION_LOA_4 = 256, /* value for LOA of 4 */
+
+       AFB_SESSION_LOA_LE_0 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_0, /* check LOA <= 0 */
+       AFB_SESSION_LOA_LE_1 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_1, /* check LOA <= 1 */
+       AFB_SESSION_LOA_LE_2 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_2, /* check LOA <= 2 */
+       AFB_SESSION_LOA_LE_3 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_3, /* check LOA <= 3 */
+
+       AFB_SESSION_LOA_GE_0 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_0, /* check LOA >= 0 */
+       AFB_SESSION_LOA_GE_1 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_1, /* check LOA >= 1 */
+       AFB_SESSION_LOA_GE_2 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_2, /* check LOA >= 2 */
+       AFB_SESSION_LOA_GE_3 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_3, /* check LOA >= 3 */
+
+       AFB_SESSION_LOA_EQ_0 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_0, /* check LOA == 0 */
+       AFB_SESSION_LOA_EQ_1 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_1, /* check LOA == 1 */
+       AFB_SESSION_LOA_EQ_2 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_2, /* check LOA == 2 */
+       AFB_SESSION_LOA_EQ_3 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_3  /* check LOA == 3 */
+};
+
+/*
+ * Description of one verb of the API provided by the binding
+ * This enumeration is valid for bindings of type version 1
+ */
+struct afb_verb_desc_v1
+{
+       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 */
+};
+
+/*
+ * Description of the bindings of type version 1
+ */
+struct afb_binding_desc_v1
+{
+       const char *info;                       /* textual information about the binding */
+       const char *prefix;                     /* required prefix name for the binding */
+       const struct afb_verb_desc_v1 *verbs;   /* array of descriptions of verbs terminated by a NULL name */
+};
+
diff --git a/include/afb/afb-binding.h b/include/afb/afb-binding.h
index 41ce0c52..8df08ded 100644
--- a/include/afb/afb-binding.h
+++ b/include/afb/afb-binding.h
@@ -29,17 +29,16 @@
  *
  * A binding is a shared library. This shared library must have at least one
  * exported symbol for being registered in afb-daemon.
- * For the current version of afb-daemon, the function exported MUST be named
  *
- *                  afbBindingV1Register
  */
 
 /*
  * Some function of the library are exported to afb-daemon.
  */
 
-#include <afb/afb-event-itf.h>
-#include <afb/afb-req-itf.h>
+#include "afb-event-itf.h"
+#include "afb-req-itf.h"
+#include "afb-binding-v1.h"
 
 /*
  * Definition of the type+versions of the binding.
@@ -51,69 +50,6 @@ enum  afb_binding_type
 };
 
 /*
- * Enum for Session/Token/Assurance middleware.
- * This enumeration is valid for bindings of type 1
- */
-enum afb_session_v1
-{
-       AFB_SESSION_NONE = 0,   /* nothing required */
-       AFB_SESSION_CREATE = 1, /* Obsolete */
-       AFB_SESSION_CLOSE = 2,  /* After token authentification, closes the session at end */
-       AFB_SESSION_RENEW = 4,  /* After token authentification, refreshes the token at end */
-       AFB_SESSION_CHECK = 8,  /* Requires token authentification */
-
-       AFB_SESSION_LOA_GE = 16, /* check that the LOA is greater or equal to the given value */
-       AFB_SESSION_LOA_LE = 32, /* check that the LOA is lesser or equal to the given value */
-       AFB_SESSION_LOA_EQ = 48, /* check that the LOA is equal to the given value */
-
-       AFB_SESSION_LOA_SHIFT = 6, /* shift for LOA */
-       AFB_SESSION_LOA_MASK = 7,  /* mask for LOA */
-
-       AFB_SESSION_LOA_0 = 0,   /* value for LOA of 0 */
-       AFB_SESSION_LOA_1 = 64,  /* value for LOA of 1 */
-       AFB_SESSION_LOA_2 = 128, /* value for LOA of 2 */
-       AFB_SESSION_LOA_3 = 192, /* value for LOA of 3 */
-       AFB_SESSION_LOA_4 = 256, /* value for LOA of 4 */
-
-       AFB_SESSION_LOA_LE_0 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_0, /* check LOA <= 0 */
-       AFB_SESSION_LOA_LE_1 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_1, /* check LOA <= 1 */
-       AFB_SESSION_LOA_LE_2 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_2, /* check LOA <= 2 */
-       AFB_SESSION_LOA_LE_3 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_3, /* check LOA <= 3 */
-
-       AFB_SESSION_LOA_GE_0 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_0, /* check LOA >= 0 */
-       AFB_SESSION_LOA_GE_1 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_1, /* check LOA >= 1 */
-       AFB_SESSION_LOA_GE_2 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_2, /* check LOA >= 2 */
-       AFB_SESSION_LOA_GE_3 = AFB_SESSION_LOA_GE | AFB_SESSION_LOA_3, /* check LOA >= 3 */
-
-       AFB_SESSION_LOA_EQ_0 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_0, /* check LOA == 0 */
-       AFB_SESSION_LOA_EQ_1 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_1, /* check LOA == 1 */
-       AFB_SESSION_LOA_EQ_2 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_2, /* check LOA == 2 */
-       AFB_SESSION_LOA_EQ_3 = AFB_SESSION_LOA_EQ | AFB_SESSION_LOA_3  /* check LOA == 3 */
-};
-
-/*
- * Description of one verb of the API provided by the binding
- * This enumeration is valid for bindings of type 1
- */
-struct afb_verb_desc_v1
-{
-       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 */
-};
-
-/*
- * Description of the bindings of type 1
- */
-struct afb_binding_desc_v1
-{
-       const char *info;                       /* textual information about the binding */
-       const char *prefix;                     /* required prefix name for the binding */
-       const struct afb_verb_desc_v1 *verbs;   /* array of descriptions of verbs terminated by a NULL name */
-};
-
-/*
  * Description of a binding
  */
 struct afb_binding
@@ -171,28 +107,6 @@ struct afb_binding_interface
 };
 
 /*
- * Function for registering the binding
- *
- * A binding V1 MUST have a function of this name and signature.
- * This function is called during loading of the binding. It
- * receives an 'interface' that should be recorded for later access to
- * functions provided by the framework.
- *
- * This function MUST return the address of a structure that describes
- * the binding and its implemented verbs.
- *
- * In case of initialisation error, NULL must be returned.
- *
- * Be aware that the given 'interface' is not fully functionnal
- * because no provision is given to the name and description
- * of the binding. Check the function 'afbBindingV1ServiceInit'
- * defined in the file <afb/afb-service-itf.h> because when
- * the function 'afbBindingV1ServiceInit' is called, the 'interface'
- * is fully functionnal.
- */
-extern const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *interface);
-
-/*
  * Retrieves the common systemd's event loop of AFB
  * 'daemon' MUST be the daemon given in interface when activating the binding.
  */
diff --git a/include/afb/afb-req-itf.h b/include/afb/afb-req-itf.h
index 5116b133..6b6c8b70 100644
--- a/include/afb/afb-req-itf.h
+++ b/include/afb/afb-req-itf.h
@@ -25,7 +25,7 @@
 #include <stdarg.h>
 #include <stdio.h>
 
-#include <afb/afb-event-itf.h>
+#include "afb-event-itf.h"
 
 /* avoid inclusion of <json-c/json.h> */
 struct json_object;
diff --git a/include/afb/afb-service-itf-v1.h b/include/afb/afb-service-itf-v1.h
new file mode 100644
index 00000000..9319cd3b
--- /dev/null
+++ b/include/afb/afb-service-itf-v1.h
@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2016, 2017 "IoT.bzh"
+ * Author: José Bollo <jose.bollo@iot.bzh>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+struct json_object;
+struct afb_service;
+
+/*
+ * When a binding have an exported implementation of the
+ * function 'afbBindingV1ServiceInit', defined below,
+ * the framework calls it for initialising the service after
+ * registration of all bindings.
+ *
+ * The object 'service' should be recorded. It has functions that
+ * allows the binding to call features with its own personality.
+ *
+ * The function should return 0 in case of success or, else, should return
+ * a negative value.
+ */
+extern int afbBindingV1ServiceInit(struct afb_service service);
+
+/*
+ * When a binding have an implementation of the function 'afbBindingV1ServiceEvent',
+ * defined below, the framework calls that function for any broadcasted event or for
+ * events that the service subscribed to in its name.
+ *
+ * It receive the 'event' name and its related data in 'object' (be aware that 'object'
+ * might be NULL).
+ */
+extern void afbBindingV1ServiceEvent(const char *event, struct json_object *object);
+
+
diff --git a/include/afb/afb-service-itf.h b/include/afb/afb-service-itf.h
index 7b5d8f23..321fa5ac 100644
--- a/include/afb/afb-service-itf.h
+++ b/include/afb/afb-service-itf.h
@@ -30,7 +30,8 @@ struct afb_service_itf
 {
 	/* CAUTION: respect the order, add at the end */
 
-	void (*call)(void *closure, const char *api, const char *verb, struct json_object *args, void (*callback)(void*, int, struct json_object*), void *callback_closure);
+	void (*call)(void *closure, const char *api, const char *verb, struct json_object *args,
+	             void (*callback)(void*, int, struct json_object*), void *callback_closure);
 };
 
 /*
@@ -42,44 +43,35 @@ struct afb_service
 	void *closure;
 };
 
-/*
- * When a binding have an exported implementation of the
- * function 'afbBindingV1ServiceInit', defined below,
- * the framework calls it for initialising the service after
- * registration of all bindings.
- *
- * The object 'service' should be recorded. It has functions that
- * allows the binding to call features with its own personality.
- *
- * The function should return 0 in case of success or, else, should return
- * a negative value.
- */
-extern int afbBindingV1ServiceInit(struct afb_service service);
-
-/*
- * When a binding have an implementation of the function 'afbBindingV1ServiceEvent',
- * defined below, the framework calls that function for any broadcasted event or for
- * events that the service subscribed to in its name.
- *
- * It receive the 'event' name and its related data in 'object' (be aware that 'object'
- * might be NULL).
- */
-extern void afbBindingV1ServiceEvent(const char *event, struct json_object *object);
+#include "afb-service-itf-v1.h"
 
-/*
+/**
  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
  *
- * The 'callcack' receives 3 arguments:
+ * The 'callback' receives 3 arguments:
  *  1. 'closure' the user defined closure pointer 'callback_closure',
  *  2. 'iserror' a boolean status being true (not null) when an error occured,
  *  2. 'result' the resulting data as a JSON object.
  *
- * See also 'afb_req_subcall'
+ * @param service  The service as received during initialisation
+ * @param api      The api name of the method to call
+ * @param verb     The verb name of the method to call
+ * @param args     The arguments to pass to the method
+ * @param callback The to call on completion
+ * @param callback_closure The closure to pass to the callback
+ *
+ * @returns 0 in case of success or -1 in case of error.
  *
- * Returns 0in case of success or -1 in case of error.
+ * @see also 'afb_req_subcall'
  */
-static inline void afb_service_call(struct afb_service service, const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, int iserror, struct json_object *result), void *callback_closure)
+static inline void afb_service_call(
+	struct afb_service service,
+	const char *api,
+	const char *verb,
+	struct json_object *args,
+	void (*callback)(void*closure, int iserror, struct json_object *result),
+	void *callback_closure)
 {
 	service.itf->call(service.closure, api, verb, args, callback, callback_closure);
 }