docs/afb-migration-to-binding-v3.md

   1 Migration to binding V3
   2 =======================
   3
   4 The ***binding*** interface evolved from version 1 to version 2
   5 for the following reasons:
   6
   7 - integration of the security requirements within the bindings
   8 - simplification of the API (after developer feedbacks)
   9 - removal of obscure features, cleanup
  10
  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 ...
  13
  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.
  16
  17 So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
  18
  19 This guide covers the migration of bindings from version 2 to version 3.
  20
  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](afb-migration-v1-to-v2.md).
  24
  25
  26 Differences between version 2 and version 3
  27 -------------------------------------------
  28
  29 ### in v3 all is api
  30
  31 The version 3 introduce 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.
  33
  34 The concept of API is intended to allow the definition of multiple APIs
  35 by a same "binding" (a dynamically loaded library).
  36
  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.
  39
  40 To be compatible with version 2, the bindings v3 still have a default hidden
  41 context: the default API named **afbBindingV3root**.
  42
  43 To summarize, the functions of class **daemon** and **service** use the default
  44 hidden API.
  45
  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**.
  49
  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**,
  53 **AFB_API_DEBUG**.
  54
  55 Example of 2 equivalent writes:
  56
  57 ```C
  58         AFB_NOTICE("send stress event");
  59         afb_daemon_broadcast_event(stressed_event, NULL);
  60 ```
  61
  62 or
  63
  64 ```C
  65         AFB_API_NOTICE(afbBindingV3root, "send stress event");
  66         afb_api_broadcast_event(afbBindingV3root, stressed_event, NULL);
  67 ```
  68
  69 ### the reply mechanism predates success and fail
  70
  71 ### subcall has more power
  72
  73 Task list for the migration
  74 ---------------------------
  75
  76 This task list is:
  77
  78 1. Use the automatic migration procedure described below
  79 2. Adapt the init and preinit functions
  80 3. Consider to change to use the new reply
  81 4. Consider to change to use the new (sub)call
  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 down using **curl** and applied using **sed**
  90 as below.
  91
  92 ```bash
  93 BASE=https://git.automotivelinux.org/src/app-framework-binder/tree
  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 This automatic action does most of the boring job nut not all the job.
 100 The remaining of this guide explains the missing part.
 101
 102 Adapt the init and preinit functions
 103 ------------------------------------
 104
 105 Consider to change to use the new reply
 106 ---------------------------------------
 107
 108 Consider to change to use the new (sub)call
 109 -------------------------------------------
 110