From 302353aa3b90bf3b70d33f05e6c78754d2f1bc7a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Tue, 24 May 2016 23:49:18 +0200 Subject: [PATCH] begins the documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Change-Id: I560725dfa5dd7ab1ae5e91b45f5ba613c3a2c1de Signed-off-by: José Bollo --- doc/FAQ.html | 19 ++ doc/FAQ.md | 9 + doc/README.html | 22 ++ doc/afb-daemon-vocabulary.html | 77 +++++++ doc/afb-daemon-vocabulary.md | 39 ++++ doc/doc.css | 15 ++ doc/triskel_iot_bzh.svg | 110 ++++++++++ doc/updt.sh | 31 +++ doc/writing-afb-plugins.html | 482 +++++++++++++++++++++++++++++++++++++++++ doc/writing-afb-plugins.md | 404 ++++++++++++++++++++++++++++++++++ 10 files changed, 1208 insertions(+) create mode 100644 doc/FAQ.html create mode 100644 doc/FAQ.md create mode 100644 doc/README.html create mode 100644 doc/afb-daemon-vocabulary.html create mode 100644 doc/afb-daemon-vocabulary.md create mode 100644 doc/doc.css create mode 100644 doc/triskel_iot_bzh.svg create mode 100755 doc/updt.sh create mode 100644 doc/writing-afb-plugins.html create mode 100644 doc/writing-afb-plugins.md diff --git a/doc/FAQ.html b/doc/FAQ.html new file mode 100644 index 00000000..4ebefaa3 --- /dev/null +++ b/doc/FAQ.html @@ -0,0 +1,19 @@ + + + + + + + +

Frequently Asked Question about AFB-DAEMON

+ +
version: 1
+Date:    24 mai 2016
+Author:  José Bollo
+
+ +

+ + diff --git a/doc/FAQ.md b/doc/FAQ.md new file mode 100644 index 00000000..32ef2789 --- /dev/null +++ b/doc/FAQ.md @@ -0,0 +1,9 @@ +Frequently Asked Question about AFB-DAEMON +========================================== + version: 1 + Date: 24 mai 2016 + Author: José Bollo + +TABLE-OF-CONTENT-HERE + + diff --git a/doc/README.html b/doc/README.html new file mode 100644 index 00000000..0a7dffa8 --- /dev/null +++ b/doc/README.html @@ -0,0 +1,22 @@ + + + + + + + +

Inititial Build

+ +

mkdir build +cd build +cmake ..

+ + +

Netbeans

+ + +

Copy nbprojet at project base

+ +

cp -r doc/nbproject.template ./nbproject

+ + diff --git a/doc/afb-daemon-vocabulary.html b/doc/afb-daemon-vocabulary.html new file mode 100644 index 00000000..b398aa33 --- /dev/null +++ b/doc/afb-daemon-vocabulary.html @@ -0,0 +1,77 @@ + + + + + + + +

Vocabulary for AFB-DAEMON

+ +
version: 1
+Date:    24 mai 2016
+Author:  José Bollo
+
+ +

+ + +

Authentification

+ + +

Context

+ + +

Level of authorisation (LOA)

+ + +

Plugin

+ + +

Request

+ + +

Reply/Response

+ + +

Service

+ + +

Session

+ +

A session records data as

+ + +

Token

+ + +

UUID

+ +

It stand for Universal Unic IDentifier.

+ +

Its is designed to create identifier in a way that avoid has much as possible conflicts. +It means that if two differents instance create a UUID, the probability that they create the same UUID is very low, near to zero.

+ + +

x-afb-token

+ + +

x-afb-uuid

