From 525e9eaa644ca92fad23adfbb7c3119ae8b57a30 Mon Sep 17 00:00:00 2001
From: José Bollo <jose.bollo@iot.bzh>
Date: Tue, 19 Jun 2018 20:16:28 +0200
Subject: Improve documentation of api v3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The documentation is improved to reflect the new version.

Tune the options

Change-Id: I894c3db3bc0c10e89db66a9a51a9ad049bb8c0c4
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
---
 docs/reference-v3/func-service.md | 59 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/reference-v3/func-service.md

(limited to 'docs/reference-v3/func-service.md')

diff --git a/docs/reference-v3/func-service.md b/docs/reference-v3/func-service.md
new file mode 100644
index 00000000..b18c486c
--- /dev/null
+++ b/docs/reference-v3/func-service.md
@@ -0,0 +1,59 @@
+Functions of class afb_service
+==============================
+
+All the functions of the class **afb_daemon** use the default api.
+This are internally aliased to the corresponding legacy function of
+class **afb_api**.
+
+```C
+/**
+ * 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 '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.
+ *
+ * @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
+ *
+ * @see also 'afb_req_subcall'
+ */
+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);
+
+/**
+ * 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_req_subcall'
+ */
+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
-- 
cgit 1.2.3-korg