Provide functions afb_service_call[_sync]_legacy

These functions was missing and the documentation
was erronous. This fixes that issue by providing
the missing functions and updating the documentation.

Bug-AGL: SPEC-1669

Change-Id: I543b0fbe29370be6f35f15ca3bfa48fef9ab4055
Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>

5 files changed, 144 insertions, 24 deletions

diff --git a/docs/afb-migration-to-binding-v3.md b/docs/afb-migration-to-binding-v3.md
index f7e09fd9..29ea1790 100644
--- a/docs/afb-migration-to-binding-v3.md
+++ b/docs/afb-migration-to-binding-v3.md
@@ -180,6 +180,16 @@ of the context and event subscriptions. The new design allows you to specify:
 See [calls](reference-v3/func-api/#calls-and-job-functions) and
 [subcalls](reference-v3/func-req/#subcall-functions).
 
+The table below list the changes to apply:
+
+| Name in Version 2      | New name of Version 3
+|:----------------------:|:----------------------------------------------------:
+| afb_req_subcall        | afb_req_subcall_legacy
+| afb_req_subcall_sync   | afb_req_subcall_sync_legacy
+| afb_service_call       | afb_service_call_legacy
+| afb_service_call_sync  | afb_service_call_sync_legacy
+| afb_req_subcall_req    | afb_req_subcall_req (same but obsolete)
+
 
 Consider use of event handlers
 ------------------------------
diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md
index ef3816d0..aa28932a 100644
--- a/docs/reference-v3/func-api.md
+++ b/docs/reference-v3/func-api.md
@@ -279,7 +279,7 @@ struct json_object *afb_api_settings(
 
 ```C
 /**
- * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
@@ -323,7 +323,7 @@ void afb_api_call(
 
 ```C
 /**
- * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
  * 'result' will receive the response.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
@@ -880,8 +880,10 @@ of work.
 /**
  * @deprecated try to use @ref afb_api_call instead
  *
- *  * 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'.
+ * Calls the 'verb' of the 'apiname' 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'.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
  * Thus, in the case where 'args' should remain available after
@@ -924,7 +926,8 @@ void afb_api_call_legacy(
 /**
  * @deprecated try to use @ref afb_api_call_sync instead
  *
- * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
+ * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
+ * in the name of the binding.
  * 'result' will receive the response.
  *
  * For convenience, the function calls 'json_object_put' for 'args'.
diff --git a/docs/reference-v3/func-service.md b/docs/reference-v3/func-service.md
index 2faa7bcd..b82f9c95 100644
--- a/docs/reference-v3/func-service.md
+++ b/docs/reference-v3/func-service.md
@@ -2,11 +2,15 @@ Functions of class **afb_service**
 ==============================
 
 All the functions of the class **afb_daemon** use the default api.
-These are internally aliased to the corresponding legacy function of
-class **afb_api**.
+
+All these function are deprecated, try to use functions of class **afb_api** instead.
+
+## afb_service_call
 
 ```C
 /**
+ * @deprecated try to use @ref afb_api_call instead
+ *
  * 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'.
  *
@@ -14,27 +18,43 @@ class **afb_api**.
  * Thus, in the case where 'args' should remain available after
  * the function returns, the function 'json_object_get' shall be used.
  *
- * The 'callback' receives 3 arguments:
- *  1. 'closure' the user defined closure pointer 'callback_closure',
- *  2. 'status' a status being 0 on success or negative when an error occured,
- *  2. 'result' the resulting data as a JSON object.
+ * The 'callback' receives 5 arguments:
+ *  1. 'closure' the user defined closure pointer 'closure',
+ *  2. 'object'  a JSON object returned (can be NULL)
+ *  3. 'error'   a string not NULL in case of error but NULL on success
+ *  4. 'info'    a string handling some info (can be NULL)
+ *  5. 'api'     the api
  *
  * @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
+ * @param closure  The closure to pass to the callback
  *
- * @see also 'afb_req_subcall'
+ *
+ * @see afb_req_subcall
+ * @see afb_req_subcall_sync
+ * @see afb_api_call_sync
  */
 void afb_service_call(
-	const char *api,
-	const char *verb,
-	struct json_object *args,
-	void (*callback)(void*closure, int status, struct json_object *result),
-	void *callback_closure);
+			const char *api,
+			const char *verb,
+			struct json_object *args,
+			void (*callback)(
+					void *closure,
+					struct json_object *object,
+					const char *error,
+					const char * info,
+					afb_api_t api),
+			void *closure);
+```
 
+## afb_service_call_sync
+
+```C
 /**
+ * @deprecated try to use @ref afb_api_call_sync instead
+ *
  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
  * 'result' will receive the response.
  *
@@ -45,15 +65,98 @@ void afb_service_call(
  * @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 object   Where to store the returned object - should call json_object_put on it - can be NULL
+ * @param error    Where to store the copied returned error - should call free on it - can be NULL
+ * @param info     Where to store the copied returned info - should call free on it - can be NULL
+ *
+ * @returns 0 in case of success or a negative value in case of error.
+ *
+ * @see afb_req_subcall
+ * @see afb_req_subcall_sync
+ * @see afb_api_call
+ */
+int afb_service_call_sync(
+			const char *api,
+			const char *verb,
+			struct json_object *args,
+			struct json_object **object,
+			char **error,
+			char **info);
+```
+
+## afb_service_call_legacy
+
+```C
+/**
+ * @deprecated try to use @ref afb_api_call instead
+ *
+ * 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'.
+ *
+ * For convenience, the function calls 'json_object_put' for 'args'.
+ * Thus, in the case where 'args' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ *
+ * The 'callback' receives 3 arguments:
+ *  1. 'closure' the user defined closure pointer 'closure',
+ *  2. 'status' a status being 0 on success or negative when an error occurred,
+ *  2. 'result' the resulting data as a JSON object.
+ *
+ * @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 closure  The closure to pass to the callback
+ *
+ * @see also 'afb_api_call'
+ * @see also 'afb_api_call_sync'
+ * @see also 'afb_api_call_sync_legacy'
+ * @see also 'afb_req_subcall'
+ * @see also 'afb_req_subcall_sync'
+ */
+void afb_service_call_legacy(
+			const char *api,
+			const char *verb,
+			struct json_object *args,
+			void (*callback)(
+					void *closure,
+					int status,
+					struct json_object *result,
+					afb_api_t api),
+			void *closure);
+```
+
+## afb_service_call_sync_legacy
+
+```C
+/**
+ * @deprecated try to use @ref afb_api_call_sync instead
+ *
+ * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the
+ * name of the binding. 'result' will receive the response.
+ *
+ * For convenience, the function calls 'json_object_put' for 'args'.
+ * Thus, in the case where 'args' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ *
+ * @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 result   Where to store the result - should call json_object_put on it -
  *
  * @returns 0 in case of success or a negative value in case of error.
  *
+ * @see also 'afb_api_call'
+ * @see also 'afb_api_call_sync'
+ * @see also 'afb_api_call_legacy'
  * @see also 'afb_req_subcall'
+ * @see also 'afb_req_subcall_sync'
  */
-int afb_service_call_sync(
-	const char *api,
-	const char *verb,
-	struct json_object *args,
-	struct json_object **result);
-```
\ No newline at end of file
+int afb_service_call_sync_legacy(
+			const char *api,
+			const char *verb,
+			struct json_object *args,
+			struct json_object **result);
+```
diff --git a/include/afb/afb-binding-predefs.h b/include/afb/afb-binding-predefs.h
index 56ac504b..47907a4a 100644
--- a/include/afb/afb-binding-predefs.h
+++ b/include/afb/afb-binding-predefs.h
@@ -370,6 +370,8 @@
 
 # define afb_service_call		afb_service_call_v3
 # define afb_service_call_sync		afb_service_call_sync_v3
+# define afb_service_call_legacy	afb_service_call_legacy_v3
+# define afb_service_call_sync_legacy	afb_service_call_sync_legacy_v3
 
 # define AFB_ERROR			AFB_ERROR_V3
 # define AFB_WARNING			AFB_WARNING_V3
diff --git a/include/afb/afb-binding-v3.h b/include/afb/afb-binding-v3.h
index 9df2eb99..84af4861 100644
--- a/include/afb/afb-binding-v3.h
+++ b/include/afb/afb-binding-v3.h
@@ -259,4 +259,6 @@ extern const struct afb_binding_v3 afbBindingV3;
 
 #define afb_service_call_v3(...)		afb_api_call(afbBindingV3root,__VA_ARGS__)
 #define afb_service_call_sync_v3(...)		afb_api_call_sync(afbBindingV3root,__VA_ARGS__)
+#define afb_service_call_legacy_v3(...)		afb_api_call_legacy(afbBindingV3root,__VA_ARGS__)
+#define afb_service_call_sync_legacy_v3(...)	afb_api_call_sync_legacy(afbBindingV3root,__VA_ARGS__)