# Summary
-* [Overview](README.md)
+* [Binder Overview](README.md)
* [How to write a binding ?](afb-binding-writing.md)
* [Binding references](afb-binding-references.md)
* [Migration from v1 to v2](afb-migration-v1-to-v2.md)
{
const char *verb; /* name of the verb */
void (*callback)(struct afb_req req); /* callback function implementing the verb */
- const struct afb_auth *auth; /* required authorisation */
- uint32_t session; /* authorisation and session requirements of the verb */
+ const struct afb_auth *auth; /* required authorization */
+ uint32_t session; /* authorization and session requirements of the verb */
};
```
```
The following function is used by logging macros and should normally
-not be used. Instead, you should use the macros
+not be used. Instead, you should use the macros
**AFB\_ERROR**, **AFB\_WARNING**, **AFB\_NOTICE**,
**AFB\_INFO**, **AFB\_DEBUG**
* If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
* At first, the job is called with 0 as signum and the given argument.
* The job is executed with the monitoring of its time and some signals like SIGSEGV and
- * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
+ * SIGFPE. When a such signal is catched, the job is terminated and re-executed but with
* signum being the signal number (SIGALRM when timeout expired).
*
* Returns 0 in case of success or -1 in case of error.
```
The following function must be used when a binding depends on other
-bindings at its initialisation.
+bindings at its initialization.
```C
/*
*
* Note that calling afb_req_fail("success", info) is equivalent
* to call afb_req_success(NULL, info). Thus even if possible it
- * is strongly recommanded to NEVER use "success" for status.
+ * is strongly recommended to NEVER use "success" for status.
*/
void afb_req_fail(struct afb_req req, const char *status, const char *info);
void afb_req_unref(struct afb_req req);
/*
- * Stores 'req' on heap for asynchrnous use.
+ * Stores 'req' on heap for asynchronous use.
* Returns a handler to the stored 'req' or NULL on memory depletion.
* The count of reference to 'req' is incremented on success
* (see afb_req_addref).
```
The following function is used by logging macros and should normally
-not be used. Instead, you should use the macros
+not be used. Instead, you should use the macros
**AFB_REQ_ERROR**, **AFB_REQ_WARNING**, **AFB_REQ_NOTICE**,
**AFB_REQ_INFO**, **AFB_REQ_DEBUG**
By default, the logging macros add file, line and function
indication.
-
-Some definitions can be used to
-
-
desktop used for writing the binding. It allows easy
debug and test.
-Nature of a binding
--------------------
+## 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***
-functionnalities. Each of these **verbs** is a **method** that
+functionalities. Each of these **verbs** is a **method** that
processes requests of applications and sends result.
-The ***binding***'s methods is invoqued by HTTP or websocket
+The ***binding***'s methods are invoked by HTTP or websocket
requests.
The **methods** of the ***bindings*** are noted **api/verb**
The names if the **verbs** can be any character.
-The binder mkes no distinctions between upper case and lower case
+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***.
You can either write:
- - a binding version 1 (not recommanded);
- - a binding version 2 (RECOMMANDED).
-
-A ***binder*** loads and runs any of these version
-in any combination.
+ - a binding version 1 (not recommended);
+ - a binding version 2 (RECOMMENDED).
+A ***binder*** loads and runs any of these version in any combination.
This document explain how to write bindings version 2.
-
+<!-- pagebreak -->
Sample binding: tuto-1
======================
```C
1 #define AFB_BINDING_VERSION 2
2 #include <afb/afb-binding.h>
- 3
+ 3
4 void hello(afb_req req)
5 {
6 AFB_REQ_DEBUG(req, "hello world");
7 afb_req_success(req, NULL, "hello world");
8 }
- 9
+ 9
10 const afb_verb_v2 verbs[] = {
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
- 14
+ 14
15 const afb_binding_v2 afbBindingV2 = {
16 .api = "tuto-1",
17 .verbs = verbs
***binding*** without change but it will change in some future when
***bindings*** V1 will become obsoletes.
-To include **afb-binding.h** successfuly, the include search path
-should be set correctly if needed (not needed only if installed in
+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**:
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
- 14
+ 14
15 const afb_binding_v2 afbBindingV2 = {
16 .api = "tuto-1",
17 .verbs = verbs
and the function that handle the related request is **hello**
(field **.callback**).
-Note that you can explicitely mark the fact that these are
+Note that you can explicitly mark the fact that these are
struct by typing the **struct** as below:
```C
11 { .verb="hello", .callback=hello },
12 { .verb=NULL }
13 };
- 14
+ 14
15 const struct afb_binding_v2 afbBindingV2 = {
16 .api = "tuto-1",
17 .verbs = verbs
```
When the ***binder*** receives a request for the verb **hello** of
-of the api **tuto-1**, it invoque the callback **hello** of the **binding**
+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.
Here, the callback for **tuto-1/hello** replies a successful answer
-(ligne 7) to the request **req**. The second parameter (here NULL)
+(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.
-Here again, you can explicitely mark the fact that
+Here again, you can explicitly mark the fact that
**afb_req** is a structure by declaring **hello** as below:
```C
4 void hello(struct afb_req req)
```
+<!-- pagebreak -->
Sample binding: tuto-2
======================
-
The second tutorial shows many important feature that can
-commonly be used when writting a ***binding***: initialisation,
+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
+ 3
4 #define AFB_BINDING_VERSION 2
5 #include <afb/afb-binding.h>
- 6
+ 6
7 afb_event event_login, event_logout;
- 8
+ 8
9 void login(afb_req 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)) {
31 afb_event_push(event_login, json_object_new_string(usr));
32 }
33 }
- 34
+ 34
35 void action(afb_req 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));
53 }
54 afb_req_success(req, json_object_get(args), NULL);
55 }
- 56
+ 56
57 void logout(afb_req 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));
65 afb_req_context_clear(req);
66 afb_req_success(req, NULL, NULL);
67 }
- 68
+ 68
69 int preinit()
70 {
71 AFB_NOTICE("preinit");
72 return 0;
73 }
- 74
+ 74
75 int init()
76 {
77 AFB_NOTICE("init");
82 AFB_ERROR("Can't create events");
83 return -1;
84 }
- 85
+ 85
86 const afb_verb_v2 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
+ 92
93 const afb_binding_v2 afbBindingV2 = {
94 .api = "tuto-2",
95 .specification = NULL,
--roothttp=xxxx
Directory of HTTP served files. If not set, files are not served
- but apis are still accessibles.
+ but apis are still accessible.
--rootbase=xxxx
instance. It implements an API and may provide a service.
Binding made for services can have specific entry point called after
-initialisation and before serving.
+initialization and before serving.
## Event
-Desktop packages for binder developement
+Desktop packages for binder development
========================================
It exists packages of the ***binder*** (afb-daemon)
- Debian
- Suse
-Installing the developement package of the ***binder***
-allows to write ***bindings*** that runs on the destop
-computer of the developper.
+Installing the development package of the ***binder***
+allows to write ***bindings*** that runs on the desktop
+computer of the developer.
It is very convenient to quickly write and debug a binding.
-Retriving compiling option with pkg-config
+Retrieving compiling option with pkg-config
==========================================
The ***binder*** afb-daemon provides a configuration
subscription. This is part of the step 5 above.
The framework only uses the event (not its name) for subscription,
-unsubscription and pushing.
+un-subscription and pushing.
When the requested data is already generated and the event used for
pushing it already exists, the signaling agent must not instantiate a
struct afb_event afb_daemon_make_event(const char *name);
```
-The correct way to create the event at initialisation is to call the function
-***afb\_daemon\_make\_event*** within the initialisation
+The correct way to create the event at initialization is to call the function
+***afb\_daemon\_make\_event*** within the initialization
function referenced by the field ***init*** of the structure ***afbBindingV2***.
### Function afb\_event\_push
/*
* Revokes the subscription established to the 'event' for the client
* link identified by 'req'.
- * Returns 0 in case of successful unsubscription or -1 in case of error.
+ * Returns 0 in case of successful un-subscription or -1 in case of error.
*/
int afb_req_unsubscribe(struct afb_req req, struct afb_event event);
```
-The unsubscription removes the client of the request of the list of subscribers
+The un-subscription removes the client of the request of the list of subscribers
to the event.
When the list of subscribers to the event becomes empty,
the function ***afb\_event\_push*** will return zero.
The name is given here explicitly. The name is automatically prefixed
with the name of the binding. For example, a binding of prefix "xxx"
-would broadcat the event "xxx/name".
+would broadcast the event "xxx/name".
### Function onevent (field of afbBindingV2)
- integration of the security requirements within the bindings
- simplification of the API (after developer feedbacks)
- - removal of obscur features, cleanup
+ - removal of obscure features, cleanup
The ***binder*** can run ***bindings*** v1 and/or v2 in any combination.
Thus moving from v1 to v2 is not enforced. There is no real need.
More, it is possible to write a dual ***binding***: a ***binding*** that
implements the version 1 AND the version 2.
-However, IT IS HIGHLY RECOMMANDED TO SWITCH TO ONLY VERSION 2:
+However, IT IS HIGHLY RECOMMENDED TO SWITCH TO ONLY VERSION 2:
- - any new developement SHOULD start using ***binding*** V2
+ - any new development SHOULD start using ***binding*** V2
- existing ***bindings*** SHOULD migrate to the version 2
This guide covers the migration of bindings from version 1 to version 2.
It simplifies the job, that's all and that is the reason of the change.
An other important difference is between the version 1 and the version 2 is
-on how the ***binding***'s **API** is documented. The version 2 enphasis the
+on how the ***binding***'s **API** is documented. The version 2 emphasis the
**OpenAPI v3** description of the **API**. For this reason, to avoid
duplication of descriptions, only one description is expected: the **OpenAPI** one.
5. Consider where to emit logs for requests
6. Take care of store/unstore changes
7. Consider use of synchronous (sub)call requests
- 8. Optionnaly, removes explicit struct
+ 8. Optionally, removes explicit struct
The remaining chapters explain these task with more details.
struct afb_verb_desc_v1
{
const char *name; /* name of the verb */
- enum afb_session_flags_v1 session; /* authorisation and session requirements of the verb */
+ enum afb_session_flags_v1 session; /* authorization and session requirements of the verb */
void (*callback)(struct afb_req req); /* callback function implementing the verb */
const char *info; /* textual description of the verb */
};
{
const char *verb; /* name of the verb */
void (*callback)(struct afb_req req); /* callback function implementing the verb */
- const struct afb_auth *auth; /* required authorisation */
- uint32_t session; /* authorisation and session requirements of the verb */
+ const struct afb_auth *auth; /* required authorization */
+ uint32_t session; /* authorization and session requirements of the verb */
};
```
- remove field **info**
- adapt field **session** if needed
- set field **auth** to NULL
-
+
Example:
```C
```
The field **auth** can be set to a value describing the requested
-authorisation.
+authorization.
The main describing structure also changed. In version 1 it was:
The migration of instances of that structure requires the following actions:
- - declare, expore, name the structure as ```const struct afb_binding_v2 afbBindingV2```
+ - declare, explore, name the structure as ```const struct afb_binding_v2 afbBindingV2```
- rename the field **prefix** to **api**
- remove the field **info**
- - setup the fields **preinit**, **init**, **onevent** accordling to the next section
+ - setup the fields **preinit**, **init**, **onevent** according to the next section
- set the field **noconcurrency** to the right value:
* to 1 if you want to avoid concurrent calls to verbs.
* to 0 if you allow concurrent calls to verbs.
The function **afbBindingV1ServiceInit** is replaced by the field **init**
of the structure **afbBindingV2**. The init function should return 0 in case
of success or a negative error code in case of problem. It is called during
-initialisation of services.
+initialization of services.
The function **afbBindingV1ServiceEvent**is replaced by the field **onevent**
of the structure **afbBindingV2**.
So the variable that ***bindings*** version used to store the ***binder*** interface
and the service interface are no more needed and can be removed.
-On the above example the folowing lines were removed:
+On the above example the following lines were removed:
```C
const struct afb_binding_interface *interface;
struct afb_service service;
Also, to avoid possible conflicts, we introduced prefixed logging functions:
the macros **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** have now
a prefixed version: **AFB\_ERROR**, **AFB\_WARNING**, **AFB\_NOTICE**,
-**AFB\_INFO**, **AFB\_DEBUG**. It is now recommanded to use the prefixed version.
+**AFB\_INFO**, **AFB\_DEBUG**. It is now recommended to use the prefixed version.
Example:
AFB_NOTICE("hello plugin comes to live");
```
-To remove definition of the unprefixed versions of logging macros **ERROR**, **WARNING**,
+To remove definition of the un-prefixed versions of logging macros **ERROR**, **WARNING**,
**NOTICE**, **INFO**, **DEBUG** and just define **AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX**
before to include **afb/afb-binding.h**.
The ***bindings*** v2 now allows to emit log messages associated to ***requests***.
This feature is valuable when debugging because it allows to return
-side informations associated to a ***request***.
+side information associated to a ***request***.
The defined macros for logging to requests are: **AFB_REQ_ERROR**,
**AFB_REQ_WARNING**, **AFB_REQ_NOTICE**, **AFB_REQ_INFO**, **AFB_REQ_DEBUG**.
Take care of store/unstore change
---------------------------------
-For efficiency, the version 2 redefined how storing/unstoring of
+For efficiency, the version 2 redefined how storing/un-storing of
requests works. Storing request is needed for asynchronous handling
of requests.
their clients (subcalls). With ***bindings*** version 2 comes
also synchronous requests for both cases.
-So when migrating to bindings version 2, a developper can consider
+So when migrating to bindings version 2, a developer can consider
to replace the asynchronous requests (with asynchronous call back)
by synchronous ones.
See functions ***afb_service_call_sync*** and ***afb_req_subcall_sync***.
-Optionnaly, removes explicit struct
+Optionally, removes explicit struct
-----------------------------------
The new definitions now includes **typedefs** for common
Example of migration
--------------------
-The first ***binding*** that migrated from v1 to v2 was
+The first ***binding*** that migrated from v1 to v2 was
the sample **HelloWorld**. Here is shown the differences between
the version 1 and the version 2.
--- a/bindings/samples/HelloWorld.c
+++ b/bindings/samples/HelloWorld.c
@@ -21,9 +21,9 @@
-
+
#include <json-c/json.h>
-
+
+#define AFB_BINDING_VERSION 2
#include <afb/afb-binding.h>
-
+
-const struct afb_binding_interface *interface;
static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
struct event
@@ -79,7 +80,7 @@ static int event_add(const char *tag, const char *name)
strcpy(e->tag, tag);
-
+
/* make the event */
- e->event = afb_daemon_make_event(interface->daemon, name);
+ e->event = afb_daemon_make_event(name);
if (!e->event.closure) { free(e); return -1; }
-
+
/* link */
@@ -140,7 +141,7 @@ static void pingBug (struct afb_req request)
static void pingEvent(struct afb_req request)
+ afb_daemon_broadcast_event("event", json_object_get(query));
ping(request, json_object_get(query), "event");
}
-
+
@@ -288,38 +289,43 @@ static void exitnow (struct afb_req request)
exit(0);
}
-
+
+static int preinit()
+{
+ AFB_NOTICE("hello binding comes to live");
+ { "exit", exitnow , NULL, AFB_SESSION_NONE },
+ { NULL}
};
-
+
-static const struct afb_binding plugin_desc = {
- .type = AFB_BINDING_VERSION_1,
- .v1 = {
+ .preinit = preinit,
+ .init = init
};
-
+
-const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf)
-{
- interface = itf;
-Overview of the binder
-======================
+Binder Overview
+===============
The ***binder*** provides the way to connect applications to
the services that it needs. It provides a fast way
to securely offer APIs to applications written in
any language and running almost anywhere.
-The ***binder*** is developped for AGL.
+The ***binder*** is developed for AGL.
The ***binder*** is the usual name.
The binary is named **afb-daemon**.
Each ***binder*** **afb-daemon** is in charge to bind
one instance of an application or service to the rest
of the system, applications and services.
-Within AGL, the connexion between services and/or
+Within AGL, the connection between services and/or
applications is tuned by the AGL framework and
the AGL system.
An **API** is a set of **verbs** that can be called
using either REST over HTTP or a kind of JSON RPC.
-
+
***bindings*** are either:
- dynamically loaded libraries in the ***binder*** process
- remote service running on other hosts
When acting as an HTTP server, the binder treats the language
- settings of the HTTP resquests to provide internationalized
+ settings of the HTTP requests to provide internationalized
content as specified by
[widget specifications](https://www.w3.org/TR/widgets/#internationalization-and-localization).
the **API** that it provides or to get its HTTP services to access
resources.
+<!-- pagebreak -->
+
Interconnection of binders
==========================
**C** and **D**.
The application **A** might use an **API** that is shown as a
-local ***binbing*** but that in reality runs within the context
+local ***binding*** but that in reality runs within the context
of **D**.
The framework AGL takes care of making the plumbing working.
-
Code Review / src / app-framework-binder.git / commitdiff