1 Migration to binding V3
2 =======================
4 The ***binding*** interface evolved from version 1 to version 2
5 for the following reasons:
7 - integration of the security requirements within the bindings
8 - simplification of the API (after developer feedbacks)
9 - removal of obscure features, cleanup
11 The ***binder*** can run ***bindings*** v1, v2 and/or v3 in any combination.
12 Thus moving from v1 or v2 to v3 is not enforced at this time. But ...
14 In the face to face meeting of Karlsruhe it was decided to remove support
15 of bindings v1 and to deprecate the use of bindings v2.
17 So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
19 This guide covers the migration of bindings from version 2 to version 3.
21 The migration from version 1 is not treated here because bindings version 1
22 are very old and probably does not exist anymore. If needed you can refer
23 to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.md).
26 Differences between version 2 and version 3
27 -------------------------------------------
31 The version 3 introduces the concept of "API" that gather what was called before
32 the daemon and the service. This is the new concept that predates the 2 others.
34 The concept of API is intended to allow the definition of multiple APIs
35 by a same "binding" (a dynamically loaded library).
37 Because there is potentially several "API", the functions that were without
38 context in bindings version 2 need now to tell what API is consumer.
40 To be compatible with version 2, bindings v3 still have a default hidden
41 context: the default API named **afbBindingV3root**.
43 To summarize, the functions of class **daemon** and **service** use the default
46 It is encouraged to avoid use of functions of class **daemon** and **service**.
47 You should replace these implicit calls to explicit **api** calls that
48 reference **afbBindingV3root**.
50 Same thing for the logging macros: **AFB_ERROR**, **AFB_WARNING**,
51 **AFB_NOTICE**, **AFB_INFO**, **AFB_DEBUG** that becomes respectively
52 **AFB_API_ERROR**, **AFB_API_WARNING**, **AFB_API_NOTICE**, **AFB_API_INFO**,
55 Example of 2 equivalent writes:
58 AFB_NOTICE("send stress event");
59 afb_daemon_broadcast_event(stressed_event, NULL);
65 AFB_API_NOTICE(afbBindingV3root, "send stress event");
66 afb_api_broadcast_event(afbBindingV3root, stressed_event, NULL);
69 ### the reply mechanism predates success and fail
71 ### subcall has more power
73 Task list for the migration
74 ---------------------------
78 1. Use the automatic migration procedure described below
79 2. Adapt the functions **preinit**, **init** and **onevent**
80 3. Consider use of the new reply
81 4. Consider use of the new (sub)call
82 5. Consider use of event handlers
84 The remaining chapters explain these task with more details.
89 A tiny **sed** script is intended to perform a first pass on the code that
90 you want to upgrade. It can be done using **curl** and applied using **sed**
94 BASE=https://git.automotivelinux.org/src/app-framework-binder/tree
95 SED=migration-to-binding-v3.sed
96 curl -o $SED $BASE/docs/$SED
97 sed -i -f $SED file1 file2 file3...
100 This automatic action does most of the boring job but not all the job.
101 The remaining of this guide explains the missing part.
103 Adapt the functions preinit, init and onevent
104 ----------------------------------------------
106 The signature of the functions **preinit**, **init** and **onevent** changed
107 to include the target api.
109 The functions of the v2:
114 void (*onevent)(const char *event, struct json_object *object);
117 Gain a new first argument of type **afb_api_t** as below:
120 int (*preinit)(afb_api_t api);
121 int (*init)(afb_api_t api);
122 void (*onevent)(afb_api_t api, const char *event, struct json_object *object);
125 For the migration, it is enough to just add the new argument without
128 Consider use of the new reply
129 -----------------------------
131 The v3 allows error reply with JSON object. To achieve it, an unified
132 reply function's family is introduced:
135 void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info);
136 void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args);
137 void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...);
140 The functions **success** and **fail** are still supported.
141 These functions are now implemented as the following macros:
145 #define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i)
146 #define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__)
147 #define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v)
148 #define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i)
149 #define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__)
150 #define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v)
153 This is a decision of the developer to switch to the new family
154 **afb_req_reply** or to keep the good old functions **afb_req_fail**
155 adn **afb_req_success**.
157 Consider use of the new (sub)call
158 ---------------------------------
160 The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**,
161 **afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned
162 to better fit the new reply behaviour. In most case the developer will benefit
163 of the new behavior that directly gives result and error without enforcing
164 to parse the JSON object result.
166 The subcall functions are also fully redesigned to allow precise handling
167 of the context and event subscriptions. The new design allows you to specify:
169 - whether the subcall is made in the session of the caller or in the session
171 - whether the credentials to use are those of the caller or those of the
173 - whether the caller or the service or both or none will receive the
174 eventually events during the subcall.
176 See [calls](reference-v3/func-api/#calls-and-job-functions) and
177 [subcalls](reference-v3/func-req/#subcall-functions).
180 Consider use of event handlers
181 ------------------------------
183 Binding V3 brings new ways of handling event in services. You can register
184 functions that will handle specific events and that accept closure arguments.
186 See [**afb_api_event_handler_add** and **afb_api_event_handler_del**](reference-v3/func-api/#event-functions)