docs/3_Developer_Guides/2_Application_Framework_Binder/2_How_to_write_a_binding.md

   1 ---
   2 title: How to write a binding?
   3 ---
   4
   5 # Overview of the bindings
   6
   7 The ***binder*** serves files through HTTP protocol and offers developers the capability to offer application API methods through HTTP or
   8 WebSocket protocol.
   9
  10 The ***bindings*** are used to add **API** to ***binders***.
  11 This part describes how to write a ***binding*** for ***binder***
  12 or in other words how to add a new **API** to the system.
  13
  14 This section target developers.
  15
  16 This section shortly explain how to write a binding
  17 using the C programming language.
  18
  19 It is convenient to install the ***binder*** on the
  20 desktop used for writing the binding.
  21 It allows for easy debug and test.
  22
  23 ## Nature of a binding
  24
  25 A ***binding*** is an independent piece of software compiled as a shared
  26 library and dynamically loaded by a ***binder***.
  27 It is intended to provide one **API** (**A**pplication **P**rogramming
  28 **I**nterface).
  29
  30 The **API** is designated and accessed through its name.
  31 It contains several **verbs** that implement the ***binding***
  32 functionalities.
  33 Each of these **verbs** is a **method** that
  34 processes requests of applications and sends results.
  35
  36 The ***binding***'s methods are invoked by HTTP or websocket
  37 requests.
  38
  39 The **methods** of the ***bindings*** are noted **api/verb**
  40 where **api** is the **API** name of the binding and **verb** is
  41 the **method**'s name within the **API**.
  42 This notation comes from HTTP invocations that rely on URL path terminated
  43 with **api/verb**.
  44
  45 The name of an **API** can be made of any characters except:
  46
  47 - the control characters (\u0000 .. \u001f)
  48 - the characters of the set { ' ', '"', '#', '%', '&',
  49    '\'', '/', '?', '`', '\x7f' }
  50
  51 The names of the **verbs** can be any character.
  52
  53 The binder makes no distinctions between upper case and lower case
  54 latin letters.
  55 So **API/VERB** matches **Api/Verb** or **api/verb**.
  56
  57 ## Versions of the bindings
  58
  59 Since introduction of the binder, the way how bindings are written
  60 evolved a little. While changing, attention was made to ensure binary
  61 compatibility between the different versions.
  62
  63 Actually it exists 3 ways of writing ***bindings***.
  64 You can either write:
  65
  66 - a binding version 1 (not more supported);
  67 - a binding version 2 (not recommended);
  68 - a binding version 3 (RECOMMENDED).
  69
  70 A ***binder*** loads and runs any of these version in any combination.
  71 This document explain how to write bindings version 3.
  72
  73 ## Sample binding: tuto-1
  74
  75 This is the code of the binding **tuto-1.c**:
  76
  77 ```C
  78   1 #define AFB_BINDING_VERSION 3
  79   2 #include <afb/afb-binding.h>
  80   3
  81   4 void hello(afb_req_t req)
  82   5 {
  83   6         AFB_REQ_DEBUG(req, "hello world");
  84   7         afb_req_reply(req, NULL, NULL, "hello world");
  85   8 }
  86   9
  87  10 const afb_verb_t verbs[] = {
  88  11         { .verb="hello", .callback=hello },
  89  12         { .verb=NULL }
  90  13 };
  91  14
  92  15 const afb_binding_t afbBindingExport = {
  93  16         .api = "tuto-1",
  94  17         .verbs = verbs
  95  18 };
  96 ```
  97
  98 Compiling:
  99
 100 ```bash
 101 gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon)
 102 ```
 103
 104 > Note: the variable environment variable PKG_CONFIG_PATH might be necessary
 105 > tuned to get **pkg-config** working properly
 106
 107 Running:
 108
 109 ```bash
 110 afb-daemon --binding ./tuto-1.so --port 3333 --token ''
 111 ```
 112
 113 At this point, afb-daemon has started, it loaded the binding tuto-1.so and now
 114 listen at localhost on the port 3333.
 115
 116 Testing using **curl**:
 117
 118 ```bash
 119 $ curl http://localhost:3333/api/tuto-1/hello
 120 {"jtype":"afb-reply","request":{"status":"success","info":"hello world","uuid":"1e587b54-900b-49ab-9940-46141bc2e1d6"}}
 121 ```
 122
 123 Testing using **afb-client-demo** (with option -H for
 124 getting a human readable output):
 125
 126 ```bash
 127 $ afb-client-demo -H ws://localhost:3333/api?token=x tuto-1 hello
 128 ON-REPLY 1:tuto-1/hello: OK
 129 {
 130   "jtype":"afb-reply",
 131   "request":{
 132     "status":"success",
 133     "info":"hello world",
 134     "uuid":"03a84ad1-458a-4ace-af74-b1da917391b9"
 135   }
 136 }
 137 ```
 138
 139 This shows basic things:
 140
 141 - The include to get for creating a binding
 142 - How to declare the API offered by the binding
 143 - How to handle requests made to the binding
 144
 145 ### Getting declarations for the binding
 146
 147 The lines 1 and 2 show how to get the include file **afb-binding.h**.
 148
 149 ```C
 150   1 #define AFB_BINDING_VERSION 3
 151   2 #include <afb/afb-binding.h>
 152 ```
 153
 154 You must define the version of ***binding*** that you are using.
 155 This is done line 1 where we define that this is the version 3 (earlier
 156 versions 1 and 2 are deprecated).
 157
 158 If you don't define it, an error is reported and the compilation aborts.
 159
 160 To include **afb-binding.h** successfully, the include search path
 161 should be set correctly if needed (not needed only if installed in
 162 /usr/include/afb directory that is the default).
 163
 164 Setting the include path is easy using **pkg-config**:
 165
 166 ```bash
 167 pkg-config --cflags-only-I afb-daemon
 168 ```
 169
 170 > Note for **C++** developers:
 171 >
 172 > The ***binder*** currently expose a draft version of **C++** api.
 173 > To get it include the file <**afb/afb-binding**> (without **.h**).
 174
 175
 176 ### Declaring the API of the binding
 177
 178 Lines 10 to 18 show the declaration of the ***binding***.
 179
 180 The ***binder*** knows that this is a ***binding*** because
 181 it finds the exported symbol **afbBindingExport** that is expected to be
 182 a structure of type **afb_binding_t**.
 183
 184 ```C
 185  10 const afb_verb_t verbs[] = {
 186  11         { .verb="hello", .callback=hello },
 187  12         { .verb=NULL }
 188  13 };
 189  14
 190  15 const afb_binding_t afbBindingExport = {
 191  16         .api = "tuto-1",
 192  17         .verbs = verbs
 193  18 };
 194 ```
 195
 196 The structure **afbBindingExport** actually tells that:
 197
 198 - the exported **API** name is **tuto-1** (line 16)
 199 - the array of verbs is the above defined one
 200
 201 The exported list of verb is specified by an array of structures of
 202 type **afb_verb_t**, each describing a verb, ended with a verb NULL (line 12).
 203
 204 The only defined verb here (line 11) is named **hello** (field **.verb**)
 205 and the function that handle the related request is **hello**
 206 (field **.callback**).
 207
 208 ### Handling binder's requests
 209
 210 As shown above this is by default the common include directory where
 211 the AGL stuff is installed.
 212
 213 ```C
 214   4 void hello(afb_req_t req)
 215   5 {
 216   6         AFB_REQ_DEBUG(req, "hello world");
 217   7         afb_req_reply(req, NULL, NULL, "hello world");
 218   8 }
 219 ```
 220
 221 When the ***binder*** receives a request for the verb **hello** of
 222 of the api **tuto-1**, it invoke the callback **hello** of the **binding**
 223 with the argument **req** that handles the client request.
 224
 225 The callback has to treat synchronously or asynchronously the request and
 226 should at the end emit a reply for the request.
 227
 228 At the line 7, the callback for **tuto-1/hello** replies to the request **req**.
 229 Parameters of the reply are:
 230
 231  1. The first parameter is the replied request
 232  2. The second parameter is a json object (here NULL)
 233  3. The third parameter is the error string indication (here NULL: no error)
 234  4. The fourth parameter is an informative string (that can be NULL) that can be used to provide meta data.
 235
 236 The 3 last parameters are sent back to the client as the reply content.
 237
 238 <!-- pagebreak -->
 239
 240 ## Sample binding: tuto-2
 241
 242 The second tutorial shows many important feature that can
 243 commonly be used when writing a ***binding***:
 244
 245 - initialization, getting arguments, sending replies, pushing events.
 246
 247 This is the code of the binding **tuto-2.c**:
 248
 249 ```C
 250       1 #include <string.h>
 251       2 #include <json-c/json.h>
 252       3
 253       4 #define AFB_BINDING_VERSION 3
 254       5 #include <afb/afb-binding.h>
 255       6
 256       7 afb_event_t event_login, event_logout;
 257       8
 258       9 void login(afb_req_t req)
 259      10 {
 260      11         json_object *args, *user, *passwd;
 261      12         char *usr;
 262      13
 263      14         args = afb_req_json(req);
 264      15         if (!json_object_object_get_ex(args, "user", &user)
 265      16          || !json_object_object_get_ex(args, "password", &passwd)) {
 266      17                 AFB_REQ_ERROR(req, "login, bad request: %s", json_object_get_string(args));
 267      18                 afb_req_reply(req, NULL, "bad-request", NULL);
 268      19         } else if (afb_req_context_get(req)) {
 269      20                 AFB_REQ_ERROR(req, "login, bad state, logout first");
 270      21                 afb_req_reply(req, NULL, "bad-state", NULL);
 271      22         } else if (strcmp(json_object_get_string(passwd), "please")) {
 272      23                 AFB_REQ_ERROR(req, "login, unauthorized: %s", json_object_get_string(args));
 273      24                 afb_req_reply(req, NULL, "unauthorized", NULL);
 274      25         } else {
 275      26                 usr = strdup(json_object_get_string(user));
 276      27                 AFB_REQ_NOTICE(req, "login user: %s", usr);
 277      28                 afb_req_session_set_LOA(req, 1);
 278      29                 afb_req_context_set(req, usr, free);
 279      30                 afb_req_reply(req, NULL, NULL, NULL);
 280      31                 afb_event_push(event_login, json_object_new_string(usr));
 281      32         }
 282      33 }
 283      34
 284      35 void action(afb_req_t req)
 285      36 {
 286      37         json_object *args, *val;
 287      38         char *usr;
 288      39
 289      40         args = afb_req_json(req);
 290      41         usr = afb_req_context_get(req);
 291      42         AFB_REQ_NOTICE(req, "action for user %s: %s", usr, json_object_get_string(args));
 292      43         if (json_object_object_get_ex(args, "subscribe", &val)) {
 293      44                 if (json_object_get_boolean(val)) {
 294      45                         AFB_REQ_NOTICE(req, "user %s subscribes to events", usr);
 295      46                         afb_req_subscribe(req, event_login);
 296      47                         afb_req_subscribe(req, event_logout);
 297      48                 } else {
 298      49                         AFB_REQ_NOTICE(req, "user %s unsubscribes to events", usr);
 299      50                         afb_req_unsubscribe(req, event_login);
 300      51                         afb_req_unsubscribe(req, event_logout);
 301      52                 }
 302      53         }
 303      54         afb_req_reply(req, json_object_get(args), NULL, NULL);
 304      55 }
 305      56
 306      57 void logout(afb_req_t req)
 307      58 {
 308      59         char *usr;
 309      60
 310      61         usr = afb_req_context_get(req);
 311      62         AFB_REQ_NOTICE(req, "login user %s out", usr);
 312      63         afb_event_push(event_logout, json_object_new_string(usr));
 313      64         afb_req_session_set_LOA(req, 0);
 314      65         afb_req_context_clear(req);
 315      66         afb_req_reply(req, NULL, NULL, NULL);
 316      67 }
 317      68
 318      69 int preinit(afb_api_t api)
 319      70 {
 320      71         AFB_API_NOTICE(api, "preinit");
 321      72         return 0;
 322      73 }
 323      74
 324      75 int init(afb_api_t api)
 325      76 {
 326      77         AFB_API_NOTICE(api, "init");
 327      78         event_login = afb_api_make_event(api, "login");
 328      79         event_logout = afb_api_make_event(api, "logout");
 329      80         if (afb_event_is_valid(event_login) && afb_event_is_valid(event_logout))
 330      81                 return 0;
 331      82         AFB_API_ERROR(api, "Can't create events");
 332      83         return -1;
 333      84 }
 334      85
 335      86 const afb_verb_t verbs[] = {
 336      87         { .verb="login", .callback=login },
 337      88         { .verb="action", .callback=action, .session=AFB_SESSION_LOA_1 },
 338      89         { .verb="logout", .callback=logout, .session=AFB_SESSION_LOA_1 },
 339      90         { .verb=NULL }
 340      91 };
 341      92
 342      93 const afb_binding_t afbBindingExport = {
 343      94         .api = "tuto-2",
 344      95         .specification = NULL,
 345      96         .verbs = verbs,
 346      97         .preinit = preinit,
 347      98         .init = init,
 348      99         .noconcurrency = 0
 349     100 };
 350 ```
 351
 352 Compiling:
 353
 354 ```bash
 355 gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon)
 356 ```
 357
 358 Running:
 359
 360 ```bash
 361 afb-daemon --binding ./tuto-2.so --port 3333 --token ''
 362 ```
 363
 364 Testing:
 365
 366 ```bash
 367 $ afb-client-demo -H localhost:3333/api?token=toto
 368 tuto-2 login {"help":true}
 369 ON-REPLY 1:tuto-2/login: ERROR
 370 {
 371   "jtype":"afb-reply",
 372   "request":{
 373     "status":"bad-request",
 374     "uuid":"e2b24a13-fc43-487e-a5f4-9266dd1e60a9"
 375   }
 376 }
 377 tuto-2 login {"user":"jose","password":"please"}
 378 ON-REPLY 2:tuto-2/login: OK
 379 {
 380   "jtype":"afb-reply",
 381   "request":{
 382     "status":"success"
 383   }
 384 }
 385 tuto-2 login {"user":"jobol","password":"please"}
 386 ON-REPLY 3:tuto-2/login: ERROR
 387 {
 388   "jtype":"afb-reply",
 389   "request":{
 390     "status":"bad-state"
 391   }
 392 }
 393 tuto-2 action {"subscribe":true}
 394 ON-REPLY 4:tuto-2/action: OK
 395 {
 396   "response":{
 397     "subscribe":true
 398   },
 399   "jtype":"afb-reply",
 400   "request":{
 401     "status":"success"
 402   }
 403 }
 404 ```
 405
 406 In another terminal:
 407
 408 ```bash
 409 $ afb-client-demo -H localhost:3333/api?token=toto
 410 tuto-2 login {"user":"jobol","password":"please"}
 411 ON-REPLY 1:tuto-2/login: OK
 412 {
 413   "jtype":"afb-reply",
 414   "request":{
 415     "status":"success",
 416     "uuid":"a09f55ff-0e89-4f4e-8415-c6e0e7f439be"
 417   }
 418 }
 419 tuto-2 logout true
 420 ON-REPLY 2:tuto-2/logout: OK
 421 {
 422   "jtype":"afb-reply",
 423   "request":{
 424     "status":"success"
 425   }
 426 }
 427 ```
 428
 429 It produced in the first terminal:
 430
 431 ```bash
 432 ON-EVENT tuto-2/login:
 433 {
 434   "event":"tuto-2\/login",
 435   "data":"jobol",
 436   "jtype":"afb-event"
 437 }
 438 ON-EVENT tuto-2/logout:
 439 {
 440   "event":"tuto-2\/logout",
 441   "data":"jobol",
 442   "jtype":"afb-event"
 443 }
 444 ```