docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/1_Migration_to_bindings_v3.md

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