2 Overview of the bindings
3 ========================
5 The ***binder*** serves files through HTTP protocol and offers to
6 developers the capability to offer application API methods through HTTP or
9 The ***bindings*** are used to add **API** to ***binders***.
10 This part describes how to write a ***binding*** for ***binder***
11 or in other words how to add a new **API** to the system.
13 Excepting this summary, this section target developers.
15 This section shortly explain how to write a binding
16 using the C programming language.
18 It is convenient to install the ***binder*** on the
19 desktop used for writing the binding. It allows easy
22 ## Nature of a binding
24 A ***binding*** is an independent piece of software compiled as a shared
25 library and dynamically loaded by a ***binder***.
26 It is intended to provide one **API** (**A**pplication **P**rogramming
29 The **API** is designated and accessed through its name.
30 It contains several **verbs** that implement the ***binding***
31 functionalities. Each of these **verbs** is a **method** that
32 processes requests of applications and sends result.
34 The ***binding***'s methods are invoked by HTTP or websocket
37 The **methods** of the ***bindings*** are noted **api/verb**
38 where **api** is the **API** name of the binding and **verb** is
39 the **method**'s name within the **API**.
40 This notation comes from HTTP invocations that rely on URL path terminated
43 The name of an **API** can be made of any characters except:
45 - the control characters (\u0000 .. \u001f)
46 - the characters of the set { ' ', '"', '#', '%', '&',
47 '\'', '/', '?', '`', '\x7f' }
49 The names if the **verbs** can be any character.
51 The binder makes no distinctions between upper case and lower case
52 latin letters. So **API/VERB** matches **Api/Verb** or **api/verb**.
54 Actually it exists 2 ways of writing ***bindings***.
57 - a binding version 1 (not recommended);
58 - a binding version 2 (RECOMMENDED).
60 A ***binder*** loads and runs any of these version in any combination.
61 This document explain how to write bindings version 2.
64 Sample binding: tuto-1
65 ======================
67 This is the code of the binding **tuto-1.c**:
70 1 #define AFB_BINDING_VERSION 2
71 2 #include <afb/afb-binding.h>
73 4 void hello(afb_req req)
75 6 AFB_REQ_DEBUG(req, "hello world");
76 7 afb_req_success(req, NULL, "hello world");
79 10 const afb_verb_v2 verbs[] = {
80 11 { .verb="hello", .callback=hello },
84 15 const afb_binding_v2 afbBindingV2 = {
93 $ gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon)
99 $ afb-daemon --binding tuto-1.so --port 3333 --token ''
102 Testing using **curl**:
105 $ curl http://localhost:3333/api/tuto-1/hello
106 {"jtype":"afb-reply","request":{"status":"success","info":"hello world","uuid":"1e587b54-900b-49ab-9940-46141bc2e1d6"}}
109 Testing using **afb-client-demo** (with option -H for
110 getting a human readable output):
113 $ afb-client-demo -H ws://localhost:3333/api?token=x tuto-1 hello
114 ON-REPLY 1:tuto-1/hello: OK
119 "info":"hello world",
120 "uuid":"03a84ad1-458a-4ace-af74-b1da917391b9"
125 This shows basic things:
127 - The include to get for creating a binding
128 - How to declare the API offered by the binding
129 - How to handle request made to the binding
132 ### Getting declarations for the binding
134 The lines 1 and 2 show how to get the include file **afb-binding.h**.
137 1 #define AFB_BINDING_VERSION 2
138 2 #include <afb/afb-binding.h>
141 You must define the version of ***binding*** that you are using.
142 This is done line 1 where we define that this is the version 2.
144 If you don't define it, a warning message is prompted by the compiler
145 and the version is switched to version 1. This behaviour is
146 temporarily and enables to continue to use previously written
147 ***binding*** without change but it will change in some future when
148 ***bindings*** V1 will become obsoletes.
150 To include **afb-binding.h** successfully, the include search path
151 should be set correctly if needed (not needed only if installed in
152 /usr/include/afb directory that is the default).
154 Setting the include path is easy using **pkg-config**:
157 $ pkg-config --cflags-only-I afb-daemon
160 Note for **C++** developers: The ***binder*** currently expose
161 only **C** language **API**. The file **afb/afb-binding.h**
162 isn't **C++** ready. You should use the construct **extern "C"**
166 #define AFB_BINDING_VERSION 2
168 #include <afb/afb-binding.h>
172 Future version of the ***binder*** will include a **C++**
173 interface. Until it is available, please, use the above
176 ### Declaring the API of the binding
178 Lines 10 to 18 show the declaration of the ***binding***.
180 The ***binder*** knows that this is a ***binding*** version 2 because
181 it finds the exported symbol **afbBindingV2** that is expected to be
182 a structure of type **afb_binding_v2**.
185 10 const afb_verb_v2 verbs[] = {
186 11 { .verb="hello", .callback=hello },
190 15 const afb_binding_v2 afbBindingV2 = {
196 The structure **afbBindingV2** actually tells that:
198 - the exported **API** name is **tuto-1** (line 16)
199 - the array of verbs is the above defined one
201 The exported list of verb is specified by an array of structures,
202 each describing a verb, ended with a verb NULL (line 12).
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**).
208 Note that you can explicitly mark the fact that these are
209 struct by typing the **struct** as below:
212 10 const struct afb_verb_v2 verbs[] = {
213 11 { .verb="hello", .callback=hello },
217 15 const struct afb_binding_v2 afbBindingV2 = {
223 ### Handling binder's requests
225 As shown above this is by default the common include directory where
226 the AGL stuff is installed.
229 4 void hello(afb_req req)
231 6 AFB_REQ_DEBUG(req, "hello world");
232 7 afb_req_success(req, NULL, "hello world");
236 When the ***binder*** receives a request for the verb **hello** of
237 of the api **tuto-1**, it invoke the callback **hello** of the **binding**
238 with the argument **req** that handles the client request.
240 The callback has to treat synchronously or asynchronously the request and
241 should at the end emit a reply for the request.
243 Here, the callback for **tuto-1/hello** replies a successful answer
244 (line 7) to the request **req**. The second parameter (here NULL)
245 is a json object that is sent to the client with the reply.
246 The third parameter is also sent with the reply and is a string
247 called info that can be used as some meta data.
249 Here again, you can explicitly mark the fact that
250 **afb_req** is a structure by declaring **hello** as below:
253 4 void hello(struct afb_req req)
257 Sample binding: tuto-2
258 ======================
259 The second tutorial shows many important feature that can
260 commonly be used when writing a ***binding***: initialization,
261 getting arguments, sending replies, pushing events.
263 This is the code of the binding **tuto-2.c**:
266 1 #include <string.h>
267 2 #include <json-c/json.h>
269 4 #define AFB_BINDING_VERSION 2
270 5 #include <afb/afb-binding.h>
272 7 afb_event event_login, event_logout;
274 9 void login(afb_req req)
276 11 json_object *args, *user, *passwd;
279 14 args = afb_req_json(req);
280 15 if (!json_object_object_get_ex(args, "user", &user)
281 16 || !json_object_object_get_ex(args, "password", &passwd)) {
282 17 AFB_REQ_ERROR(req, "login, bad request: %s", json_object_get_string(args));
283 18 afb_req_fail(req, "bad-request", NULL);
284 19 } else if (afb_req_context_get(req)) {
285 20 AFB_REQ_ERROR(req, "login, bad state, logout first");
286 21 afb_req_fail(req, "bad-state", NULL);
287 22 } else if (strcmp(json_object_get_string(passwd), "please")) {
288 23 AFB_REQ_ERROR(req, "login, unauthorized: %s", json_object_get_string(args));
289 24 afb_req_fail(req, "unauthorized", NULL);
291 26 usr = strdup(json_object_get_string(user));
292 27 AFB_REQ_NOTICE(req, "login user: %s", usr);
293 28 afb_req_session_set_LOA(req, 1);
294 29 afb_req_context_set(req, usr, free);
295 30 afb_req_success(req, NULL, NULL);
296 31 afb_event_push(event_login, json_object_new_string(usr));
300 35 void action(afb_req req)
302 37 json_object *args, *val;
305 40 args = afb_req_json(req);
306 41 usr = afb_req_context_get(req);
307 42 AFB_REQ_NOTICE(req, "action for user %s: %s", usr, json_object_get_string(args));
308 43 if (json_object_object_get_ex(args, "subscribe", &val)) {
309 44 if (json_object_get_boolean(val)) {
310 45 AFB_REQ_NOTICE(req, "user %s subscribes to events", usr);
311 46 afb_req_subscribe(req, event_login);
312 47 afb_req_subscribe(req, event_logout);
314 49 AFB_REQ_NOTICE(req, "user %s unsubscribes to events", usr);
315 50 afb_req_unsubscribe(req, event_login);
316 51 afb_req_unsubscribe(req, event_logout);
319 54 afb_req_success(req, json_object_get(args), NULL);
322 57 void logout(afb_req req)
326 61 usr = afb_req_context_get(req);
327 62 AFB_REQ_NOTICE(req, "login user %s out", usr);
328 63 afb_event_push(event_logout, json_object_new_string(usr));
329 64 afb_req_session_set_LOA(req, 0);
330 65 afb_req_context_clear(req);
331 66 afb_req_success(req, NULL, NULL);
336 71 AFB_NOTICE("preinit");
342 77 AFB_NOTICE("init");
343 78 event_login = afb_daemon_make_event("login");
344 79 event_logout = afb_daemon_make_event("logout");
345 80 if (afb_event_is_valid(event_login) && afb_event_is_valid(event_logout))
347 82 AFB_ERROR("Can't create events");
351 86 const afb_verb_v2 verbs[] = {
352 87 { .verb="login", .callback=login },
353 88 { .verb="action", .callback=action, .session=AFB_SESSION_LOA_1 },
354 89 { .verb="logout", .callback=logout, .session=AFB_SESSION_LOA_1 },
358 93 const afb_binding_v2 afbBindingV2 = {
360 95 .specification = NULL,
362 97 .preinit = preinit,
364 99 .noconcurrency = 0
371 $ gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon)
377 $ afb-daemon --binding tuto-2.so --port 3333 --token ''
383 $ afb-client-demo -H localhost:3333/api?token=toto
384 tuto-2 login {"help":true}
385 ON-REPLY 1:tuto-2/login: ERROR
389 "status":"bad-request",
390 "uuid":"e2b24a13-fc43-487e-a5f4-9266dd1e60a9"
393 tuto-2 login {"user":"jose","password":"please"}
394 ON-REPLY 2:tuto-2/login: OK
401 tuto-2 login {"user":"jobol","password":"please"}
402 ON-REPLY 3:tuto-2/login: ERROR
409 tuto-2 action {"subscribe":true}
410 ON-REPLY 4:tuto-2/action: OK
422 In an other terminal:
425 $ afb-client-demo -H localhost:3333/api?token=toto
426 tuto-2 login {"user":"jobol","password":"please"}
427 ON-REPLY 1:tuto-2/login: OK
432 "uuid":"a09f55ff-0e89-4f4e-8415-c6e0e7f439be"
436 ON-REPLY 2:tuto-2/logout: OK
445 It produced in the first terminal:
448 ON-EVENT tuto-2/login:
450 "event":"tuto-2\/login",
454 ON-EVENT tuto-2/logout:
456 "event":"tuto-2\/logout",