Improve documentation of api v3

[src/app-framework-binder.git] / docs / afb-migration-to-binding-v3.md

diff --git a/docs/afb-migration-to-binding-v3.md b/docs/afb-migration-to-binding-v3.md
index 8f1e678..4cfb3a7 100644 (file)
--- a/docs/afb-migration-to-binding-v3.md
+++ b/docs/afb-migration-to-binding-v3.md
@@ -20,7 +20,7 @@ This guide covers the migration of bindings from version 2 to version 3.
 
 The migration from version 1 is not treated here because bindings version 1
 are very old and probably does not exist anymore. If needed you can refer
 
 The migration from version 1 is not treated here because bindings version 1
 are very old and probably does not exist anymore. If needed you can refer

-to the old [guide to migrate bindings from v1 to v2](afb-migration-v1-to-v2.md).
+to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.md).

 
 
 Differences between version 2 and version 3
 
 
 Differences between version 2 and version 3


@@ -28,7 +28,7 @@ Differences between version 2 and version 3
 
 ### in v3 all is api
 
 
 ### in v3 all is api
 

-The version 3 introduce the concept of "API" that gather what was called before
+The version 3 introduces the concept of "API" that gather what was called before

 the daemon and the service. This is the new concept that predates the 2 others.
 
 The concept of API is intended to allow the definition of multiple APIs
 the daemon and the service. This is the new concept that predates the 2 others.
 
 The concept of API is intended to allow the definition of multiple APIs


@@ -37,7 +37,7 @@ by a same "binding" (a dynamically loaded library).
 Because there is potentially several "API", the functions that were without
 context in bindings version 2 need now to tell what API is consumer.
 
 Because there is potentially several "API", the functions that were without
 context in bindings version 2 need now to tell what API is consumer.
 

-To be compatible with version 2, the bindings v3 still have a default hidden
+To be compatible with version 2, bindings v3 still have a default hidden

 context: the default API named **afbBindingV3root**.
 
 To summarize, the functions of class **daemon** and **service** use the default
 context: the default API named **afbBindingV3root**.
 
 To summarize, the functions of class **daemon** and **service** use the default


@@ -76,9 +76,10 @@ Task list for the migration
 This task list is:
 
 1. Use the automatic migration procedure described below
 This task list is:
 
 1. Use the automatic migration procedure described below

-2. Adapt the init and preinit functions
-3. Consider to change to use the new reply
-4. Consider to change to use the new (sub)call
+2. Adapt the functions **preinit**, **init** and **onevent**
+3. Consider use of the new reply
+4. Consider use of the new (sub)call
+5. Consider use of event handlers

 
 The remaining chapters explain these task with more details.
 
 
 The remaining chapters explain these task with more details.
 


@@ -86,7 +87,7 @@ Automatic migration!
 --------------------
 
 A tiny **sed** script is intended to perform a first pass on the code that
 --------------------
 
 A tiny **sed** script is intended to perform a first pass on the code that

-you want to upgrade. It can be down using **curl** and applied using **sed**
+you want to upgrade. It can be done using **curl** and applied using **sed**

 as below.
 
 ```bash
 as below.
 
 ```bash


@@ -96,15 +97,90 @@ curl -o $SED $BASE/docs/$SED
 sed -i -f $SED file1 file2 file3...
 ```
 
 sed -i -f $SED file1 file2 file3...
 ```
 

-This automatic action does most of the boring job nut not all the job.
+This automatic action does most of the boring job but not all the job.

 The remaining of this guide explains the missing part.
 
 The remaining of this guide explains the missing part.
 

-Adapt the init and preinit functions
-------------------------------------
+Adapt the functions preinit, init and onevent
+----------------------------------------------

 
 

-Consider to change to use the new reply
----------------------------------------
+The signature of the functions **preinit**, **init** and **onevent** changed
+to include the target api.

 
 

-Consider to change to use the new (sub)call
--------------------------------------------
+The functions of the v2:
+
+```C
+int (*preinit)();
+int (*init)();
+void (*onevent)(const char *event, struct json_object *object);
+```
+
+Gain a new first argument of type **afb_api_t** as below:
+
+```C
+int (*preinit)(afb_api_t api);
+int (*init)(afb_api_t api);
+void (*onevent)(afb_api_t api, const char *event, struct json_object *object);
+```
+
+For the migration, it is enough to just add the new argument without
+using it.
+
+Consider use of the new reply
+-----------------------------
+
+The v3 allows error reply with JSON object. To achieve it, an unified
+reply function's family is introduced:
+
+```C
+void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info);
+void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args);
+void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...);
+```
+
+The functions **success** and **fail** are still supported.
+These functions are now implemented as the following macros:
+
+
+```C
+#define afb_req_success(r,o,i)         afb_req_reply(r,o,NULL,i)
+#define afb_req_success_f(r,o,...)     afb_req_reply_f(r,o,NULL,__VA_ARGS__)
+#define afb_req_success_v(r,o,f,v)     afb_req_reply_v(r,o,NULL,f,v)
+#define afb_req_fail(r,e,i)            afb_req_reply(r,NULL,e,i)
+#define afb_req_fail_f(r,e,...)                afb_req_reply_f(r,NULL,e,__VA_ARGS__)
+#define afb_req_fail_v(r,e,f,v)                afb_req_reply_v(r,NULL,e,f,v)
+```
+
+This is a decision of the developer to switch to the new family
+**afb_req_reply** or to keep the good old functions **afb_req_fail**
+adn **afb_req_success**.
+
+Consider use of the new (sub)call
+---------------------------------
+
+The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**,
+**afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned
+to better fit the new reply behaviour. In most case the developer will benefit
+of the new behavior that directly gives result and error without enforcing
+to parse the JSON object result.
+
+The subcall functions are also fully redesigned to allow precise handling
+of the context and event subscriptions. The new design allows you to specify:
+
+ - whether the subcall is made in the session of the caller or in the session
+   of the service
+ - whether the credentials to use are those of the caller or those of the
+   service
+ - whether the caller or the service or both or none will receive the
+   eventually events during the subcall.
+
+See [calls](reference-v3/func-api/#calls-and-job-functions) and
+[subcalls](reference-v3/func-req/#subcall-functions).
+
+
+Consider use of event handlers
+------------------------------
+
+Binding V3 brings new ways of handling event in services. You can register
+functions that will handle specific events and that accept closure arguments.

 
 

+See [**afb_api_event_handler_add** and **afb_api_event_handler_del**](reference-v3/func-api/#event-functions)