docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/1_Migration_to_bindings_v3.md

   1 ---
   2 edit_link: ''
   3 title: Migration to bindings v3
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-migration-to-binding-v3.md?h=master
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/app-framework-binder-developer-guides-api-services-book.yml -->
   9
  10 Migration to binding V3
  11 =======================
  12
  13 The ***binding*** interface evolved from version 1 to version 2
  14 for the following reasons:
  15
  16 - integration of the security requirements within the bindings
  17 - simplification of the API (after developer feedbacks)
  18 - removal of obscure features and cleanup
  19
  20 The ***binder*** can run ***bindings*** v1, v2 and/or v3 in any combination.
  21 Thus moving from v1 or v2 to v3 is not enforced at this time. But ...
  22
  23 In the face to face meeting in Karlsruhe it was decided to remove support
  24 of bindings v1 and to deprecate the use of bindings v2.
  25
  26 So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
  27
  28 This guide covers the migration of bindings from version 2 to version 3.
  29
  30 The migration from version 1 is not treated here because bindings version 1
  31 are very old and probably do not exist anymore. If needed you can refer
  32 to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.html).
  33
  34
  35 Differences between version 2 and version 3
  36 -------------------------------------------
  37
  38 ### in v3 all is api
  39
  40 The version 3 introduces the concept of "API" that gather what was called before
  41 the daemon and the service. This is the new concept that predates the 2 others.
  42
  43 The concept of API is intended to allow the definition of multiple APIs
  44 by a same "binding" (a dynamically loaded library).
  45
  46 Because there is potentially several "API", the functions that were without
  47 context in bindings version 2 need now to tell what API is consumer.
  48
  49 To be compatible with version 2, bindings v3 still have a default hidden
  50 context: the default API named **afbBindingV3root**.
  51
  52 To summarize, the functions of class **daemon** and **service** use the default
  53 hidden API.
  54
  55 It is encouraged to avoid use of functions of class **daemon** and **service**.
  56 You should replace these implicit calls to explicit **api** calls that
  57 reference **afbBindingV3root**.
  58
  59 Same thing for the logging macros: **AFB_ERROR**, **AFB_WARNING**,
  60 **AFB_NOTICE**, **AFB_INFO**, **AFB_DEBUG** that becomes respectively
  61 **AFB_API_ERROR**, **AFB_API_WARNING**, **AFB_API_NOTICE**, **AFB_API_INFO**,
  62 **AFB_API_DEBUG**.
  63
  64 Example of 2 equivalent writes:
  65
  66 ```C
  67         AFB_NOTICE("send stress event");
  68         afb_daemon_broadcast_event(stressed_event, NULL);
  69 ```
  70
  71 or
  72
  73 ```C
  74         AFB_API_NOTICE(afbBindingV3root, "send stress event");
  75         afb_api_broadcast_event(afbBindingV3root, stressed_event, NULL);
  76 ```
  77
  78 ### the reply mechanism predates success and fail
  79
  80 ### subcall has more power
  81
  82 Task list for the migration
  83 ---------------------------
  84
  85 This task list is:
  86
  87 1. Use the automatic migration procedure described below
  88 2. Adapt the functions **preinit**, **init** and **onevent**
  89 3. Consider use of the new reply
  90 4. Consider use of the new (sub)call
  91 5. Consider use of event handlers
  92
  93 The remaining chapters explain these task with more details.
  94
  95 Automatic migration!
  96 --------------------
  97
  98 A tiny **sed** script is intended to perform a first pass on the code that
  99 you want to upgrade. It can be done using **curl** and applied using **sed**
 100 as below.
 101
 102 ```bash
 103 BASE=https://git.automotivelinux.org/src/app-framework-binder/plain
 104 SED=migration-to-binding-v3.sed
 105 curl -o $SED $BASE/docs/$SED
 106 sed -i -f $SED file1 file2 file3...
 107 ```
 108
 109 You can also follow
 110 [this link](https://git.automotivelinux.org/src/app-framework-binder/plain/docs/migration-to-binding-v3.sed)
 111 and save the file.
 112
 113 This automatic action does most of the boring job but not all the job.
 114 The remaining of this guide explains the missing part.
 115
 116 Adapt the functions preinit, init and onevent
 117 ----------------------------------------------
 118
 119 The signature of the functions **preinit**, **init** and **onevent** changed
 120 to include the target api.
 121
 122 The functions of the v2:
 123
 124 ```C
 125 int (*preinit)();
 126 int (*init)();
 127 void (*onevent)(const char *event, struct json_object *object);
 128 ```
 129
 130 Gain a new first argument of type **afb_api_t** as below:
 131
 132 ```C
 133 int (*preinit)(afb_api_t api);
 134 int (*init)(afb_api_t api);
 135 void (*onevent)(afb_api_t api, const char *event, struct json_object *object);
 136 ```
 137
 138 For the migration, it is enough to just add the new argument without
 139 using it.
 140
 141 Consider use of the new reply
 142 -----------------------------
 143
 144 The v3 allows error reply with JSON object. To achieve it, an unified
 145 reply function's family is introduced:
 146
 147 ```C
 148 void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info);
 149 void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args);
 150 void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...);
 151 ```
 152
 153 The functions **success** and **fail** are still supported.
 154 These functions are now implemented as the following macros:
 155
 156
 157 ```C
 158 #define afb_req_success(r,o,i)          afb_req_reply(r,o,NULL,i)
 159 #define afb_req_success_f(r,o,...)      afb_req_reply_f(r,o,NULL,__VA_ARGS__)
 160 #define afb_req_success_v(r,o,f,v)      afb_req_reply_v(r,o,NULL,f,v)
 161 #define afb_req_fail(r,e,i)             afb_req_reply(r,NULL,e,i)
 162 #define afb_req_fail_f(r,e,...)         afb_req_reply_f(r,NULL,e,__VA_ARGS__)
 163 #define afb_req_fail_v(r,e,f,v)         afb_req_reply_v(r,NULL,e,f,v)
 164 ```
 165
 166 This is a decision of the developer to switch to the new family
 167 **afb_req_reply** or to keep the good old functions **afb_req_fail**
 168 adn **afb_req_success**.
 169
 170 Consider use of the new (sub)call
 171 ---------------------------------
 172
 173 The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**,
 174 **afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned
 175 to better fit the new reply behaviour. In most case the developer will benefit
 176 of the new behavior that directly gives result and error without enforcing
 177 to parse the JSON object result.
 178
 179 The subcall functions are also fully redesigned to allow precise handling
 180 of the context and event subscriptions. The new design allows you to specify:
 181
 182  - whether the subcall is made in the session of the caller or in the session
 183    of the service
 184  - whether the credentials to use are those of the caller or those of the
 185    service
 186  - whether the caller or the service or both or none will receive the
 187    eventually events during the subcall.
 188
 189 See [calls](reference-v3/func-api.html#calls-and-job-functions) and
 190 [subcalls](reference-v3/func-req.html#subcall-functions).
 191
 192 The table below list the changes to apply:
 193
 194 | Name in Version 2      | New name of Version 3
 195 |:----------------------:|:----------------------------------------------------:
 196 | afb_req_subcall        | afb_req_subcall_legacy
 197 | afb_req_subcall_sync   | afb_req_subcall_sync_legacy
 198 | afb_service_call       | afb_service_call_legacy
 199 | afb_service_call_sync  | afb_service_call_sync_legacy
 200 | afb_req_subcall_req    | afb_req_subcall_req (same but obsolete)
 201
 202
 203 Consider use of event handlers
 204 ------------------------------
 205
 206 Binding V3 brings new ways of handling event in services. You can register
 207 functions that will handle specific events and that accept closure arguments.
 208
 209 See [**afb_api_event_handler_add** and **afb_api_event_handler_del**](reference-v3/func-api.html#event-functions)