--- /dev/null
+
+How to write a binding for AFB-DAEMON
+===================================
+
+Summary
+-------
+
+The afb-daemon binders serve 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 ***afb-daemon***.
+This part describes how to write a binding for***afb-daemon***.
+
+Excepting this summary, this document target developers.
+
+Before moving further through an example, here after
+a short overview of binder bindings fundamentals.
+
+### Nature of a binding
+
+A binding is an independent piece of software. A binding is self contain and
+exposes application logic as sharable library. A binding is intended to be
+dynamically loaded by ***afb-daemon*** to expose application API.
+
+Technically, a binder binding does not reference and is not linked with any
+***afb-daemon*** library.
+
+### Class of bindings
+
+Application binder supports two kinds of bindings: application bindings and
+service bindings. Technically both class of binding are equivalent and use the
+same coding convention. Only sharing mode and security context diverge.
+
+#### Application-bindings
+
+Application-bindings implements the glue in between application's UI and
+services. Every AGL application has a corresponding binder that typically
+activates one or many bindings to interface the application logic with lower
+platform services. When an application is started by the AGL application
+framework, a dedicate binder is started that loads/activates application
+binding(s). API expose by application-binding are executed within corresponding
+application security context.
+
+Application bindings generally handle a unique context for a unique client. As
+the application framework start a dedicated instance of afb_daemon for each AGL
+application, if a given binding is used within multiple application each of
+those application get a new and private instance of eventually "shared" binding.
+
+#### Service-bindings
+
+Service-bindings enable API activation within corresponding service security
+context and not within calling application context. Service-bindings are
+intended to run as a unique instance. Service-bindings can be shared in between
+multiple clients.
+
+Service-bindings can either be stateless or manage client context. When managing
+context each client get a private context. Sharing may either be global to the
+platform (ie: GPS service) or dedicated to a given user (ie: user preferences)
+
+### Live cycle of bindings within ***afb-daemon***
+
+Application and service bindings are loaded and activated each time a new
+***afb-daemon*** is started.
+
+At launch time, every loaded binding initialise itself. If a single binding
+initialisation fails the corresponding instance of ***afb-daemon*** aborts.
+
+Conversely, when a binding initialisation succeeds, it should register its
+unique name as well as the list of verbs (methods name from binder point of
+view) attached to the methods it exposes.
+
+When initialised, on request from application clients to the right API/verbs
+binding methods are activated by the ***afb-daemon*** attached to the
+application or service.
+
+At exit time, no special action is enforced by ***afb-daemon***. When a specific
+actions is required at afb-daemon stop, developers should use 'atexit/on_exit'
+during binding initialisation sequence to register a custom exit function.
+
+### Binding Content
+
+Afb-daemon's bindings register two classes of objects: names and functions.
+
+Bindings declare categories of names:
+ - A unique binding name to access all API exposed by this binding,
+ - One name for each methods/verbs provided by this binding.
+
+Bindings declare two categories of functions:
+ - function used for initialisation
+ - functions implementing the exposed API methods
+
+Afb-daemon parses URI requests to extract the API(binding name) and the
+VERB(method to activate). As an example, URI **foo/bar** translates to binding
+named **foo** and method named **bar**. To serve such a request,
+***afb-daemon*** looks for an active binding named **foo** and then within this
+binding for a method named **bar**. When found ***afb-daemon*** calls
+the corresponding method with an attached parameter if any.
+
+Afb-daemon is case-insensitive when parsing URI. Thus **TicTacToe/Board** and
+**tictactoe/board** are equivalent.
+
+#### The name of the binding
+
+The name of a given binding is also known as the name
+of the API prefix that defines the binding.
+
+The name of a binding SHOULD be unique within a given ***afb-daemon*** instance.
+
+For example, when a client of ***afb-daemon*** calls a URI named **foo/bar**.
+Afb-daemon extracts the prefix **foo** and the suffix **bar**. **foo** must
+match a binding name and **bar** has to match a VERB attached to some method.
+
+#### Names of methods
+
+Each binding exposes a set of methods that can be called by the clients of a
+given ***afb-daemon***.
+
+VERB's name attached to a given binding (API) MUST be unique within a binding.
+
+Bindings static declaration link VERBS to the corresponding methods.
+When clients emit requests on a given API/VERB corresponding method is called
+by ***afb-daemon***.
+
+#### Initialisation function
+
+Binding's initialisation function serves several purposes.
+
+1. It allows ***afb-daemon*** to control the binding version depending on
+the initialisation of function name. As today, the only supported initialisation
+function is **afbBindingV1Register**. This identifies version "one" of bindings.
+
+2. It allows bindings to initialise itself.
+
+3. It enables names declarations: descriptions, requirements and implementations
+of exposed API/VERB.
+
+#### Functions instantiation of API/VERBs
+
+When an API/VERB is called, ***afb-daemon*** constructs a request object. Then
+it passes this request object to the implementation function corresponding to
+requested method, this within attached API binding.
+
+An implementation function receives a request object used to: get
+the arguments of the request, send an answer, store session data.
+
+A binding MUST set an answer to every received requests.
+
+Nevertheless, there are two implementations, *synchronous* and *asynchronous*.
+API/VERB implementation that set an answer before returning are called
+*synchronous implementations*. Those that do not systematically set an answer
+before returning are called *asynchronous implementations*.
+
+Asynchronous implementations typically launch asynchronous actions. They record
+some context at request time and provide an answer to the request only at
+completion of asynchronous actions.
+
+The Tic-Tac-Toe example
+-----------------------
+
+This part explains how to write an afb-binding. For the sake of being practical
+it uses many examples based on tic-tac-toe. This binding example is in
+*bindings/samples/tic-tac-toe.c*.
+
+This binding is named ***tictactoe***.
+
+Dependencies when compiling
+---------------------------
+
+Afb-daemon provides a configuration file for *pkg-config*.
+Typing the command
+
+ pkg-config --cflags afb-daemon
+
+Print flags use for compilation:
+
+ $ pkg-config --cflags afb-daemon
+ -I/opt/local/include -I/usr/include/json-c
+
+For linking, you should use
+
+ $ pkg-config --libs afb-daemon
+ -ljson-c
+
+Afb-daemon automatically includes the dependency to json-c.
+This is activated through **Requires** keyword in pkg-config.
+While almost every binding replies on **json-c** this is not a must have
+dependency.
+
+Internally, ***afb-daemon*** relies on **libsystemd** for its event loop, as
+well as for its binding to D-Bus. Bindings developers are encouraged to leverage
+**libsystemd** when possible. Nevertheless there is no hard dependency to
+**libsystemd** if you do not want to use it, feel free to do so.
+
+> Afb-daemon bindings are fully self contained. They do not enforce dependency
+on any libraries from the application framework.
+> Afb-daemon dependencies requirer to run AGL bindings are given at runtime
+through pointers leveraging read-only
+> memory feature.
+
+Header files to include
+-----------------------
+
+Binding *tictactoe* has following includes:
+
+```C
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <string.h>
+#include <json-c/json.h>
+#include <afb/afb-binding.h>
+```
+
+Header *afb/afb-binding.h* is the only hard dependency, it includes all features
+that a binding MUST HAVE. Outside of includes used to support application logic,
+common external headers used within bindings are:
+
+- *json-c/json.h*: should be include to handle json objects;
+- *systemd/sd-event.h*: should be include to access event main loop;
+- *systemd/sd-bus.h*: should be include for dbus connections.
+
+The *tictactoe* binding does not leverage systemd features, also only json.h
+is used on top of mandatory afb/afb-binding.h.
+
+When including *afb/afb-binding.h*, the macro **_GNU_SOURCE** MUST be
+defined.
+
+Choosing names
+--------------
+
+Designers of bindings should define a unique name for every API binding
+as well as for methods VERBs. They should also define names for request
+arguments passed as name/value pair in URI.
+
+While forging names, designers should respect few rules to
+ensure that created names are valid and easy to use across platforms.
+
+All names and strings are UTF-8 encoded.
+
+### Names for API (binding)
+
+Binding API name are checked.
+All characters are authorised except:
+
+- the control characters (\u0000 .. \u001f)
+- the characters of the set { ' ', '"', '#', '%', '&',
+ '\'', '/', '?', '`', '\x7f' }
+
+In other words the set of forbidden characters is
+{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027,
+ \u002f, \u003f, \u0060, \u007f }.
+
+Afb-daemon makes no distinction between lower case
+and upper case when searching for API/VERB.
+
+### Names for methods
+
+The names of methods VERBs are totally free and not checked.
+
+However, the validity rules for method's VERB name are the
+same as for Binding API name except that the dot(.) character
+is forbidden.
+
+Afb-daemon makes no case distinction when searching for an API by name.
+
+### Names for arguments
+
+Argument's name are not restricted and can be everything you wish.
+
+> Warning arguments search is case sensitive and "index" and "Index"
+> are not two different arguments.
+
+### Forging names widely available
+
+The key names of javascript object can be almost
+anything using the arrayed notation:
+
+ object[key] = value
+
+Nevertheless this is not the case with javascript dot notation:
+
+ object.key = value
+
+Using the dot notation, the key must be a valid javascript
+identifier and dash(-) as well as few other reserved characters cannot be used.
+
+For this reason, we advise developers to chose name compatible with both
+javascript and HTML notation.
+
+It is a good practice, even for arguments not to rely on case sensitivity.
+This may reduce headache strength at debug time, especially with interpreted
+language like javascript that may not warn you that a variable was not defined.
+
+Declaration of methods and initialisation of the bindings
+---------------------------------------------------------
+
+### Declaration of methods
+
+To be active, binding's methods should be declared to
+***afb-daemon***. Furthermore, the binding itself must be recorded.
+
+The registration mechanism is very basic: when ***afb-daemon*** starts,
+it loads all bindings listed in: command line or configuration file.
+
+Loading a binding follows the following steps:
+
+1. Afb-daemon loads the binding with *dlopen*.
+
+2. Afb-daemon searches for a symbol named **afbBindingV1Register** using *dlsym*.
+This symbol is assumed to be the exported initialisation function of the binding.
+
+3. Afb-daemon builds an interface object for the binding.
+
+4. Afb-daemon calls the found function **afbBindingV1Register** with interface pointer
+as parameter.
+
+5. Function **afbBindingV1Register** setups the binding and initialises it.
+
+6. Function **afbBindingV1Register** returns the pointer to a structure
+describing the binding: version, name (prefix or API name), and list of methods.
+
+7. Afb-daemon checks that the returned version and name can be managed.
+If so, binding and its methods are register to become usable as soon as
+***afb-daemon*** initialisation is finished.
+
+### Initialisation of bindings
+
+The bindings initialisation is the final step made at the end of declaration of
+methods. This will initialize the binding and make its ***afb-daemon***'s
+interface fully functional.
+
+So, afb-daemon binder call **afbBindingV1ServiceInit** as final step to a
+binding. This will allows the binding to call features in its name and as saw in
+[Binder events guide](afb-events-guide.md) you can create an event only at this
+moment and not before. Before that it will fail because afb-daemon doesn't know
+the binding name.
+
+**afbBindingV1ServiceInit** is defined as below:
+
+```C
+/*
+ * When a binding have an exported implementation of the
+ * function 'afbBindingV1ServiceInit', defined below,
+ * the framework calls it for initialising the service after
+ * registration of all bindings.
+ *
+ * The object 'service' should be recorded. It has functions that
+ * allows the binding to call features with its own personality.
+ *
+ * The function should return 0 in case of success or, else, should return
+ * a negative value.
+ */
+extern int afbBindingV1ServiceInit(struct afb_service service);
+```
+
+### Application binding example: tic-tac-toe
+
+If we continue our tic-tac-toe example, here after the code used for
+**afbBindingV1Register** implementation from binding *tic-tac-toe*:
+
+```C
+/*
+ * activation function for registering the binding called by afb-daemon
+ */
+const struct afb_binding *afbBindingV1Register(const struct afb_binding_interface *itf)
+{
+ afbitf = itf; // records the interface for accessing afb-daemon
+ return &binding_description; // returns the description of the binding
+}
+```
+
+It is a very minimal initialisation function because *tic-tac-toe* binding doesn't
+have any application related initialisation step. It merely record daemon's interface
+and returns its description.
+
+The variable **afbitf** is a binding global variable. It keeps the
+interface to ***afb-daemon*** that should be used for logging and pushing events.
+Here is its declaration:
+
+```C
+/*
+ * the interface to afb-daemon
+ */
+const struct afb_binding_interface *afbitf;
+```
+
+The description of the binding is defined here after.
+
+```C
+/*
+ * array of the methods exported to afb-daemon
+ */
+static const struct afb_verb_desc_v1 binding_methods[] = {
+ /* VERB'S NAME SESSION MANAGEMENT FUNCTION TO CALL SHORT DESCRIPTION */
+ { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" },
+ { .name= "play", .session= AFB_SESSION_NONE, .callback= play, .info= "Asks the server to play" },
+ { .name= "move", .session= AFB_SESSION_NONE, .callback= move, .info= "Tells the client move" },
+ { .name= "board", .session= AFB_SESSION_NONE, .callback= board, .info= "Get the current board" },
+ { .name= "level", .session= AFB_SESSION_NONE, .callback= level, .info= "Set the server level" },
+ { .name= "join", .session= AFB_SESSION_CHECK,.callback= join, .info= "Join a board" },
+ { .name= "undo", .session= AFB_SESSION_NONE, .callback= undo, .info= "Undo the last move" },
+ { .name= "wait", .session= AFB_SESSION_NONE, .callback= wait, .info= "Wait for a change" },
+ { .name= NULL } /* marker for end of the array */
+};
+
+/*
+ * description of the binding for afb-daemon
+ */
+static const struct afb_binding binding_description =
+{
+ /* description conforms to VERSION 1 */
+ .type= AFB_BINDING_VERSION_1,
+ .v1= { /* fills the v1 field of the union when AFB_BINDING_VERSION_1 */
+ .prefix= "tictactoe", /* the API name (or binding name or prefix) */
+ .info= "Sample tac-tac-toe game", /* short description of of the binding */
+ .methods = binding_methods /* the array describing the methods of the API */
+ }
+};
+```
+
+The structure **binding_description** describes the binding.
+It declares the type and version of the binding, its name, a short description
+and its methods list.
+
+The list of methods is an array of structures describing the methods and terminated by a NULL marker.
+
+In version one of afb-damon binding, a method description contains 4 fields:
+
+- the name of the method,
+
+- the session management flags,
+
+- the implementation function to be call for the method,
+
+- a short description.
+
+The structure describing methods is defined as follows:
+
+```C
+/*
+ * Description of one method of the API provided by the binding
+ * This enumeration is valid for bindings of type 1
+ */
+struct afb_verb_desc_v1
+{
+ const char *name; /* name of the method */
+ enum AFB_session_v1 session; /* authorisation and session requirements of the method */
+ void (*callback)(struct afb_req req); /* callback function implementing the method */
+ const char *info; /* textual description of the method */
+};
+```
+
+For technical reasons, the enumeration **enum AFB_session_v1** is not exactly an
+enumeration but the wrapper of constant definitions that can be mixed using bitwise or
+(the C operator |).
+
+The constants that can bit mixed are:
+
+Constant name | Meaning
+-------------------------|-------------------------------------------------------------
+**AFB_SESSION_CREATE** | Equals to AFB_SESSION_LOA_EQ_0|AFB_SESSION_RENEW
+**AFB_SESSION_CLOSE** | Closes the session after the reply and set the LOA to 0
+**AFB_SESSION_RENEW** | Refreshes the token of authentification
+**AFB_SESSION_CHECK** | Just requires the token authentification
+**AFB_SESSION_LOA_LE_0** | Requires the current LOA to be lesser then or equal to 0
+**AFB_SESSION_LOA_LE_1** | Requires the current LOA to be lesser then or equal to 1
+**AFB_SESSION_LOA_LE_2** | Requires the current LOA to be lesser then or equal to 2
+**AFB_SESSION_LOA_LE_3** | Requires the current LOA to be lesser then or equal to 3
+**AFB_SESSION_LOA_GE_0** | Requires the current LOA to be greater then or equal to 0
+**AFB_SESSION_LOA_GE_1** | Requires the current LOA to be greater then or equal to 1
+**AFB_SESSION_LOA_GE_2** | Requires the current LOA to be greater then or equal to 2
+**AFB_SESSION_LOA_GE_3** | Requires the current LOA to be greater then or equal to 3
+**AFB_SESSION_LOA_EQ_0** | Requires the current LOA to be equal to 0
+**AFB_SESSION_LOA_EQ_1** | Requires the current LOA to be equal to 1
+**AFB_SESSION_LOA_EQ_2** | Requires the current LOA to be equal to 2
+**AFB_SESSION_LOA_EQ_3** | Requires the current LOA to be equal to 3
+
+If any of this flag is set, ***afb-daemon*** requires an authentication token
+as if **AFB_SESSION_CHECK** flag was also set.
+
+The special value **AFB_SESSION_NONE** is zero and can be used to bypass token check.
+
+> Note that **AFB_SESSION_CREATE** and **AFB_SESSION_CLOSE** might be removed in later versions.
+
+Sending messages to the log system
+----------------------------------
+
+Afb-daemon provides 4 levels of verbosity and 5 methods for logging messages.
+
+The verbosity is managed. Options allow the change the verbosity of ***afb-daemon***
+and the verbosity of the bindings can be set binding by binding.
+
+The methods for logging messages are defined as macros that test the
+verbosity level and that call the real logging function only if the
+message must be output. This avoid evaluation of arguments of the
+formatting messages if the message must not be output.
+
+### Verbs for logging messages
+
+The 5 logging methods are:
+
+Macro | Verbosity | Meaning | syslog level
+--------|:---------:|-----------------------------------|:-----------:
+ERROR | 0 | Error conditions | 3
+WARNING | 1 | Warning conditions | 4
+NOTICE | 1 | Normal but significant condition | 5
+INFO | 2 | Informational | 6
+DEBUG | 3 | Debug-level messages | 7
+
+You can note that the 2 methods **WARNING** and **NOTICE** have the same level
+of verbosity. But they don't have the same *syslog level*. It means that
+they are output with a different level on the logging system.
+
+All of these methods have the same signature:
+
+```C
+void ERROR(const struct afb_binding_interface *afbitf, const char *message, ...);
+```
+
+The first argument **afbitf** is the interface to afb daemon that the
+binding received at initialisation time when **afbBindingV1Register** is called.
+
+The second argument **message** is a formatting string compatible with printf/sprintf.
+
+The remaining arguments are arguments of the formating message like with printf.
+
+### Managing verbosity
+
+Depending on the level of verbosity, the messages are output or not.
+The following table explains what messages will be output depending
+ont the verbosity level.
+
+Level of verbosity | Outputed macro
+:-----------------:|--------------------------
+0 | ERROR
+1 | ERROR + WARNING + NOTICE
+2 | ERROR + WARNING + NOTICE + INFO
+3 | ERROR + WARNING + NOTICE + INFO + DEBUG
+
+### Output format and destination
+
+The syslog level is used for forging a prefix to the message.
+The prefixes are:
+
+syslog level | prefix
+:-----------:|---------------
+0 | <0> EMERGENCY
+1 | <1> ALERT
+2 | <2> CRITICAL
+3 | <3> ERROR
+4 | <4> WARNING
+5 | <5> NOTICE
+6 | <6> INFO
+7 | <7> DEBUG
+
+
+The message is pushed to standard error.
+The final destination of the message depends on how systemd service
+was configured through its variable **StandardError**. It can be
+journal, syslog or kmsg. (See man sd-daemon).
+
+Sending events
+--------------
+
+Specific documentation exists about [sending events](afb-events-guide.md).
+
+The binding *tic-tac-toe* broadcasts events when the board changes. This is done
+in the function ***changed***:
+
+```C
+/*
+ * signals a change of the board
+ */
+static void changed(struct board *board, const char *reason)
+{
+ ...
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ ...
+
+ afb_daemon_broadcast_event(afbitf->daemon, reason, description);
+}
+```
+
+The description of the changed board is pushed via the daemon interface.
+
+Within binding *tic-tac-toe*, *reason* indicates the origin of
+the change. In function **afb_daemon_broadcast_event** the second
+parameter is the name of broadcasted event. The third argument is the
+object that is transmitted with the event.
+
+Function **afb_daemon_broadcast_event** is defined here after:
+
+```C
+/*
+ * Broadcasts widely the event of 'name' with the data 'object'.
+ * 'object' can be NULL.
+ * 'daemon' MUST be the daemon given in interface when activating the binding.
+ *
+ * For convenience, the function calls 'json_object_put' for 'object'.
+ * Thus, in the case where 'object' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object);
+```
+
+> Be aware, as with reply functions **object** is automatically released using
+> **json_object_put** when using this function. Call **json_object_get** before
+> calling **afb_daemon_broadcast_event** to keep **object** available
+> after function returns.
+
+Event name received by listeners is prefixed with binding name.
+So when a change occurs after a move, the reason is **move** and every clients
+receive an event **tictactoe/move**.
+
+> Note that nothing is said about case sensitivity of event names.
+> However, the event is always prefixed with the name that the binding
+> declared, with the same case, followed with a slash /.
+> Thus it is safe to compare event using a case sensitive comparison.
+
+Writing a synchronous method implementation
+-----------------------------------------
+
+The method **tictactoe/board** is a synchronous implementation.
+Here is its listing:
+
+```C
+/*
+ * get the board
+ */
+static void board(struct afb_req req)
+{
+ struct board *board;
+ struct json_object *description;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'board' called for boardid %d", board->id);
+
+ /* describe the board */
+ description = describe(board);
+
+ /* send the board's description */
+ afb_req_success(req, description, NULL);
+}
+```
+
+This example shows many aspects of a synchronous
+method implementation. Let summarise it:
+
+1. The function **board_of_req** retrieves the context stored
+for the binding: the board.
+
+2. The macro **INFO** sends a message of kind *INFO*
+to the logging system. The global variable named **afbitf**
+used represents the interface to ***afb-daemon***.
+
+3. The function **describe** creates a json_object representing
+the board.
+
+4. The function **afb_req_success** sends the reply, attaching to
+it the object *description*.
+
+### The incoming request
+
+For any implementation, the request is received by a structure of type
+**struct afb_req**.
+
+> Note that this is a PLAIN structure, not a pointer to a structure.
+
+The definition of **struct afb_req** is:
+
+```C
+/*
+ * Describes the request by bindings from afb-daemon
+ */
+struct afb_req {
+ const struct afb_req_itf *itf; /* the interfacing functions */
+ void *closure; /* the closure for functions */
+};
+```
+
+It contains two pointers: first one *itf*, points to functions used
+to handle internal request. Second one *closure* point onto function closure.
+
+> The structure must never be used directly.
+> Instead developer should use the intended functions provided
+> by ***afb-daemon*** as described here after.
+
+*req* is used to get arguments of the request, to send
+answer, to store session data.
+
+This object and its interface is defined and documented
+in the file names *afb/afb-req-itf.h*
+
+The above example uses twice *req* object request.
+
+The first time, to retrieve the board attached to the session of the request.
+
+The second time, to send the reply: an object that describes the current board.
+
+### Associating a client context to a session
+
+When *tic-tac-toe* binding receives a request, it musts get
+the board describing the game associated to the session.
+
+For a binding, having data associated to a session is common.
+This data is called "binding context" for the session.
+Within *tic-tac-toe* binding the context is the board.
+
+Requests *afb_req* offer four functions for storing and retrieving session
+associated context.
+
+These functions are:
+
+- **afb_req_context_get**:
+ retrieves context data stored for current binding.
+
+- **afb_req_context_set**:
+ store context data of current binding.
+
+- **afb_req_context**:
+ if exist retrieves context data of current binding.
+ if context does not yet exist, creates a new context and store it.
+
+- **afb_req_context_clear**:
+ reset the stored context data.
+
+The binding *tictactoe* use a convenient function to retrieve
+its context: the board. This function is *board_of_req*:
+
+```C
+/*
+ * retrieves the board of the request
+ */
+static inline struct board *board_of_req(struct afb_req req)
+{
+ return afb_req_context(req, (void*)get_new_board, (void*)release_board);
+}
+```
+
+The function **afb_req_context** ensures an existing context
+for the session of the request.
+Its two last arguments are functions to allocate and free context.
+Note function type casts to avoid compilation warnings.
+
+Here is the definition of the function **afb_req_context**
+
+```C
+/*
+ * Gets the pointer stored by the binding for the session of 'req'.
+ * If the stored pointer is NULL, indicating that no pointer was
+ * already stored, afb_req_context creates a new context by calling
+ * the function 'create_context' and stores it with the freeing function
+ * 'free_context'.
+ */
+static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
+{
+ void *result = afb_req_context_get(req);
+ if (result == NULL) {
+ result = create_context();
+ afb_req_context_set(req, result, free_context);
+ }
+ return result;
+}
+```
+
+The second argument if the function that creates the context.
+For binding *tic-tac-toe* (function **get_new_board**).
+The function **get_new_board** creates a new board and set usage its count to 1.
+The boards are checking usage count to free resources when not used.
+
+The third argument is a function that frees context resources.
+For binding *tic-tac-toe* (function **release_board**).
+The function **release_board** decrease usage count of the board passed in
+argument. When usage count falls to zero, data board are freed.
+
+Definition of other functions dealing with contexts:
+
+```C
+/*
+ * Gets the pointer stored by the binding for the session of 'req'.
+ * When the binding has not yet recorded a pointer, NULL is returned.
+ */
+void *afb_req_context_get(struct afb_req req);
+
+/*
+ * Stores for the binding the pointer 'context' to the session of 'req'.
+ * The function 'free_context' will be called when the session is closed
+ * or if binding stores an other pointer.
+ */
+void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
+
+/*
+ * Frees the pointer stored by the binding for the session of 'req'
+ * and sets it to NULL.
+ *
+ * Shortcut for: afb_req_context_set(req, NULL, NULL)
+ */
+static inline void afb_req_context_clear(struct afb_req req)
+{
+ afb_req_context_set(req, NULL, NULL);
+}
+```
+
+### Sending reply to a request
+
+Two kinds of replies: successful or failure.
+
+> Sending a reply to a request MUST be done once and only once.
+
+It exists two functions for "success" replies: **afb_req_success** and **afb_req_success_f**.
+
+```C
+/*
+ * Sends a reply of kind success to the request 'req'.
+ * The status of the reply is automatically set to "success".
+ * Its send the object 'obj' (can be NULL) with an
+ * informationnal comment 'info (can also be NULL).
+ *
+ * For convenience, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_success(struct afb_req req, struct json_object *obj, const char *info);
+
+/*
+ * Same as 'afb_req_success' but the 'info' is a formatting
+ * string followed by arguments.
+ *
+ * For convenience, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...);
+```
+
+It exists two functions for "failure" replies: **afb_req_fail** and **afb_req_fail_f**.
+
+```C
+/*
+ * Sends a reply of kind failure to the request 'req'.
+ * The status of the reply is set to 'status' and an
+ * informational comment 'info' (can also be NULL) can be added.
+ *
+ * Note that calling afb_req_fail("success", info) is equivalent
+ * to call afb_req_success(NULL, info). Thus even if possible it
+ * is strongly recommended to NEVER use "success" for status.
+ *
+ * For convenience, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_fail(struct afb_req req, const char *status, const char *info);
+
+/*
+ * Same as 'afb_req_fail' but the 'info' is a formatting
+ * string followed by arguments.
+ *
+ * For convenience, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...);
+```
+
+> For convenience, these functions automatically call **json_object_put** to release **obj**.
+> Because **obj** usage count is null after being passed to a reply function, it SHOULD not be used anymore.
+> If exceptionally **obj** needs to remain usable after reply function then using **json_object_get** on **obj**
+> to increase usage count and cancels the effect the **json_object_put** is possible.
+
+Getting argument of invocation
+------------------------------
+
+Many methods expect arguments. Afb-daemon's bindings
+retrieve arguments by name and not by position.
+
+Arguments are passed by requests through either HTTP
+or WebSockets.
+
+For example, the method **join** of binding **tic-tac-toe**
+expects one argument: the *boardid* to join. Here is an extract:
+
+```C
+/*
+ * Join a board
+ */
+static void join(struct afb_req req)
+{
+ struct board *board, *new_board;
+ const char *id;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'join' called for boardid %d", board->id);
+
+ /* retrieves the argument */
+ id = afb_req_value(req, "boardid");
+ if (id == NULL)
+ goto bad_request;
+ ...
+```
+
+The function **afb_req_value** searches in the request *req*
+for argument name passed in the second argument. When argument name
+is not passed, **afb_req_value** returns NULL.
+
+> The search is case sensitive and *boardid* is not equivalent to *BoardId*.
+> Nevertheless having argument names that only differ by name case is not a good idea.
+
+### Basic functions for querying arguments
+
+The function **afb_req_value** is defined here after:
+
+```C
+/*
+ * Gets from the request 'req' the string value of the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name'.
+ * Returns the value of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).value
+ */
+static inline const char *afb_req_value(struct afb_req req, const char *name)
+{
+ return afb_req_get(req, name).value;
+}
+```
+
+It is defined as a shortcut to call the function **afb_req_get**.
+That function is defined here after:
+
+```C
+/*
+ * Gets from the request 'req' the argument of 'name'.
+ * Returns a PLAIN structure of type 'struct afb_arg'.
+ * When the argument of 'name' is not found, all fields of result are set to NULL.
+ * When the argument of 'name' is found, the fields are filled,
+ * in particular, the field 'result.name' is set to 'name'.
+ *
+ * There is a special name value: the empty string.
+ * The argument of name "" is defined only if the request was made using
+ * an HTTP POST of Content-Type "application/json". In that case, the
+ * argument of name "" receives the value of the body of the HTTP request.
+ */
+struct afb_arg afb_req_get(struct afb_req req, const char *name);
+```
+
+That function takes 2 parameters: the request and the name
+of the argument to retrieve. It returns a PLAIN structure of
+type **struct afb_arg**.
+
+There is a special name that is defined when the request is
+of type HTTP/POST with a Content-Type being application/json.
+This name is **""** (the empty string). In that case, the value
+of this argument of empty name is the string received as a body
+of the post and is supposed to be a JSON string.
+
+The definition of **struct afb_arg** is:
+
+```C
+/*
+ * Describes an argument (or parameter) of a request
+ */
+struct afb_arg {
+ const char *name; /* name of the argument or NULL if invalid */
+ const char *value; /* string representation of the value of the argument */
+ /* original filename of the argument if path != NULL */
+ const char *path; /* if not NULL, path of the received file for the argument */
+ /* when the request is finalized this file is removed */
+};
+```
+
+The structure returns the data arguments that are known for the
+request. This data include a field named **path**. This **path**
+can be accessed using the function **afb_req_path** defined here after:
+
+```C
+/*
+ * Gets from the request 'req' the path for file attached to the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name' or when there is no file.
+ * Returns the path of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).path
+ */
+static inline const char *afb_req_path(struct afb_req req, const char *name)
+{
+ return afb_req_get(req, name).path;
+}
+```
+
+The path is only defined for HTTP/POST requests that send file.
+
+### Arguments for received files
+
+As it is explained above, clients can send files using HTTP/POST requests.
+
+Received files are attached to "file" argument name. For example, the
+following HTTP fragment (from test/sample-post.html)
+will send an HTTP/POST request to the method
+**post/upload-image** with 2 arguments named *file* and
+*hidden*.
+
+```html
+<h2>Sample Post File</h2>
+<form enctype="multipart/form-data">
+ <input type="file" name="file" />
+ <input type="hidden" name="hidden" value="bollobollo" />
+ <br>
+ <button formmethod="POST" formaction="api/post/upload-image">Post File</button>
+</form>
+```
+
+Argument named **file** should have both its value and path defined.
+
+The value is the name of the file as it was set by the HTTP client.
+Generally it is the filename on client side.
+
+The path is the effective path of saved file on the temporary local storage
+area of the application. This is a randomly generated and unique filename.
+It is not linked with the original filename as used on client side.
+
+After success the binding can use the uploaded file directly from local storage path with no restriction:
+read, write, remove, copy, rename...
+Nevertheless when request reply is set and query terminated, the uploaded temporary file at
+path is destroyed.
+
+### Arguments as a JSON object
+
+Bindings may also request every arguments of a given call as one single object.
+This feature is provided by the function **afb_req_json** defined here after:
+
+```C
+/*
+ * Gets from the request 'req' the json object hashing the arguments.
+ * The returned object must not be released using 'json_object_put'.
+ */
+struct json_object *afb_req_json(struct afb_req req);
+```
+
+It returns a json object. This object depends on how the request was built:
+
+- For HTTP requests, this json object uses key names mapped on argument name.
+Values are either string for common arguments or object ie: { "file": "...", "path": "..." }
+
+- For WebSockets requests, returned directly the object as provided by the client.
+
+> In fact, for Websockets requests, the function **afb_req_value**
+> can be seen as a shortcut to
+> ***json_object_get_string(json_object_object_get(afb_req_json(req), name))***
+
+
+Writing an asynchronous method implementation
+-------------------------------------------
+
+The *tic-tac-toe* example allows two clients or more to share the same board.
+This is implemented by the method **join** that illustrated partly how to
+retrieve arguments.
+
+When two or more clients are sharing a same board, one of them can wait
+until the state of the board changes, but this could also be implemented using
+events because an event is generated each time the board changes.
+
+In this case, the reply to the wait is sent only when the board changes.
+See the diagram below:
+
+![tic-tac-toe_diagram][tic-tac-toe_diagram]
+
+Here, this is an invocation of the binding by an other client that
+unblock the suspended *wait* call.
+Nevertheless in most case this should be a timer, a hardware event, a sync with
+a concurrent process or thread, ...
+
+Common case of an asynchronous implementation.
+
+Here is the listing of the function **wait**:
+
+```C
+static void wait(struct afb_req req)
+{
+ struct board *board;
+ struct waiter *waiter;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'wait' called for boardid %d", board->id);
+
+ /* creates the waiter and enqueues it */
+ waiter = calloc(1, sizeof *waiter);
+ waiter->req = req;
+ waiter->next = board->waiters;
+ afb_req_addref(req);
+ board->waiters = waiter;
+}
+```
+
+After retrieving the board, the function adds a new waiter to
+waiters list and returns without setting a reply.
+
+Before returning, it increases **req** request's reference count using **afb_req_addref** function.
+
+> When a method returns without setting a reply,
+> it **MUST** increment request's reference count
+> using **afb_req_addref**. If unpredictable behaviour may pop up.
+
+Later, when a board changes, it calls *tic-tac-toe* **changed** function
+with reason of change in parameter.
+
+Here is the full listing of the function **changed**:
+
+```C
+/*
+ * signals a change of the board
+ */
+static void changed(struct board *board, const char *reason)
+{
+ struct waiter *waiter, *next;
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ waiter = board->waiters;
+ board->waiters = NULL;
+ while (waiter != NULL) {
+ next = waiter->next;
+ afb_req_success(waiter->req, json_object_get(description), reason);
+ afb_req_unref(waiter->req);
+ free(waiter);
+ waiter = next;
+ }
+
+ afb_event_sender_push(afb_daemon_get_event_sender(afbitf->daemon), reason, description);
+}
+```
+
+The list of waiters is walked and a reply is sent to each waiter.
+After sending the reply, the reference count of the request
+is decremented using **afb_req_unref** to allow resources to be freed.
+
+> The reference count **MUST** be decremented using **afb_req_unref** to free
+> resources and avoid memory leaks.
+> This usage count decrement should happen **AFTER** setting reply or
+> bad things may happen.
+
+Sending messages to the log system
+----------------------------------
+
+Afb-daemon provides 4 levels of verbosity and 5 methods for logging messages.
+
+The verbosity is managed. Options allow the change the verbosity of ***afb-daemon***
+and the verbosity of the bindings can be set binding by binding.
+
+The methods for logging messages are defined as macros that test the
+verbosity level and that call the real logging function only if the
+message must be output. This avoid evaluation of arguments of the
+formatting messages if the message must not be output.
+
+### Verbs for logging messages
+
+The 5 logging methods are:
+
+Macro | Verbosity | Meaning | syslog level
+--------|:---------:|-----------------------------------|:-----------:
+ERROR | 0 | Error conditions | 3
+WARNING | 1 | Warning conditions | 4
+NOTICE | 1 | Normal but significant condition | 5
+INFO | 2 | Informational | 6
+DEBUG | 3 | Debug-level messages | 7
+
+You can note that the 2 methods **WARNING** and **NOTICE** have the same level
+of verbosity. But they don't have the same *syslog level*. It means that
+they are output with a different level on the logging system.
+
+All of these methods have the same signature:
+
+```C
+void ERROR(const struct afb_binding_interface *afbitf, const char *message, ...);
+```
+
+The first argument **afbitf** is the interface to afb daemon that the
+binding received at initialisation time when **afbBindingV1Register** is called.
+
+The second argument **message** is a formatting string compatible with printf/sprintf.
+
+The remaining arguments are arguments of the formating message like with printf.
+
+### Managing verbosity
+
+Depending on the level of verbosity, the messages are output or not.
+The following table explains what messages will be output depending
+ont the verbosity level.
+
+Level of verbosity | Outputed macro
+:-----------------:|--------------------------
+0 | ERROR
+1 | ERROR + WARNING + NOTICE
+2 | ERROR + WARNING + NOTICE + INFO
+3 | ERROR + WARNING + NOTICE + INFO + DEBUG
+
+### Output format and destination
+
+The syslog level is used for forging a prefix to the message.
+The prefixes are:
+
+syslog level | prefix
+:-----------:|---------------
+0 | <0> EMERGENCY
+1 | <1> ALERT
+2 | <2> CRITICAL
+3 | <3> ERROR
+4 | <4> WARNING
+5 | <5> NOTICE
+6 | <6> INFO
+7 | <7> DEBUG
+
+
+The message is pushed to standard error.
+The final destination of the message depends on how systemd service
+was configured through its variable **StandardError**. It can be
+journal, syslog or kmsg. (See man sd-daemon).
+
+Sending events
+--------------
+
+Since version 0.5, bindings can broadcast events to any potential listener.
+As today only unattended events are supported. Targeted events are expected for
+next coming version.
+
+The binding *tic-tac-toe* broadcasts events when the board changes.
+This is done in the function **changed**:
+
+```C
+/*
+ * signals a change of the board
+ */
+static void changed(struct board *board, const char *reason)
+{
+ ...
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ ...
+
+ afb_daemon_broadcast_event(afbitf->daemon, reason, description);
+}
+```
+
+The description of the changed board is pushed via the daemon interface.
+
+Within binding *tic-tac-toe*, *reason* indicates the origin of
+the change. In function **afb_daemon_broadcast_event** the second
+parameter is the name of broadcasted event. The third argument is the
+object that is transmitted with the event.
+
+Function **afb_daemon_broadcast_event** is defined here after:
+
+```C
+/*
+ * Broadcasts widely the event of 'name' with the data 'object'.
+ * 'object' can be NULL.
+ * 'daemon' MUST be the daemon given in interface when activating the binding.
+ *
+ * For convenience, the function calls 'json_object_put' for 'object'.
+ * Thus, in the case where 'object' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object);
+```
+
+> Be aware, as with reply functions **object** is automatically released using
+> **json_object_put** when using this function. Call **json_object_get** before
+> calling **afb_daemon_broadcast_event** to keep **object** available
+> after function returns.
+
+Event name received by listeners is prefixed with binding name.
+So when a change occurs after a move, the reason is **move** and every clients
+receive an event **tictactoe/move**.
+
+> Note that nothing is said about case sensitivity of event names.
+> However, the event is always prefixed with the name that the binding
+> declared, with the same case, followed with a slash /.
+> Thus it is safe to compare event using a case sensitive comparison.
+
+How to build a binding
+---------------------
+
+Afb-daemon provides a *pkg-config* configuration file that can be
+queried by providing ***afb-daemon*** in command line arguments.
+This configuration file provides data that should be used
+for bindings compilation. Examples:
+
+```bash
+$ pkg-config --cflags afb-daemon
+$ pkg-config --libs afb-daemon
+```
+
+### Example for cmake meta build system
+
+This example is the extract for building the binding *afm-main* using *CMAKE*.
+
+```cmake
+pkg_check_modules(afb afb-daemon)
+if(afb_FOUND)
+ message(STATUS "Creation afm-main-binding for AFB-DAEMON")
+ add_library(afm-main-binding MODULE afm-main-binding.c)
+ target_compile_options(afm-main-binding PRIVATE ${afb_CFLAGS})
+ target_include_directories(afm-main-binding PRIVATE ${afb_INCLUDE_DIRS})
+ target_link_libraries(afm-main-binding utils ${afb_LIBRARIES})
+ set_target_properties(afm-main-binding PROPERTIES
+ PREFIX ""
+ LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-binding.export-map"
+ )
+ install(TARGETS afm-main-binding LIBRARY DESTINATION ${binding_dir})
+else()
+ message(STATUS "Not creating the binding for AFB-DAEMON")
+endif()
+```
+
+Let now describe some of these lines.
+
+```cmake
+pkg_check_modules(afb afb-daemon)
+```
+
+This first lines searches to the *pkg-config* configuration file for
+**afb-daemon**. Resulting data are stored in the following variables:
+
+Variable | Meaning
+------------------|------------------------------------------------
+afb_FOUND | Set to 1 if afb-daemon binding development files exist
+afb_LIBRARIES | Only the libraries (w/o the '-l') for compiling afb-daemon bindings
+afb_LIBRARY_DIRS | The paths of the libraries (w/o the '-L') for compiling afb-daemon bindings
+afb_LDFLAGS | All required linker flags for compiling afb-daemon bindings
+afb_INCLUDE_DIRS | The '-I' preprocessor flags (w/o the '-I') for compiling afb-daemon bindings
+afb_CFLAGS | All required cflags for compiling afb-daemon bindings
+
+If development files are found, the binding can be added to the set of
+target to build.
+
+```cmake
+add_library(afm-main-binding MODULE afm-main-binding.c)
+```
+
+This line asks to create a shared library having a single
+source file named afm-main-binding.c to be compiled.
+The default name of the created shared object is
+**libafm-main-binding.so**.
+
+```cmake
+set_target_properties(afm-main-binding PROPERTIES
+ PREFIX ""
+ LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-binding.export-map"
+)
+```
+
+This lines are doing two things:
+
+1. It renames the built library from **libafm-main-binding.so** to **afm-main-binding.so**
+by removing the implicitly added prefix *lib*. This step is not mandatory
+because afb-daemon doesn't check names of files at load time.
+The only filename convention used by afb-daemon relates to **.so** termination.
+*.so pattern is used when afb-daemon automatically discovers binding from a directory hierarchy.
+
+2. It applies a version script at link time to only export the reserved name
+**afbBindingV1Register** for registration entry point. By default, when building
+a shared library linker exports all the public symbols (C functions that are not **static**).
+
+Next line are:
+
+```cmake
+target_include_directories(afm-main-binding PRIVATE ${afb_INCLUDE_DIRS})
+target_link_libraries(afm-main-binding utils ${afb_LIBRARIES})
+```
+
+As you can see it uses the variables computed by ***pkg_check_modules(afb afb-daemon)***
+to configure the compiler and the linker.
+
+### Exporting the function afbBindingV1Register
+
+The function **afbBindingV1Register** MUST be exported. This can be achieved
+using a version script at link time. Here after is a version script used for
+*tic-tac-toe* (bindings/samples/export.map).
+
+ { global: afbBindingV1Register; local: *; };
+
+This sample [version script](https://sourceware.org/binutils/docs-2.26/ld/VERSION.html#VERSION)
+exports as global the symbol *afbBindingV1Register* and hides any
+other symbols.
+
+This version script is added to the link options using the
+option **--version-script=export.map** is given directly to the
+linker or using the option **-Wl,--version-script=export.map**
+when the option is given to the C compiler.
+
+### Building within yocto
+
+Adding a dependency to afb-daemon is enough. See below:
+
+ DEPENDS += " afb-daemon "
+
+
+[tic-tac-toe_diagram]: pictures/tic-tac-toe.svg
Code Review / src / app-framework-binder.git / blobdiff