summaryrefslogtreecommitdiffstats
path: root/docs/afb-binding-writing.md
diff options
context:
space:
mode:
authorJosé Bollo <jose.bollo@iot.bzh>2018-04-09 18:16:07 +0200
committerJosé Bollo <jose.bollo@iot.bzh>2018-06-15 17:57:36 +0200
commit4521c1e7ae5371ab9d639adc617d17fb4e8ded0c (patch)
treea8a1416a2d58c16ab3993c7e4dc405fc71daab6a /docs/afb-binding-writing.md
parent63682b4da9d3e892d1d0a671de860adc43068142 (diff)
api-v3: First draft
This commit introduces the bindings v3 API for bindings. The documentation has still to be improved and will come very soon. Change-Id: I8f9007370e29f671fdfd1da87fff7372a17db7af Signed-off-by: José Bollo <jose.bollo@iot.bzh>
Diffstat (limited to 'docs/afb-binding-writing.md')
-rw-r--r--docs/afb-binding-writing.md180
1 files changed, 80 insertions, 100 deletions
diff --git a/docs/afb-binding-writing.md b/docs/afb-binding-writing.md
index aad422c4..69090e3d 100644
--- a/docs/afb-binding-writing.md
+++ b/docs/afb-binding-writing.md
@@ -51,14 +51,21 @@ The binder makes no distinctions between upper case and lower case
latin letters.
So **API/VERB** matches **Api/Verb** or **api/verb**.
-Actually it exists 2 ways of writing ***bindings***.
+## 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 recommended);
-- a binding version 2 (RECOMMENDED).
+- 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 2.
+This document explain how to write bindings version 3.
<!-- pagebreak -->
@@ -67,21 +74,21 @@ This document explain how to write bindings version 2.
This is the code of the binding **tuto-1.c**:
```C
- 1 #define AFB_BINDING_VERSION 2
+ 1 #define AFB_BINDING_VERSION 3
2 #include <afb/afb-binding.h>
3
- 4 void hello(afb_req req)
+ 4 void hello(afb_req_t req)
5 {
6 AFB_REQ_DEBUG(req, "hello world");
- 7 afb_req_success(req, NULL, "hello world");
+ 7 afb_req_reply(req, NULL, NULL, "hello world");
8 }
9
- 10 const afb_verb_v2 verbs[] = {
+ 10 const afb_verb_t verbs[] = {
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
14
- 15 const afb_binding_v2 afbBindingV2 = {
+ 15 const afb_binding_t afbBindingExport = {
16 .api = "tuto-1",
17 .verbs = verbs
18 };
@@ -93,12 +100,18 @@ Compiling:
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
@@ -133,18 +146,15 @@ This shows basic things:
The lines 1 and 2 show how to get the include file **afb-binding.h**.
```C
- 1 #define AFB_BINDING_VERSION 2
+ 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 2.
+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, a warning message is prompted by the compiler
-and the version is switched to version 1.
-This behaviour is temporarily and enables to continue to use previously written
-***binding*** without change but it will change in some future when
-***bindings*** V1 will become obsoletes.
+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
@@ -156,81 +166,54 @@ Setting the include path is easy using **pkg-config**:
pkg-config --cflags-only-I afb-daemon
```
-Note for **C++** developers:
-
-- The ***binder*** currently expose only **C** language **API**.
- The file **afb/afb-binding.h** isn't **C++** ready.
-
-You should use the construct **extern "C"** as below:
+> 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**).
-```C
- #define AFB_BINDING_VERSION 2
- extern "C" {
- #include <afb/afb-binding.h>
- }
-```
-
-Future version of the ***binder*** will include a **C++**
-interface.
-Until it is available, please, use the above construct.
### Declaring the API of the binding
Lines 10 to 18 show the declaration of the ***binding***.
-The ***binder*** knows that this is a ***binding*** version 2 because
-it finds the exported symbol **afbBindingV2** that is expected to be
-a structure of type **afb_binding_v2**.
+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_v2 verbs[] = {
+ 10 const afb_verb_t verbs[] = {
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
14
- 15 const afb_binding_v2 afbBindingV2 = {
+ 15 const afb_binding_t afbBindingExport = {
16 .api = "tuto-1",
17 .verbs = verbs
18 };
```
-The structure **afbBindingV2** actually tells that:
+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,
-each describing a verb, ended with a verb NULL (line 12).
+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**).
-Note that you can explicitly mark the fact that these are
-struct by typing the **struct** as below:
-
-```C
- 10 const struct afb_verb_v2 verbs[] = {
- 11 { .verb="hello", .callback=hello },
- 12 { .verb=NULL }
- 13 };
- 14
- 15 const struct afb_binding_v2 afbBindingV2 = {
- 16 .api = "tuto-1",
- 17 .verbs = verbs
- 18 };
-```
-
### 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 req)
+ 4 void hello(afb_req_t req)
5 {
6 AFB_REQ_DEBUG(req, "hello world");
- 7 afb_req_success(req, NULL, "hello world");
+ 7 afb_req_reply(req, NULL, NULL, "hello world");
8 }
```
@@ -241,18 +224,15 @@ 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.
-Here, the callback for **tuto-1/hello** replies a successful answer
-(line 7) to the request **req**.
-The second parameter (here NULL) is a json object that is sent to the client with the reply.
-The third parameter is also sent with the reply and is a string
-called info that can be used as some meta data.
+At the line 7, the callback for **tuto-1/hello** replies to the request **req**.
+Parameters of the reply are:
-Here again, you can explicitly mark the fact that
-**afb_req** is a structure by declaring **hello** as below:
+ 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.
-```C
- 4 void hello(struct afb_req req)
-```
+The 3 last parameters are sent back to the client as the reply content.
<!-- pagebreak -->
@@ -268,43 +248,43 @@ 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 2
+ 3
+ 4 #define AFB_BINDING_VERSION 3
5 #include <afb/afb-binding.h>
- 6
- 7 afb_event event_login, event_logout;
- 8
- 9 void login(afb_req req)
+ 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
+ 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_fail(req, "bad-request", NULL);
+ 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_fail(req, "bad-state", NULL);
+ 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_fail(req, "unauthorized", NULL);
+ 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_success(req, NULL, NULL);
+ 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 req)
+ 34
+ 35 void action(afb_req_t req)
36 {
37 json_object *args, *val;
38 char *usr;
- 39
+ 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));
@@ -319,46 +299,46 @@ This is the code of the binding **tuto-2.c**:
51 afb_req_unsubscribe(req, event_logout);
52 }
53 }
- 54 afb_req_success(req, json_object_get(args), NULL);
+ 54 afb_req_reply(req, json_object_get(args), NULL, NULL);
55 }
- 56
- 57 void logout(afb_req req)
+ 56
+ 57 void logout(afb_req_t req)
58 {
59 char *usr;
- 60
+ 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_success(req, NULL, NULL);
+ 66 afb_req_reply(req, NULL, NULL, NULL);
67 }
- 68
- 69 int preinit()
+ 68
+ 69 int preinit(afb_api_t api)
70 {
- 71 AFB_NOTICE("preinit");
+ 71 AFB_API_NOTICE(api, "preinit");
72 return 0;
73 }
- 74
- 75 int init()
+ 74
+ 75 int init(afb_api_t api)
76 {
- 77 AFB_NOTICE("init");
- 78 event_login = afb_daemon_make_event("login");
- 79 event_logout = afb_daemon_make_event("logout");
+ 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_ERROR("Can't create events");
+ 82 AFB_API_ERROR(api, "Can't create events");
83 return -1;
84 }
- 85
- 86 const afb_verb_v2 verbs[] = {
+ 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_v2 afbBindingV2 = {
+ 92
+ 93 const afb_binding_t afbBindingExport = {
94 .api = "tuto-2",
95 .specification = NULL,
96 .verbs = verbs,