+ + diff --git a/doc/afb-daemon-vocabulary.md b/doc/afb-daemon-vocabulary.md new file mode 100644 index 00000000..7a4b6537 --- /dev/null +++ b/doc/afb-daemon-vocabulary.md @@ -0,0 +1,39 @@ +Vocabulary for AFB-DAEMON +========================= + version: 1 + Date: 24 mai 2016 + Author: José Bollo + +TABLE-OF-CONTENT-HERE + +## Authentification + +## Context + +## Level of authorisation (LOA) + +## Plugin + +## Request + +## Reply/Response + +## Service + +## Session + +A session records data as + +## Token + + +## UUID + +It stand for Universal Unic IDentifier. + +Its is designed to create identifier in a way that avoid has much as possible conflicts. +It means that if two differents instance create a UUID, the probability that they create the same UUID is very low, near to zero. + +## x-afb-token + +## x-afb-uuid diff --git a/doc/doc.css b/doc/doc.css new file mode 100644 index 00000000..c11082fd --- /dev/null +++ b/doc/doc.css @@ -0,0 +1,15 @@ +body { + background: #fff url(triskel_iot_bzh.svg) no-repeat fixed right top; + font-family: "Verdana"; + color: #000; +} + +h1, h2, h3 { color: #306; } + +pre { + border: medium dashed #306; + background: #ccc; + margin-left: 4em; + padding: 1em; +} + diff --git a/doc/triskel_iot_bzh.svg b/doc/triskel_iot_bzh.svg new file mode 100644 index 00000000..096f4244 --- /dev/null +++ b/doc/triskel_iot_bzh.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/updt.sh b/doc/updt.sh new file mode 100755 index 00000000..cd978e22 --- /dev/null +++ b/doc/updt.sh @@ -0,0 +1,31 @@ +#!/bin/sh + +subst() { + awk -v pat="$1" -v rep="$(sed 's:\\:\\\\:g' $2)" '{gsub(pat,rep);gsub(pat,"\\&");print}' +} + +main=' + + + + + +GENERATED-MARKDOWN-HERE + +' + +for x in *.md; do + t=$(git log -n 1 --format=%ct $x) + [[ -n "$t" ]] || t=$(stat -c %Y $x) + d=$(LANG= date -d @$t +"%d %B %Y") + sed -i "s/^\( Date: *\).*/\1$d/" $x + h=${x%%.md}.html + markdown -f toc,autolink $x > $h.toc.no + markdown -Tf toc,autolink $x > $h.toc.yes + head --bytes=-$(stat -c %s $h.toc.no) $h.toc.yes > $h.toc + echo "$main" | + subst GENERATED-MARKDOWN-HERE $h.toc.no | + subst TABLE-OF-CONTENT-HERE $h.toc > $h +# rm $h.toc* +done + diff --git a/doc/writing-afb-plugins.html b/doc/writing-afb-plugins.html new file mode 100644 index 00000000..5aeca0a5 --- /dev/null +++ b/doc/writing-afb-plugins.html @@ -0,0 +1,482 @@ + + + + + + + +

HOWTO WRITE a PLUGIN for AFB-DAEMON

+ +
version: 1
+Date:    24 mai 2016
+Author:  José Bollo
+
+ +

+ + +

Summary

+ +

The binder afb-daemon serves files through +the HTTP protocol and offers access to API’s through +HTTP or WebSocket protocol.

+ +

The plugins are used to add API’s to afb-daemon. +This part describes how to write a plugin for afb-daemon. +Excepting this summary, this part is intended to be read +by developpers.

+ +

Before going into details, through a tiny example, +a short overview plugins basis is needed.

+ + +

Nature of a plugin

+ +

A plugin is a separate piece of code made of a shared library. +The plugin is loaded and activated by afb-daemon when afb-daemon +starts.

+ +

Technically, a plugin is not linked to any library of afb-daemon.

+ + +

Live cycle of a plugin within afb-daemon

+ +

The plugins are loaded and activated when afb-daemon starts.

+ +

At start, the plugin initialise itself. +If it fails to initialise then afb-daemon stops.

+ +

Conversely, if it success to initialize, it must declare +a name, that must be unique, and a list of API’s verbs.

+ +

When initialized, the functions implementing the API’s verbs +of the plugin are activated on call.

+ +

