blob: 69090e3dbcb7f1036d4a824347bca132837c89fa (
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
# Overview of the bindings
The ***binder*** serves files through HTTP protocol and offers to
developers the capability to offer application API methods through HTTP or
WebSocket protocol.
The ***bindings*** are used to add **API** to ***binders***.
This part describes how to write a ***binding*** for ***binder***
or in other words how to add a new **API** to the system.
Excepting this summary, this section target developers.
This section shortly explain how to write a binding
using the C programming language.
It is convenient to install the ***binder*** on the
desktop used for writing the binding.
It allows easy debug and test.
## Nature of a binding
A ***binding*** is an independent piece of software compiled as a shared
library and dynamically loaded by a ***binder***.
It is intended to provide one **API** (**A**pplication **P**rogramming
**I**nterface).
The **API** is designated and accessed through its name.
It contains several **verbs** that implement the ***binding***
functionalities.
Each of these **verbs** is a **method** that
processes requests of applications and sends result.
The ***binding***'s methods are invoked by HTTP or websocket
requests.
The **methods** of the ***bindings*** are noted **api/verb**
where **api** is the **API** name of the binding and **verb** is
the **method**'s name within the **API**.
This notation comes from HTTP invocations that rely on URL path terminated
with **api/verb**.
The name of an **API** can be made of any characters except:
- the control characters (\u0000 .. \u001f)
- the characters of the set { ' ', '"', '#', '%', '&',
'\'', '/', '?', '`', '\x7f' }
The names of the **verbs** can be any character.
The binder makes no distinctions between upper case and lower case
latin letters.
So **API/VERB** matches **Api/Verb** or **api/verb**.
## Versions of the bindings
Since introduction of the binder, the way how bindings are written
evolved a little. While changing, attention was made to ensure binary
compatibility between the different versions.
Actually it exists 3 ways of writing ***bindings***.
You can either write:
- a binding version 1 (not more supported);
- a binding version 2 (not recommended);
- a binding version 3 (RECOMMENDED).
A ***binder*** loads and runs any of these version in any combination.
This document explain how to write bindings version 3.
<!-- pagebreak -->
## Sample binding: tuto-1
This is the code of the binding **tuto-1.c**:
```C
1 #define AFB_BINDING_VERSION 3
2 #include <afb/afb-binding.h>
3
4 void hello(afb_req_t req)
5 {
6 AFB_REQ_DEBUG(req, "hello world");
7 afb_req_reply(req, NULL, NULL, "hello world");
8 }
9
10 const afb_verb_t verbs[] = {
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
14
15 const afb_binding_t afbBindingExport = {
16 .api = "tuto-1",
17 .verbs = verbs
18 };
```
Compiling:
```bash
gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon)
```
> Note: the variable environment variable PKG_CONFIG_PATH might be necessary
> tuned to get **pkg-config** working properly
Running:
```bash
afb-daemon --binding tuto-1.so --port 3333 --token ''
```
At this point, afb-daemon has started, it loaded the binding tuto-1.so and now
listen at localhost on the port 3333.
Testing using **curl**:
```bash
$ curl http://localhost:3333/api/tuto-1/hello
{"jtype":"afb-reply","request":{"status":"success","info":"hello world","uuid":"1e587b54-900b-49ab-9940-46141bc2e1d6"}}
```
Testing using **afb-client-demo** (with option -H for
getting a human readable output):
```bash
$ afb-client-demo -H ws://localhost:3333/api?token=x tuto-1 hello
ON-REPLY 1:tuto-1/hello: OK
{
"jtype":"afb-reply",
"request":{
"status":"success",
"info":"hello world",
"uuid":"03a84ad1-458a-4ace-af74-b1da917391b9"
}
}
```
This shows basic things:
- The include to get for creating a binding
- How to declare the API offered by the binding
- How to handle request made to the binding
### Getting declarations for the binding
The lines 1 and 2 show how to get the include file **afb-binding.h**.
```C
1 #define AFB_BINDING_VERSION 3
2 #include <afb/afb-binding.h>
```
You must define the version of ***binding*** that you are using.
This is done line 1 where we define that this is the version 3 (earlier
versions 1 and 2 are deprecated).
If you don't define it, an error is reported and the compilation aborts.
To include **afb-binding.h** successfully, the include search path
should be set correctly if needed (not needed only if installed in
/usr/include/afb directory that is the default).
Setting the include path is easy using **pkg-config**:
```bash
pkg-config --cflags-only-I afb-daemon
```
> Note for **C++** developers:
>
> The ***binder*** currently expose a draft version of **C++** api.
> To get it include the file <**afb/afb-binding**> (without **.h**).
### Declaring the API of the binding
Lines 10 to 18 show the declaration of the ***binding***.
The ***binder*** knows that this is a ***binding*** because
it finds the exported symbol **afbBindingExport** that is expected to be
a structure of type **afb_binding_t**.
```C
10 const afb_verb_t verbs[] = {
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
14
15 const afb_binding_t afbBindingExport = {
16 .api = "tuto-1",
17 .verbs = verbs
18 };
```
The structure **afbBindingExport** actually tells that:
- the exported **API** name is **tuto-1** (line 16)
- the array of verbs is the above defined one
The exported list of verb is specified by an array of structures of
type **afb_verb_t**, each describing a verb, ended with a verb NULL (line 12).
The only defined verb here (line 11) is named **hello** (field **.verb**)
and the function that handle the related request is **hello**
(field **.callback**).
### Handling binder's requests
As shown above this is by default the common include directory where
the AGL stuff is installed.
```C
4 void hello(afb_req_t req)
5 {
6 AFB_REQ_DEBUG(req, "hello world");
7 afb_req_reply(req, NULL, NULL, "hello world");
8 }
```
When the ***binder*** receives a request for the verb **hello** of
of the api **tuto-1**, it invoke the callback **hello** of the **binding**
with the argument **req** that handles the client request.
The callback has to treat synchronously or asynchronously the request and
should at the end emit a reply for the request.
At the line 7, the callback for **tuto-1/hello** replies to the request **req**.
Parameters of the reply are:
1. The first parameter is the replied request
2. The second parameter is a json object (here NULL)
3. The third parameter is the error string indication (here NULL: no error)
4. The fourth parameter is an informative string (that can be NULL) that can be used to provide meta data.
The 3 last parameters are sent back to the client as the reply content.
<!-- pagebreak -->
## Sample binding: tuto-2
The second tutorial shows many important feature that can
commonly be used when writing a ***binding***:
- initialization, getting arguments, sending replies, pushing events.
This is the code of the binding **tuto-2.c**:
```C
1 #include <string.h>
2 #include <json-c/json.h>
3
4 #define AFB_BINDING_VERSION 3
5 #include <afb/afb-binding.h>
6
7 afb_event_t event_login, event_logout;
8
9 void login(afb_req_t req)
10 {
11 json_object *args, *user, *passwd;
12 char *usr;
13
14 args = afb_req_json(req);
15 if (!json_object_object_get_ex(args, "user", &user)
16 || !json_object_object_get_ex(args, "password", &passwd)) {
17 AFB_REQ_ERROR(req, "login, bad request: %s", json_object_get_string(args));
18 afb_req_reply(req, NULL, "bad-request", NULL);
19 } else if (afb_req_context_get(req)) {
20 AFB_REQ_ERROR(req, "login, bad state, logout first");
21 afb_req_reply(req, NULL, "bad-state", NULL);
22 } else if (strcmp(json_object_get_string(passwd), "please")) {
23 AFB_REQ_ERROR(req, "login, unauthorized: %s", json_object_get_string(args));
24 afb_req_reply(req, NULL, "unauthorized", NULL);
25 } else {
26 usr = strdup(json_object_get_string(user));
27 AFB_REQ_NOTICE(req, "login user: %s", usr);
28 afb_req_session_set_LOA(req, 1);
29 afb_req_context_set(req, usr, free);
30 afb_req_reply(req, NULL, NULL, NULL);
31 afb_event_push(event_login, json_object_new_string(usr));
32 }
33 }
34
35 void action(afb_req_t req)
36 {
37 json_object *args, *val;
38 char *usr;
39
40 args = afb_req_json(req);
41 usr = afb_req_context_get(req);
42 AFB_REQ_NOTICE(req, "action for user %s: %s", usr, json_object_get_string(args));
43 if (json_object_object_get_ex(args, "subscribe", &val)) {
44 if (json_object_get_boolean(val)) {
45 AFB_REQ_NOTICE(req, "user %s subscribes to events", usr);
46 afb_req_subscribe(req, event_login);
47 afb_req_subscribe(req, event_logout);
48 } else {
49 AFB_REQ_NOTICE(req, "user %s unsubscribes to events", usr);
50 afb_req_unsubscribe(req, event_login);
51 afb_req_unsubscribe(req, event_logout);
52 }
53 }
54 afb_req_reply(req, json_object_get(args), NULL, NULL);
55 }
56
57 void logout(afb_req_t req)
58 {
59 char *usr;
60
61 usr = afb_req_context_get(req);
62 AFB_REQ_NOTICE(req, "login user %s out", usr);
63 afb_event_push(event_logout, json_object_new_string(usr));
64 afb_req_session_set_LOA(req, 0);
65 afb_req_context_clear(req);
66 afb_req_reply(req, NULL, NULL, NULL);
67 }
68
69 int preinit(afb_api_t api)
70 {
71 AFB_API_NOTICE(api, "preinit");
72 return 0;
73 }
74
75 int init(afb_api_t api)
76 {
77 AFB_API_NOTICE(api, "init");
78 event_login = afb_api_make_event(api, "login");
79 event_logout = afb_api_make_event(api, "logout");
80 if (afb_event_is_valid(event_login) && afb_event_is_valid(event_logout))
81 return 0;
82 AFB_API_ERROR(api, "Can't create events");
83 return -1;
84 }
85
86 const afb_verb_t verbs[] = {
87 { .verb="login", .callback=login },
88 { .verb="action", .callback=action, .session=AFB_SESSION_LOA_1 },
89 { .verb="logout", .callback=logout, .session=AFB_SESSION_LOA_1 },
90 { .verb=NULL }
91 };
92
93 const afb_binding_t afbBindingExport = {
94 .api = "tuto-2",
95 .specification = NULL,
96 .verbs = verbs,
97 .preinit = preinit,
98 .init = init,
99 .noconcurrency = 0
100 };
```
Compiling:
```bash
gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon)
```
Running:
```bash
afb-daemon --binding tuto-2.so --port 3333 --token ''
```
Testing:
```bash
$ afb-client-demo -H localhost:3333/api?token=toto
tuto-2 login {"help":true}
ON-REPLY 1:tuto-2/login: ERROR
{
"jtype":"afb-reply",
"request":{
"status":"bad-request",
"uuid":"e2b24a13-fc43-487e-a5f4-9266dd1e60a9"
}
}
tuto-2 login {"user":"jose","password":"please"}
ON-REPLY 2:tuto-2/login: OK
{
"jtype":"afb-reply",
"request":{
"status":"success"
}
}
tuto-2 login {"user":"jobol","password":"please"}
ON-REPLY 3:tuto-2/login: ERROR
{
"jtype":"afb-reply",
"request":{
"status":"bad-state"
}
}
tuto-2 action {"subscribe":true}
ON-REPLY 4:tuto-2/action: OK
{
"response":{
"subscribe":true
},
"jtype":"afb-reply",
"request":{
"status":"success"
}
}
```
In an other terminal:
```bash
$ afb-client-demo -H localhost:3333/api?token=toto
tuto-2 login {"user":"jobol","password":"please"}
ON-REPLY 1:tuto-2/login: OK
{
"jtype":"afb-reply",
"request":{
"status":"success",
"uuid":"a09f55ff-0e89-4f4e-8415-c6e0e7f439be"
}
}
tuto-2 logout true
ON-REPLY 2:tuto-2/logout: OK
{
"jtype":"afb-reply",
"request":{
"status":"success"
}
}
```
It produced in the first terminal:
```bash
ON-EVENT tuto-2/login:
{
"event":"tuto-2\/login",
"data":"jobol",
"jtype":"afb-event"
}
ON-EVENT tuto-2/logout:
{
"event":"tuto-2\/logout",
"data":"jobol",
"jtype":"afb-event"
}
```
|