From 9eb125dae5663f521464d35292c646d9e76d2076 Mon Sep 17 00:00:00 2001
From: jobol <jobol@nonadev.net>
Date: Wed, 25 May 2016 16:55:17 +0200
Subject: [PATCH] more doc

Signed-off-by: jobol <jobol@nonadev.net>
---
 doc/writing-afb-plugins.md | 107 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 96 insertions(+), 11 deletions(-)

diff --git a/doc/writing-afb-plugins.md b/doc/writing-afb-plugins.md
index f0e3a376..ba2e676a 100644
--- a/doc/writing-afb-plugins.md
+++ b/doc/writing-afb-plugins.md
@@ -1,7 +1,7 @@
 HOWTO WRITE a PLUGIN for AFB-DAEMON
 ===================================
     version: 1
-    Date:    24 mai 2016
+    Date:    25 May 2016
     Author:  José Bollo
 
 TABLE-OF-CONTENT-HERE
@@ -295,7 +295,20 @@ Here is its listing:
 	}
 
 This examples show many aspects of writing a synchronous
-verb implementation.
+verb implementation. Let summarize it:
+
+1. The function **board_of_req** retrieves the context stored
+for the plugin: the board.
+
+2. The macro **INFO** sends a message of kind *INFO*
+to the logging system. The global variable named **afbitf**
+used represents the interface to afb-daemon.
+
+3. The function **describe** creates a json_object representing
+the board.
+
+4. The function **afb_req_success** sends the reply, attaching to
+it the object *description*.
 
 ### The incoming request
 
@@ -358,10 +371,10 @@ its context: the board. This function is *board_of_req*:
 		return afb_req_context(req, (void*)get_new_board, (void*)release_board);
 	}
 
-This function is very simple because it merely wraps
-a call to the function **afb_req_context**, providing
-all needed arguments.
-The casts are required to avoid a warning when compiling.
+The function **afb_req_context** ensure an existing context
+for the session of the request.
+Its two last arguments are functions. Here, the casts are required
+to avoid a warning when compiling.
 
 Here is the definition of the function **afb_req_context**
 
@@ -382,23 +395,95 @@ Here is the definition of the function **afb_req_context**
 		return result;
 	}
 
-This powerful function ensures that the context exists and is
-stored for the session.
-
+The second argument if the function that creates the context.
+For the plugin *tic-tac-toe* it is the function **get_new_board**.
 The function **get_new_board** creates a new board and set its
 count of use to 1. The boards are counting their count of use
 to free there ressources when no more used.
 
-The function **release_board** 
+The third argument if the function that frees the context.
+For the plugin *tic-tac-toe* it is the function **release_board**.
+The function **release_board** decrease the the count of use of
+the board given as argument. If the use count decrease to zero,
+the board data are freed.
 
 ### Sending the reply to a request
 
+Sending a reply to a request must be done at most one time.
+
+Two kinds of replies can be made: successful replies and
+failure replies.
+
+The functions to send replies are defined as below:
+
+	/*
+	 * Sends a reply of kind success to the request 'req'.
+	 * The status of the reply is automatically set to "success".
+	 * Its send the object 'obj' (can be NULL) with an
+	 * informationnal comment 'info (can also be NULL).
+	 */
+	static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info)
+	{
+		req.itf->success(req.closure, obj, info);
+	}
+
+	/*
+	 * Same as 'afb_req_success' but the 'info' is a formatting
+	 * string followed by arguments.
+	 */
+	static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...)
+	{
+		char *message;
+		va_list args;
+		va_start(args, info);
+		if (info == NULL || vasprintf(&message, info, args) < 0)
+			message = NULL;
+		va_end(args);
+		afb_req_success(req, obj, message);
+		free(message);
+	}
+
+	/*
+	 * Sends a reply of kind failure to the request 'req'.
+	 * The status of the reply is set to 'status' and an
+	 * informationnal comment 'info' (can also be NULL) can be added.
+	 *
+	 * Note that calling afb_req_fail("success", info) is equivalent
+	 * to call afb_req_success(NULL, info). Thus even if possible it
+	 * is strongly recommanded to NEVER use "success" for status.
+	 */
+	static inline void afb_req_fail(struct afb_req req, const char *status, const char *info)
+	{
+		req.itf->fail(req.closure, status, info);
+	}
+
+	/*
+	 * Same as 'afb_req_fail' but the 'info' is a formatting
+	 * string followed by arguments.
+	 */
+	static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...)
+	{
+		char *message;
+		va_list args;
+		va_start(args, info);
+		if (info == NULL || vasprintf(&message, info, args) < 0)
+			message = NULL;
+		va_end(args);
+		afb_req_fail(req, status, message);
+		free(message);
+	}
+
+
+
 Getting argument of invocation
 ------------------------------
 
+Sending messages to the log system
+----------------------------------
+
 How to build a plugin
 ---------------------
 
-Afb-daemon provides a The packaging of afb-daemon
+Afb-daemon provides a *pkg-config* configuration file.
 
 
-- 
2.16.6