At the end, nothing special is done by afb-daemon. +Consequently, developpers of plugins should use ‘atexit’ +or ‘on_exit’ during initialisation if they need to +perform specific actions when stopping.

+ + +

Content of a plugin

+ +

For afb-daemon, a plugin contains 2 different +things: names and functions.

+ +

There is two kind of names: + - the name of the plugin, + - the names of the verbs.

+ +

There is two kind of functions: + - the initialisation function + - functions implementing verbs

+ +

Afb-daemon translates the name of the method that is +invoked to a pair of API and verb names. For example, +the method named foo/bar translated to the API +name foo and the verb name bar. +To serve it, afb-daemon search the plugin that record +the name foo and if it also recorded the verb bar, +it calls the implementation function declared for this verb.

+ +

Afb-daemon make no distinction between lower case +and upper case when searching for a method. +Thus, The names TicTacToe/Board and tictactoe/borad +are equals.

+ + +

The name of the plugin

+ +

The name of the plugin is also known as the name +of the API that defines the plugin.

+ +

This name is also known as the prefix.

+ +

The name of a plugin MUST be unique within afb-daemon.

+ +

For example, when a client of afb-daemon +calls a method named foo/bar. Afb-daemon +extracts the prefix foo and the suffix bar. +foo is the API name and must match a plugin name, +the plugin that implements the verb bar.

+ + +

Names of verbs

+ +

Each plugin exposes a set of verbs that can be called +by client of afb-daemon.

+ +

The name of a verb MUST be unique within a plugin.

+ +

Plugins link verbs to functions that are called +when clients emit requests for that verb.

+ +

For example, when a client of afb-daemon +calls a method named foo/bar.

+ + +

The initialisation function

+ +

The initialisation function serves several purposes.

+ +
    +

  1. It allows afb-daemon to check the version +of the plugin using the name of the initialisation +functions that it found. Currently, the initialisation +function is named pluginAfbV1Register. It identifies +the first version of plugins.

    2. +

  2. It allows the plugin to initialise itself.

    3. +

  3. It serves to the plugin to declare names, descriptions, +requirements and implmentations of the verbs that it exposes.

    4. +
+ + + +

Functions implementing verbs

+ +

When a method is called, afb-daemon constructs a request +object and pass it to the implementation function for verb +within the plugin of the API.

+ +

An implementation function receives a request object that +is used to get arguments of the request, to send +answer, to store session data.

+ +

A plugin MUST send an answer to the request.

+ +

But it is not mandatory to send the answer +before to return from the implementing function. +This behaviour is important for implementing +asynchronous actions.

+ +

Implementation functions that always reply to the request +before returning are named synchronous implementations. +Those that don’t always reply to the request before +returning are named asynchronous implementations.

+ +

Asynchronous implementations typically initiate an +asynchronous action and record to send the reply +on completion of this action.

+ + +

The Tic-Tac-Toe example

+ +

This part explains how to write an afb-plugin. +For the sake of being practical we will use many +examples from the tic-tac-toe example. +This plugin example is in plugins/samples/tic-tac-toe.c.

+ +

This plugin is named tictactoe.

+ + +

Choosing names

+ +

The designer of a plugin must defines names for its plugin +(or its API) and for the verbs of its API. He also +must defines names for arguments given by name.

+ +

While forging names, the designer should take into account +the rules for making valid names and some rules that make +the names easy to use across plaforms.

+ +

The names and strings used ALL are UTF-8 encoded.

+ + +

Names for API (plugin)

+ +

The names of the API are checked. +All characters are authorised except:

+ + + + +

In other words the set of forbidden characters is +{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027, + \u002f, \u003f, \u0060, \u007f }.

+ +

Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name.

+ + +

Names for verbs

+ +

The names of the verbs are not checked.

+ +

However, the validity rules for verb’s names are the +same as for API’s names except that the dot (.) character +is forbidden.

+ +

Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name.

+ + +

Names for arguments

+ +

The names for arguments are not restricted and can be +anything.

+ +

The arguments are searched with the case sensitive +string comparison. Thus the names “index” and “Index” +are not the same.

