+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.