2 title: LEGACY Migration from v1 to v2
5 > LEGACY!!! IT IS NOT EXPECTED THAT YOU STILL NEED THIS GUIDE.
7 > THIS GUIDE WILL BE REMOVED IN A NEAR FUTURE
10 The ***binding*** interface evolved from version 1 to version 2
11 for the following reasons:
13 - integration of the security requirements within the bindings
14 - simplification of the API (after developer feedbacks)
15 - removal of obscure features, cleanup
17 The ***binder*** can run ***bindings*** v1 and/or v2 in any combination.
18 Thus moving from v1 to v2 is not enforced, there is no real need.
20 More, it is possible to write a dual ***binding***:
22 - a ***binding*** that implements the version 1 and the version 2.
24 However, IT IS HIGHLY RECOMMENDED TO SWITCH TO ONLY VERSION 2:
26 - any new development SHOULD start using ***binding*** V2
27 - existing ***bindings*** SHOULD migrate to the version 2
29 This guide covers the migration of bindings from version 1 to version 2.
31 It also explains some of the rationale taken when migrating from version 1 to version 2.
33 In the future, if ***binding*** api evolves to fresh versions (3, 4, ...)
34 it might be necessarily to write bindings implementing more than
38 - a ***binding*** being v2 AND v3 will resolve the issue of running on older and newer version of AGL.
40 This should always be possible even if more complicated.
42 Important things to known when migrating
43 ----------------------------------------
45 One of the most important change when migrating from v1 to v2 is
46 that many functions use an hidden *common* variable.
47 This affects the functions of the following classes:
49 - functions of class **daemon**:
50 - functions starting with **afb_daemon_...**
51 - functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG**
52 - functions of class **service**:
53 - functions starting with **afb_service_...**
55 - the register function (that is removed)
56 - the service init function
57 - the onevent function
59 For these functions, the first parameter is now implicit.
62 For ***binding*** v1 you had to write:
65 afb_daemon_broadcast_event(afbitf->daemon, reason, description);
68 For ***binding*** v2, you simply write:
71 afb_daemon_broadcast_event(reason, description);
74 This simplification is possible because the header files included for the bindings
75 now provide a common variable for storing the **daemon** and **service** data.
77 As a programmer, you shouldn't care much about that hidden variable.
78 It simplifies the job, that's all and that is the reason of the change.
80 An other important difference is between the version 1 and the version 2 is
81 on how the ***binding***'s **API** is documented.
82 The version 2 emphasis the **OpenAPI v3** description of the **API**.
83 For this reason, to avoid duplication of descriptions, only one description is expected:
85 - The **OpenAPI** one.
87 Task list for the migration
88 ---------------------------
92 1. Enforce use of binding v2 by setting **AFB_BINDING_VERSION**
93 2. Rewrite the main structure and the list of exported verbs
94 3. Adapt the init and callback functions
95 4. Removes the first parameter of functions of classes **daemon** and **service**
96 5. Consider where to emit logs for requests
97 6. Take care of store/unstore changes
98 7. Consider use of synchronous (sub)call requests
99 8. Optionally, removes explicit struct
101 The remaining chapters explain these task with more details.
103 Enforce use of binding v2 by setting AFB_BINDING_VERSION
104 --------------------------------------------------------
106 By defining **AFB_BINDING_VERSION** to **2** you switch to version 2.
107 This is done as below.
110 #define AFB_BINDING_VERSION 2
111 #include <afb/afb-binding.h>
114 After that you will get many errors when compiling.
116 Rewrite the main structures and the list of exported verbs
117 ---------------------------------------------------------
119 The structures describing the ***binding** changed from version 1 to version 2.
121 The structure for describing verbs changed to include security
127 struct afb_verb_desc_v1
129 const char *name; /* name of the verb */
130 enum afb_session_flags_v1 session; /* authorization and session requirements of the verb */
131 void (*callback)(struct afb_req req); /* callback function implementing the verb */
132 const char *info; /* textual description of the verb */
136 In version 2 it becomes:
141 const char *verb; /* name of the verb */
142 void (*callback)(struct afb_req req); /* callback function implementing the verb */
143 const struct afb_auth *auth; /* required authorization */
144 uint32_t session; /* authorization and session requirements of the verb */
149 The migration of instances of that structure requires the following actions:
151 - rename field **name** to **verb**
152 - remove field **info**
153 - adapt field **session** if needed
154 - set field **auth** to NULL
159 { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" }
165 { .verb = "new", .session = AFB_SESSION_NONE, .callback = new, .auth = NULL }
168 The field **auth** can be set to a value describing the requested
171 The main describing structure also changed.
176 struct afb_binding_desc_v1
178 const char *info; /* textual information about the binding */
179 const char *prefix; /* required prefix name for the binding */
180 const struct afb_verb_desc_v1 *verbs; /* array of descriptions of verbs terminated by a NULL name */
184 In version 2 it becomes:
187 struct afb_binding_v2
189 const char *api; /* api name for the binding */
190 const char *specification; /* textual specification of the binding */
191 const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */
192 int (*preinit)(); /* callback at load of the binding */
193 int (*init)(); /* callback for starting the service */
194 void (*onevent)(const char *event, struct json_object *object); /* callback for handling events */
195 unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */
199 The migration of instances of that structure requires the following actions:
201 - declare, explore, name the structure as ```const struct afb_binding_v2 afbBindingV2```
202 - rename the field **prefix** to **api**
203 - remove the field **info**
204 - setup the fields **preinit**, **init**, **onevent** according to the next section
205 - set the field **noconcurrency** to the right value:
206 - to 1 if you want to avoid concurrent calls to verbs.
207 - to 0 if you allow concurrent calls to verbs.
212 static const struct afb_binding plugin_desc = {
213 .type = AFB_BINDING_VERSION_1,
215 .info = "Minimal Hello World Sample",
224 const struct afb_binding_v2 afbBindingV2 = {
226 .specification = NULL,
233 The **binder** now relies only on the exported names
234 to deduce the type of the binding.
235 This make the main structure more simple.
237 Adapt the init and callback functions
238 -------------------------------------
240 The ***bindings*** version 1 defined 3 exported functions:
242 - **afbBindingV1Register**
243 - **afbBindingV1ServiceInit**
244 - **afbBindingV1ServiceEvent**
246 These function should not be exported any more and there definition changed.
248 The function **afbBindingV1Register** is no more used to describe the binding.
249 When a binding has to take actions when it is loaded, it must set the field
250 **preinit** of the structure **afbBindingV2**.
251 This field, this preinit, might be used to check features at load.
252 When it returns a negative number, the ***binder*** stops before initializing any ***binding***.
254 The function **afbBindingV1ServiceInit** is replaced by the field **init**
255 of the structure **afbBindingV2**.
256 The init function should return 0 in case of success or a negative error code
258 It is called during initialization of services.
260 The function **afbBindingV1ServiceEvent**is replaced by the field **onevent**
261 of the structure **afbBindingV2**.
263 The two functions **afbBindingV1Register** and **afbBindingV1ServiceInit**,
264 were taking as parameter the ***binder*** interface and the service interface respectively.
265 These interfaces are now managed hiddenly for the **binding** by the **binder**.
266 So the variable that ***bindings*** version used to store the ***binder*** interface
267 and the service interface are no more needed and can be removed.
272 const struct afb_binding_interface *interface;
273 struct afb_service service;
275 static const struct afb_binding plugin_desc = {
276 .type = AFB_BINDING_VERSION_1,
278 .info = "Minimal Hello World Sample",
284 const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf)
287 NOTICE(interface, "binding register");
291 int afbBindingV1ServiceInit(struct afb_service svc)
294 NOTICE(interface, "binding init");
298 void afbBindingV1ServiceEvent(const char *event, struct json_object *object)
300 NOTICE(interface, "onevent %s", event);
309 AFB_NOTICE("binding preinit (was register)");
315 AFB_NOTICE("binding init");
319 static void onevent(const char *event, struct json_object *object)
321 AFB_NOTICE("onevent %s", event);
324 const struct afb_binding_v2 afbBindingV2 = {
326 .specification = NULL,
334 The two functions **afbBindingV1Register** and **afbBindingV1ServiceInit**,
335 were taking as parameter the ***binder*** interface and the service interface respectively.
336 These interfaces are now managed hiddenly for the **binding** by the **binder**.
337 So the variable that ***bindings*** version used to store the ***binder*** interface
338 and the service interface are no more needed and can be removed.
340 On the above example the following lines were removed:
343 const struct afb_binding_interface *interface;
344 struct afb_service service;
351 Removes the first parameter of functions of classes **daemon** and **service**
352 ------------------------------------------------------------------------------
354 As explained before, many functions loose there first
355 arguments, this are the functions of the following classes:
357 - functions of class **daemon**:
358 - functions starting with **afb_daemon_...**
359 - functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG**
360 - functions of class **service**:
361 - functions starting with **afb_service_...**
362 - callback functions:
363 - the register function (that is removed)
364 - the service init function
365 - the onevent function
367 For these functions, the first parameter is now implicit.
372 afb_daemon_broadcast_event(afbitf->daemon, reason, description);
378 afb_daemon_broadcast_event(reason, description);
381 Also, to avoid possible conflicts, we introduced prefixed logging functions:
390 have now a prefixed version:
398 It is now recommended to use the prefixed version.
403 NOTICE(interface, "hello plugin comes to live");
409 NOTICE("hello plugin comes to live");
415 AFB_NOTICE("hello plugin comes to live");
418 To remove definition of the un-prefixed versions of logging macros:
428 - **AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX**
430 before to include **afb/afb-binding.h**.
433 #define AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX
434 #define AFB_BINDING_VERSION 2
435 #include <afb/afb-binding.h>
438 Consider where to emit logs for requests
439 ----------------------------------------
441 The ***bindings*** v2 now allows to emit log messages associated to ***requests***.
442 This feature is valuable when debugging because it allows to return
443 side information associated to a ***request***.
445 The defined macros for logging to requests are:
448 - **AFB_REQ_WARNING**
453 We encourage the use of these new logging facilities everywhere it makes sense.
458 INFO(afbitf, "method 'new' called for boardid %d", board->id);
464 AFB_REQ_INFO(req, "method 'new' called for boardid %d", board->id);
467 Take care of store/unstore change
468 ---------------------------------
470 For efficiency, the version 2 redefined how storing/un-storing of
472 Storing request is needed for asynchronous handling of requests.
474 For ***bindings*** version, the signature of the functions were:
477 struct afb_req *afb_req_store(struct afb_req req);
478 struct afb_req afb_req_unstore(struct afb_req *req);
481 For version 2 it becomes
484 struct afb_stored_req *afb_req_store(struct afb_req req);
485 struct afb_req afb_req_unstore(struct afb_stored_req *sreq);
488 Where the structure ```struct afb_stored_req``` is opaque.
490 It should require few code change.
492 Also check the following chapter that explain that asynchronous (sub)calls
493 can be replaced by synchronous one, avoiding the need to store/unstore
496 Consider use of synchronous (sub)call requests
497 ----------------------------------------------
499 ***Bindings*** can emit requests for themselves (calls) or for
500 their clients (subcalls).
501 With ***bindings*** version 2 comes also synchronous requests for both cases.
503 So when migrating to bindings version 2, a developer can consider
504 to replace the asynchronous requests (with asynchronous call back)
507 See functions ***afb_service_call_sync*** and ***afb_req_subcall_sync***.
509 Optionally, removes explicit struct
510 -----------------------------------
512 The new definitions now includes **typedefs** for common
513 structures, as shown on below sample:
516 typedef struct afb_daemon afb_daemon;
517 typedef struct afb_event afb_event;
518 typedef struct afb_arg afb_arg;
519 typedef struct afb_req afb_req;
520 typedef struct afb_service afb_service;
523 So you can remove the keyword **struct** if it bores you.
528 static void verb(struct afb_req req)
537 static void verb(afb_req req)
546 The first ***binding*** that migrated from v1 to v2 was the sample **HelloWorld**.
547 Here is shown the differences between the version 1 and the version 2.
550 diff --git a/bindings/samples/HelloWorld.c b/bindings/samples/HelloWorld.c
551 index c6fa779..505aee3 100644
552 --- a/bindings/samples/HelloWorld.c
553 +++ b/bindings/samples/HelloWorld.c
556 #include <json-c/json.h>
558 +#define AFB_BINDING_VERSION 2
559 #include <afb/afb-binding.h>
561 -const struct afb_binding_interface *interface;
562 static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
565 @@ -79,7 +80,7 @@ static int event_add(const char *tag, const char *name)
569 - e->event = afb_daemon_make_event(interface->daemon, name);
570 + e->event = afb_daemon_make_event(name);
571 if (!e->event.closure) { free(e); return -1; }
574 @@ -140,7 +141,7 @@ static void pingBug (struct afb_req request)
575 static void pingEvent(struct afb_req request)
577 json_object *query = afb_req_json(request);
578 - afb_daemon_broadcast_event(interface->daemon, "event", json_object_get(query));
579 + afb_daemon_broadcast_event("event", json_object_get(query));
580 ping(request, json_object_get(query), "event");
583 @@ -288,38 +289,43 @@ static void exitnow (struct afb_req request)
587 +static int preinit()
589 + AFB_NOTICE("hello binding comes to live");
595 + AFB_NOTICE("hello binding starting");
599 // NOTE: this sample does not use session to keep test a basic as possible
600 // in real application most APIs should be protected with AFB_SESSION_CHECK
601 -static const struct afb_verb_desc_v1 verbs[]= {
602 - {"ping" , AFB_SESSION_NONE, pingSample , "Ping Application Framework"},
603 - {"pingfail" , AFB_SESSION_NONE, pingFail , "Fails"},
604 - {"pingnull" , AFB_SESSION_NONE, pingNull , "Return NULL"},
605 - {"pingbug" , AFB_SESSION_NONE, pingBug , "Do a Memory Violation"},
606 - {"pingJson" , AFB_SESSION_NONE, pingJson , "Return a JSON object"},
607 - {"pingevent", AFB_SESSION_NONE, pingEvent , "Send an event"},
608 - {"subcall", AFB_SESSION_NONE, subcall , "Call api/verb(args)"},
609 - {"subcallsync", AFB_SESSION_NONE, subcallsync , "Call api/verb(args)"},
610 - {"eventadd", AFB_SESSION_NONE, eventadd , "adds the event of 'name' for the 'tag'"},
611 - {"eventdel", AFB_SESSION_NONE, eventdel , "deletes the event of 'tag'"},
612 - {"eventsub", AFB_SESSION_NONE, eventsub , "subscribes to the event of 'tag'"},
613 - {"eventunsub",AFB_SESSION_NONE, eventunsub , "unsubscribes to the event of 'tag'"},
614 - {"eventpush", AFB_SESSION_NONE, eventpush , "pushs the event of 'tag' with the 'data'"},
615 - {"exit", AFB_SESSION_NONE, exitnow , "exits from afb-daemon"},
617 +static const struct afb_verb_v2 verbs[]= {
618 + { "ping" , pingSample , NULL, AFB_SESSION_NONE },
619 + { "pingfail" , pingFail , NULL, AFB_SESSION_NONE },
620 + { "pingnull" , pingNull , NULL, AFB_SESSION_NONE },
621 + { "pingbug" , pingBug , NULL, AFB_SESSION_NONE },
622 + { "pingJson" , pingJson , NULL, AFB_SESSION_NONE },
623 + { "pingevent", pingEvent , NULL, AFB_SESSION_NONE },
624 + { "subcall", subcall , NULL, AFB_SESSION_NONE },
625 + { "subcallsync", subcallsync, NULL, AFB_SESSION_NONE },
626 + { "eventadd", eventadd , NULL, AFB_SESSION_NONE },
627 + { "eventdel", eventdel , NULL, AFB_SESSION_NONE },
628 + { "eventsub", eventsub , NULL, AFB_SESSION_NONE },
629 + { "eventunsub", eventunsub , NULL, AFB_SESSION_NONE },
630 + { "eventpush", eventpush , NULL, AFB_SESSION_NONE },
631 + { "exit", exitnow , NULL, AFB_SESSION_NONE },
635 -static const struct afb_binding plugin_desc = {
636 - .type = AFB_BINDING_VERSION_1,
638 - .info = "Minimal Hello World Sample",
642 +const struct afb_binding_v2 afbBindingV2 = {
644 + .specification = NULL,
646 + .preinit = preinit,
650 -const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf)
653 - NOTICE(interface, "hello plugin comes to live");
654 - return &plugin_desc;