+ + +

Forging names widely available

+ +

The key names of javascript object can be almost +anything using the arrayed notation:

+ +
object[key] = value
+
+ +

That is not the case with the dot notation:

+ +
object.key = value
+
+ +

Using the dot notation, the key must be a valid javascript +identifier.

+ +

For this reason, the chosen names should better be +valid javascript identifier.

+ +

It is also a good practice, even for arguments, to not +rely on the case sensitivity and to avoid the use of +names different only by the case.

+ + +

Options to set when compiling plugins

+ +

Afb-daemon provides a configuration file for pkg-config. +Typing the command

+ +
pkg-config --cflags afb-daemon
+
+ +

will print the flags to use for compiling, like this:

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

As you see, afb-daemon automatically includes dependency to json-c. +This is done through the Requires keyword of pkg-config.

+ +

If this behaviour is a problem, let us know.

+ + +

Header files to include

+ +

The plugin tictactoe has the following lines for its includes:

+ +
#define _GNU_SOURCE
+#include <stdio.h>
+#include <string.h>
+#include <json-c/json.h>
+#include <afb/afb-plugin.h>
+
+ +

The header afb/afb-plugin.h includes all the features that a plugin +needs except two foreign header that must be included by the plugin +if it needs it:

+ + + + +

The tictactoe plugin does not use systemd features so it is not included.

+ +

When including afb/afb-plugin.h, the macro _GNU_SOURCE must be +defined.

+ + +

Writing a synchronous verb implementation

+ +

The verb tictactoe/board is a synchronous implementation. +Here is its listing:

+ +
/*
+ * 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 examples show many aspects of writing a synchronous +verb implementation.

+ + +

The incoming request

+ +

For any implementation, the request is received by a structure of type +struct afb_req.

+ +

Important: note that this is a PLAIN structure, not a pointer to a structure.

+ +

This structure, here named req, is used

+ +

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 2 times the request object req.

+ +

The first time, it is used for retrieving the board attached to +the session of the request.

+ +

The second time, it is used to send the reply: an object that +describes the current board.

+ + +

Associating an object to the session for the plugin

+ +

When the plugin tic-tac-toe receives a request, it musts regain +the board that describes the game associated to the session.

+ +

For a plugin, having data associated to a session is a common case. +This data is called the context of the plugin for the session. +For the plugin tic-tac-toe, the context is the board.

+ +

The requests afb_req offer four functions for +storing and retrieving the context associated to the session.

+ +

These functions are:

+ + + + +

The plugin tictactoe use a convenient function to retrieve +its context: the board. This function is board_of_req:

+ +
/*
+ * 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);
+}
+
+ +

This function is very simple because it merely wraps +a call to the function afb_req_context, providing +all needed arguments. +The casts are required to avoid a warning when compiling.

+ +

Here is the definition of the function afb_req_context

+ +
/*
+ * Gets the pointer stored by the plugin 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;
+}
+
+ +

This powerful function ensures that the context exists and is +stored for the session.

+ +

The function get_new_board creates a new board and set its +count of use to 1. The boards are counting their count of use +to free there ressources when no more used.

+ +

The function release_board

+ + +

Sending the reply to a request

+ + +

Getting argument of invocation

+ + +

How to build a plugin

+ +

Afb-daemon provides a The packaging of afb-daemon

+ + diff --git a/doc/writing-afb-plugins.md b/doc/writing-afb-plugins.md new file mode 100644 index 00000000..f0e3a376 --- /dev/null +++ b/doc/writing-afb-plugins.md @@ -0,0 +1,404 @@ +HOWTO WRITE a PLUGIN for AFB-DAEMON +=================================== + version: 1 + Date: 24 mai 2016 + Author: José Bollo + +TABLE-OF-CONTENT-HERE + +Summary +------- + +The binder afb-daemon serves files through +the HTTP protocol and offers access to API's through +HTTP or WebSocket protocol. + +The plugins are used to add API's to afb-daemon. +This part describes how to write a plugin for afb-daemon. +Excepting this summary, this part is intended to be read +by developpers. + +Before going into details, through a tiny example, +a short overview plugins basis is needed. + +### Nature of a plugin + +A plugin is a separate piece of code made of a shared library. +The plugin is loaded and activated by afb-daemon when afb-daemon +starts. + +Technically, a plugin is not linked to any library of afb-daemon. + +### Live cycle of a plugin within afb-daemon + +The plugins are loaded and activated when afb-daemon starts. + +At start, the plugin initialise itself. +If it fails to initialise then afb-daemon stops. + +Conversely, if it success to initialize, it must declare +a name, that must be unique, and a list of API's verbs. + +When initialized, the functions implementing the API's verbs +of the plugin are activated on call. + +At the end, nothing special is done by afb-daemon. +Consequently, developpers of plugins should use 'atexit' +or 'on_exit' during initialisation if they need to +perform specific actions when stopping. + +### Content of a plugin + +For afb-daemon, a plugin contains 2 different +things: names and functions. + +There is two kind of names: + - the name of the plugin, + - the names of the verbs. + +There is two kind of functions: + - the initialisation function + - functions implementing verbs + +Afb-daemon translates the name of the method that is +invoked to a pair of API and verb names. For example, +the method named **foo/bar** translated to the API +name **foo** and the verb name **bar**. +To serve it, afb-daemon search the plugin that record +the name **foo** and if it also recorded the verb **bar**, +it calls the implementation function declared for this verb. + +Afb-daemon make no distinction between lower case +and upper case when searching for a method. +Thus, The names **TicTacToe/Board** and **tictactoe/borad** +are equals. + +#### The name of the plugin + +The name of the plugin is also known as the name +of the API that defines the plugin. + +This name is also known as the prefix. + +The name of a plugin MUST be unique within afb-daemon. + +For example, when a client of afb-daemon +calls a method named **foo/bar**. Afb-daemon +extracts the prefix **foo** and the suffix **bar**. +**foo** is the API name and must match a plugin name, +the plugin that implements the verb **bar**. + +#### Names of verbs + +Each plugin exposes a set of verbs that can be called +by client of afb-daemon. + +The name of a verb MUST be unique within a plugin. + +Plugins link verbs to functions that are called +when clients emit requests for that verb. + +For example, when a client of afb-daemon +calls a method named **foo/bar**. + +#### The initialisation function + +The initialisation function serves several purposes. + +1. It allows afb-daemon to check the version +of the plugin using the name of the initialisation +functions that it found. Currently, the initialisation +function is named **pluginAfbV1Register**. It identifies +the first version of plugins. + +2. It allows the plugin to initialise itself. + +3. It serves to the plugin to declare names, descriptions, +requirements and implmentations of the verbs that it exposes. + +#### Functions implementing verbs + +When a method is called, afb-daemon constructs a request +object and pass it to the implementation function for verb +within the plugin of the API. + +An implementation function receives a request object that +is used to get arguments of the request, to send +answer, to store session data. + +A plugin MUST send an answer to the request. + +But it is not mandatory to send the answer +before to return from the implementing function. +This behaviour is important for implementing +asynchronous actions. + +Implementation functions that always reply to the request +before returning are named *synchronous implementations*. +Those that don't always reply to the request before +returning are named *asynchronous implementations*. + +Asynchronous implementations typically initiate an +asynchronous action and record to send the reply +on completion of this action. + +The Tic-Tac-Toe example +----------------------- + +This part explains how to write an afb-plugin. +For the sake of being practical we will use many +examples from the tic-tac-toe example. +This plugin example is in *plugins/samples/tic-tac-toe.c*. + +This plugin is named ***tictactoe***. + +Choosing names +-------------- + +The designer of a plugin must defines names for its plugin +(or its API) and for the verbs of its API. He also +must defines names for arguments given by name. + +While forging names, the designer should take into account +the rules for making valid names and some rules that make +the names easy to use across plaforms. + +The names and strings used ALL are UTF-8 encoded. + +### Names for API (plugin) + +The names of the API 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 make no distinction between lower case +and upper case when searching for an API by its name. + +### Names for verbs + +The names of the verbs are not checked. + +However, the validity rules for verb's names are the +same as for API's names except that the dot (.) character +is forbidden. + +Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name. + +### Names for arguments + +The names for arguments are not restricted and can be +anything. + +The arguments are searched with the case sensitive +string comparison. Thus the names "index" and "Index" +are not the same. + +### Forging names widely available + +The key names of javascript object can be almost +anything using the arrayed notation: + + object[key] = value + +That is not the case with the dot notation: + + object.key = value + +Using the dot notation, the key must be a valid javascript +identifier. + +For this reason, the chosen names should better be +valid javascript identifier. + +It is also a good practice, even for arguments, to not +rely on the case sensitivity and to avoid the use of +names different only by the case. + +Options to set when compiling plugins +------------------------------------- + +Afb-daemon provides a configuration file for *pkg-config*. +Typing the command + + pkg-config --cflags afb-daemon + +will print the flags to use for compiling, like this: + + $ 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 + +As you see, afb-daemon automatically includes dependency to json-c. +This is done through the **Requires** keyword of pkg-config. + +If this behaviour is a problem, let us know. + +Header files to include +----------------------- + +The plugin *tictactoe* has the following lines for its includes: + + #define _GNU_SOURCE + #include + #include + #include + #include + +The header *afb/afb-plugin.h* includes all the features that a plugin +needs except two foreign header that must be included by the plugin +if it needs it: + +- *json-c/json.h*: this header must be include to handle json objects; +- *systemd/sd-event.h*: this must be include to access the main loop; +- *systemd/sd-bus.h*: this may be include to use dbus connections. + +The *tictactoe* plugin does not use systemd features so it is not included. + +When including *afb/afb-plugin.h*, the macro **_GNU_SOURCE** must be +defined. + +Writing a synchronous verb implementation +----------------------------------------- + +The verb **tictactoe/board** is a synchronous implementation. +Here is its listing: + + /* + * 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 examples show many aspects of writing a synchronous +verb implementation. + +### The incoming request + +For any implementation, the request is received by a structure of type +**struct afb_req**. + +***Important: note that this is a PLAIN structure, not a pointer to a structure.*** + +This structure, here named *req*, is used + +*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 2 times the request object *req*. + +The first time, it is used for retrieving the board attached to +the session of the request. + +The second time, it is used to send the reply: an object that +describes the current board. + +### Associating an object to the session for the plugin + +When the plugin *tic-tac-toe* receives a request, it musts regain +the board that describes the game associated to the session. + +For a plugin, having data associated to a session is a common case. +This data is called the context of the plugin for the session. +For the plugin *tic-tac-toe*, the context is the board. + +The requests *afb_req* offer four functions for +storing and retrieving the context associated to the session. + +These functions are: + +- **afb_req_context_get**: + retrieves the context data stored for the plugin. + +- **afb_req_context_set**: + store the context data of the plugin. + +- **afb_req_context**: + retrieves the context data of the plugin, + if needed, creates the context and store it. + +- **afb_req_context_clear**: + reset the stored data. + +The plugin *tictactoe* use a convenient function to retrieve +its context: the board. This function is *board_of_req*: + + /* + * 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); + } + +This function is very simple because it merely wraps +a call to the function **afb_req_context**, providing +all needed arguments. +The casts are required to avoid a warning when compiling. + +Here is the definition of the function **afb_req_context** + + /* + * Gets the pointer stored by the plugin 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; + } + +This powerful function ensures that the context exists and is +stored for the session. + +The function **get_new_board** creates a new board and set its +count of use to 1. The boards are counting their count of use +to free there ressources when no more used. + +The function **release_board** + +### Sending the reply to a request + +Getting argument of invocation +------------------------------ + +How to build a plugin +--------------------- + +Afb-daemon provides a The packaging of afb-daemon + + -- 2.16.6