--- /dev/null
+<html>
+<head>
+ <link rel="stylesheet" type="text/css" href="doc.css">
+ <meta charset="UTF-8">
+</head>
+<body>
+<a name="Frequently.Asked.Question.about.AFB-DAEMON"></a>
+<h1>Frequently Asked Question about AFB-DAEMON</h1>
+
+<pre><code>version: 1
+Date: 24 mai 2016
+Author: José Bollo
+</code></pre>
+
+<p><ul>
+ <li><a href="#Frequently.Asked.Question.about.AFB-DAEMON">Frequently Asked Question about AFB-DAEMON</a></li>
+</ul></p>
+</body>
+</html>
--- /dev/null
+Frequently Asked Question about AFB-DAEMON
+==========================================
+ version: 1
+ Date: 24 mai 2016
+ Author: José Bollo
+
+TABLE-OF-CONTENT-HERE
+
+
--- /dev/null
+<html>
+<head>
+ <link rel="stylesheet" type="text/css" href="doc.css">
+ <meta charset="UTF-8">
+</head>
+<body>
+<a name="Inititial.Build"></a>
+<h3>Inititial Build</h3>
+
+<p>mkdir build
+cd build
+cmake ..</p>
+
+<a name="Netbeans"></a>
+<h3>Netbeans</h3>
+
+<a name="Copy.nbprojet.at.project.base"></a>
+<h1>Copy nbprojet at project base</h1>
+
+<p>cp -r doc/nbproject.template ./nbproject</p>
+</body>
+</html>
--- /dev/null
+<html>
+<head>
+ <link rel="stylesheet" type="text/css" href="doc.css">
+ <meta charset="UTF-8">
+</head>
+<body>
+<a name="Vocabulary.for.AFB-DAEMON"></a>
+<h1>Vocabulary for AFB-DAEMON</h1>
+
+<pre><code>version: 1
+Date: 24 mai 2016
+Author: José Bollo
+</code></pre>
+
+<p><ul>
+ <li><a href="#Vocabulary.for.AFB-DAEMON">Vocabulary for AFB-DAEMON</a>
+ <ul>
+ <li><a href="#Authentification">Authentification</a></li>
+ <li><a href="#Context">Context</a></li>
+ <li><a href="#Level.of.authorisation..LOA.">Level of authorisation (LOA)</a></li>
+ <li><a href="#Plugin">Plugin</a></li>
+ <li><a href="#Request">Request</a></li>
+ <li><a href="#Reply.Response">Reply/Response</a></li>
+ <li><a href="#Service">Service</a></li>
+ <li><a href="#Session">Session</a></li>
+ <li><a href="#Token">Token</a></li>
+ <li><a href="#UUID">UUID</a></li>
+ <li><a href="#x-afb-token">x-afb-token</a></li>
+ <li><a href="#x-afb-uuid">x-afb-uuid</a></li>
+ </ul>
+ </li>
+</ul></p>
+
+<a name="Authentification"></a>
+<h2>Authentification</h2>
+
+<a name="Context"></a>
+<h2>Context</h2>
+
+<a name="Level.of.authorisation..LOA."></a>
+<h2>Level of authorisation (LOA)</h2>
+
+<a name="Plugin"></a>
+<h2>Plugin</h2>
+
+<a name="Request"></a>
+<h2>Request</h2>
+
+<a name="Reply.Response"></a>
+<h2>Reply/Response</h2>
+
+<a name="Service"></a>
+<h2>Service</h2>
+
+<a name="Session"></a>
+<h2>Session</h2>
+
+<p>A session records data as</p>
+
+<a name="Token"></a>
+<h2>Token</h2>
+
+<a name="UUID"></a>
+<h2>UUID</h2>
+
+<p>It stand for Universal Unic IDentifier.</p>
+
+<p>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.</p>
+
+<a name="x-afb-token"></a>
+<h2>x-afb-token</h2>
+
+<a name="x-afb-uuid"></a>
+<h2>x-afb-uuid</h2>
+</body>
+</html>
--- /dev/null
+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
--- /dev/null
+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;
+}
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="205.71426"
+ height="197.14285"
+ id="svg4199"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="triskel_iot_bzh.svg">
+ <defs
+ id="defs4201">
+ <filter
+ color-interpolation-filters="sRGB"
+ id="filter4111"
+ inkscape:label="Drop Shadow">
+ <feFlood
+ id="feFlood4113"
+ flood-opacity="0.475"
+ flood-color="rgb(0,0,0)"
+ result="flood" />
+ <feComposite
+ id="feComposite4115"
+ in2="SourceGraphic"
+ in="flood"
+ operator="in"
+ result="composite1" />
+ <feGaussianBlur
+ id="feGaussianBlur4117"
+ stdDeviation="5"
+ result="blur" />
+ <feOffset
+ id="feOffset4119"
+ dx="8"
+ dy="8"
+ result="offset" />
+ <feComposite
+ id="feComposite4121"
+ in2="offset"
+ in="SourceGraphic"
+ operator="over"
+ result="composite2" />
+ </filter>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="0.35"
+ inkscape:cx="46.428557"
+ inkscape:cy="178.57144"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ fit-margin-top="0"
+ fit-margin-left="0"
+ fit-margin-right="0"
+ fit-margin-bottom="0"
+ inkscape:window-width="500"
+ inkscape:window-height="435"
+ inkscape:window-x="1087"
+ inkscape:window-y="400"
+ inkscape:window-maximized="0" />
+ <metadata
+ id="metadata4204">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-328.57144,-513.79077)">
+ <path
+ id="path3415-4-2-2-5-0-3-7-4-4-1-9"
+ style="fill:#5a2ca0;display:inline;filter:url(#filter4111)"
+ d="m 470.88567,595.30412 c 28.21686,16.29102 28.75566,58.73778 0.99693,78.5383 -7.67688,5.47598 -8.77935,4.91028 -1.99529,-1.0238 17.47377,-15.28453 17.98492,-42.17774 1.08522,-57.09785 l -3.91266,-3.45435 0.72312,-3.71053 c 0.39771,-2.04076 0.5997,-5.73115 0.44885,-8.20083 -0.33876,-5.54623 0.15803,-6.49185 2.65383,-5.05094 z m -64.76568,11.40332 c 7.06047,-7.74198 18.64659,-14.16089 29.04027,-16.08874 l 6.87489,-1.27521 0.87404,2.89709 c 0.4807,1.59343 0.67439,5.2245 0.43037,8.06906 l -0.44364,5.17195 -6.13887,1.6918 c -10.91241,3.00731 -20.4022,10.85909 -25.4533,21.05979 l -2.41633,4.87984 -2.74281,-0.41238 c -5.14252,-0.77316 -12.72985,-3.97645 -12.79123,-5.40033 -0.092,-2.13451 8.34659,-15.74625 12.76661,-20.59287 z m 33.20546,36.39493 c -28.21687,16.291 -65.24624,-4.46574 -68.51461,-38.40577 -0.9039,-9.38637 0.13723,-10.0583 1.88428,-1.21608 4.49989,22.77499 27.53453,36.66428 48.90556,29.48876 l 4.94788,-1.66128 2.85184,2.48149 c 1.56852,1.36481 4.66349,3.38493 6.87772,4.48914 4.97257,2.47973 5.54308,3.38282 3.04733,4.82374 z m 22.50729,-61.7904 c 3.17451,9.98554 2.94038,23.2289 -0.58688,33.194 l -2.33309,6.59143 -2.94597,-0.69161 c -1.6203,-0.38041 -4.86173,-2.02821 -7.2032,-3.6618 l -4.25721,-2.97018 1.60429,-6.16234 c 2.85178,-10.95404 0.79685,-23.09834 -5.51167,-32.57308 l -3.01788,-4.53253 1.72854,-2.16916 c 3.24083,-4.06698 9.80863,-9.03614 11.07242,-8.37738 1.89457,0.98756 9.46336,15.1015 11.45065,21.35265 z m -48.80223,10.31438 c 0,-32.58202 36.49058,-54.27202 67.51771,-40.13251 8.58077,3.9104 8.6421,5.148 0.11108,2.23988 -21.97368,-7.49048 -45.51946,5.51348 -49.99082,27.6091 l -1.03521,5.11562 -3.57498,1.22902 c -1.96621,0.67596 -5.26316,2.34622 -7.32655,3.71171 -4.63379,3.06649 -5.70115,3.10904 -5.70115,0.22718 z m 42.25842,50.3871 c -10.23499,-2.24356 -21.58699,-9.06801 -28.45341,-17.10525 l -4.5418,-5.31622 2.07194,-2.20549 c 1.13957,-1.21302 4.18733,-3.19628 6.77282,-4.40726 l 4.70085,-2.20176 4.53458,4.47053 c 8.06061,7.94674 19.60535,12.23927 30.96496,11.51329 l 5.43422,-0.34731 1.01427,2.58154 c 1.90169,4.84014 2.92124,13.01261 1.71883,13.77769 -1.80254,1.14695 -17.80995,0.64475 -24.21726,-0.75976 z"
+ inkscape:connector-curvature="0"
+ inkscape:export-filename="/home/sdx/Pictures/Logo/triskel_iot_bzh_300dpi.png"
+ inkscape:export-xdpi="300"
+ inkscape:export-ydpi="300" />
+ <rect
+ style="fill:none;stroke:none;display:inline"
+ id="rect4179"
+ width="205.71426"
+ height="197.14285"
+ x="328.57144"
+ y="513.79077"
+ inkscape:export-filename="/home/sdx/Pictures/Logo/triskel_iot_bzh_300dpi.png"
+ inkscape:export-xdpi="300"
+ inkscape:export-ydpi="300" />
+ </g>
+</svg>
--- /dev/null
+#!/bin/sh
+
+subst() {
+ awk -v pat="$1" -v rep="$(sed 's:\\:\\\\:g' $2)" '{gsub(pat,rep);gsub(pat,"\\&");print}'
+}
+
+main='<html>
+<head>
+ <link rel="stylesheet" type="text/css" href="doc.css">
+ <meta charset="UTF-8">
+</head>
+<body>
+GENERATED-MARKDOWN-HERE
+</body>
+</html>'
+
+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
+
--- /dev/null
+<html>
+<head>
+ <link rel="stylesheet" type="text/css" href="doc.css">
+ <meta charset="UTF-8">
+</head>
+<body>
+<a name="HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON"></a>
+<h1>HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
+
+<pre><code>version: 1
+Date: 24 mai 2016
+Author: José Bollo
+</code></pre>
+
+<p><ul>
+ <li><a href="#HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</a>
+ <ul>
+ <li><a href="#Summary">Summary</a>
+ <ul>
+ <li><a href="#Nature.of.a.plugin">Nature of a plugin</a></li>
+ <li><a href="#Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</a></li>
+ <li><a href="#Content.of.a.plugin">Content of a plugin</a>
+ <ul>
+ <li><a href="#The.name.of.the.plugin">The name of the plugin</a></li>
+ <li><a href="#Names.of.verbs">Names of verbs</a></li>
+ <li><a href="#The.initialisation.function">The initialisation function</a></li>
+ <li><a href="#Functions.implementing.verbs">Functions implementing verbs</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#The.Tic-Tac-Toe.example">The Tic-Tac-Toe example</a></li>
+ <li><a href="#Choosing.names">Choosing names</a>
+ <ul>
+ <li><a href="#Names.for.API..plugin.">Names for API (plugin)</a></li>
+ <li><a href="#Names.for.verbs">Names for verbs</a></li>
+ <li><a href="#Names.for.arguments">Names for arguments</a></li>
+ <li><a href="#Forging.names.widely.available">Forging names widely available</a></li>
+ </ul>
+ </li>
+ <li><a href="#Options.to.set.when.compiling.plugins">Options to set when compiling plugins</a></li>
+ <li><a href="#Header.files.to.include">Header files to include</a></li>
+ <li><a href="#Writing.a.synchronous.verb.implementation">Writing a synchronous verb implementation</a>
+ <ul>
+ <li><a href="#The.incoming.request">The incoming request</a></li>
+ <li><a href="#Associating.an.object.to.the.session.for.the.plugin">Associating an object to the session for the plugin</a></li>
+ <li><a href="#Sending.the.reply.to.a.request">Sending the reply to a request</a></li>
+ </ul>
+ </li>
+ <li><a href="#Getting.argument.of.invocation">Getting argument of invocation</a></li>
+ <li><a href="#How.to.build.a.plugin">How to build a plugin</a></li>
+ </ul>
+ </li>
+</ul></p>
+
+<a name="Summary"></a>
+<h2>Summary</h2>
+
+<p>The binder afb-daemon serves files through
+the HTTP protocol and offers access to API’s through
+HTTP or WebSocket protocol.</p>
+
+<p>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.</p>
+
+<p>Before going into details, through a tiny example,
+a short overview plugins basis is needed.</p>
+
+<a name="Nature.of.a.plugin"></a>
+<h3>Nature of a plugin</h3>
+
+<p>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.</p>
+
+<p>Technically, a plugin is not linked to any library of afb-daemon.</p>
+
+<a name="Live.cycle.of.a.plugin.within.afb-daemon"></a>
+<h3>Live cycle of a plugin within afb-daemon</h3>
+
+<p>The plugins are loaded and activated when afb-daemon starts.</p>
+
+<p>At start, the plugin initialise itself.
+If it fails to initialise then afb-daemon stops.</p>
+
+<p>Conversely, if it success to initialize, it must declare
+a name, that must be unique, and a list of API’s verbs.</p>
+
+<p>When initialized, the functions implementing the API’s verbs
+of the plugin are activated on call.</p>
+
+<p>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.</p>
+
+<a name="Content.of.a.plugin"></a>
+<h3>Content of a plugin</h3>
+
+<p>For afb-daemon, a plugin contains 2 different
+things: names and functions.</p>
+
+<p>There is two kind of names:
+ - the name of the plugin,
+ - the names of the verbs.</p>
+
+<p>There is two kind of functions:
+ - the initialisation function
+ - functions implementing verbs</p>
+
+<p>Afb-daemon translates the name of the method that is
+invoked to a pair of API and verb names. For example,
+the method named <strong>foo/bar</strong> translated to the API
+name <strong>foo</strong> and the verb name <strong>bar</strong>.
+To serve it, afb-daemon search the plugin that record
+the name <strong>foo</strong> and if it also recorded the verb <strong>bar</strong>,
+it calls the implementation function declared for this verb.</p>
+
+<p>Afb-daemon make no distinction between lower case
+and upper case when searching for a method.
+Thus, The names <strong>TicTacToe/Board</strong> and <strong>tictactoe/borad</strong>
+are equals.</p>
+
+<a name="The.name.of.the.plugin"></a>
+<h4>The name of the plugin</h4>
+
+<p>The name of the plugin is also known as the name
+of the API that defines the plugin.</p>
+
+<p>This name is also known as the prefix.</p>
+
+<p>The name of a plugin MUST be unique within afb-daemon.</p>
+
+<p>For example, when a client of afb-daemon
+calls a method named <strong>foo/bar</strong>. Afb-daemon
+extracts the prefix <strong>foo</strong> and the suffix <strong>bar</strong>.
+<strong>foo</strong> is the API name and must match a plugin name,
+the plugin that implements the verb <strong>bar</strong>.</p>
+
+<a name="Names.of.verbs"></a>
+<h4>Names of verbs</h4>
+
+<p>Each plugin exposes a set of verbs that can be called
+by client of afb-daemon.</p>
+
+<p>The name of a verb MUST be unique within a plugin.</p>
+
+<p>Plugins link verbs to functions that are called
+when clients emit requests for that verb.</p>
+
+<p>For example, when a client of afb-daemon
+calls a method named <strong>foo/bar</strong>.</p>
+
+<a name="The.initialisation.function"></a>
+<h4>The initialisation function</h4>
+
+<p>The initialisation function serves several purposes.</p>
+
+<ol>
+<li><p>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 <strong>pluginAfbV1Register</strong>. It identifies
+the first version of plugins.</p></li>
+<li><p>It allows the plugin to initialise itself.</p></li>
+<li><p>It serves to the plugin to declare names, descriptions,
+requirements and implmentations of the verbs that it exposes.</p></li>
+</ol>
+
+
+<a name="Functions.implementing.verbs"></a>
+<h4>Functions implementing verbs</h4>
+
+<p>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.</p>
+
+<p>An implementation function receives a request object that
+is used to get arguments of the request, to send
+answer, to store session data.</p>
+
+<p>A plugin MUST send an answer to the request.</p>
+
+<p>But it is not mandatory to send the answer
+before to return from the implementing function.
+This behaviour is important for implementing
+asynchronous actions.</p>
+
+<p>Implementation functions that always reply to the request
+before returning are named <em>synchronous implementations</em>.
+Those that don’t always reply to the request before
+returning are named <em>asynchronous implementations</em>.</p>
+
+<p>Asynchronous implementations typically initiate an
+asynchronous action and record to send the reply
+on completion of this action.</p>
+
+<a name="The.Tic-Tac-Toe.example"></a>
+<h2>The Tic-Tac-Toe example</h2>
+
+<p>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 <em>plugins/samples/tic-tac-toe.c</em>.</p>
+
+<p>This plugin is named <strong><em>tictactoe</em></strong>.</p>
+
+<a name="Choosing.names"></a>
+<h2>Choosing names</h2>
+
+<p>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.</p>
+
+<p>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.</p>
+
+<p>The names and strings used ALL are UTF-8 encoded.</p>
+
+<a name="Names.for.API..plugin."></a>
+<h3>Names for API (plugin)</h3>
+
+<p>The names of the API are checked.
+All characters are authorised except:</p>
+
+<ul>
+<li>the control characters (\u0000 .. \u001f)</li>
+<li>the characters of the set { ‘ ’, ‘“’, ‘#’, ‘%’, ‘&’,
+‘’‘, ’/‘, ’?‘, ’`‘, ’\x7f' }</li>
+</ul>
+
+
+<p>In other words the set of forbidden characters is
+{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027,
+ \u002f, \u003f, \u0060, \u007f }.</p>
+
+<p>Afb-daemon make no distinction between lower case
+and upper case when searching for an API by its name.</p>
+
+<a name="Names.for.verbs"></a>
+<h3>Names for verbs</h3>
+
+<p>The names of the verbs are not checked.</p>
+
+<p>However, the validity rules for verb’s names are the
+same as for API’s names except that the dot (.) character
+is forbidden.</p>
+
+<p>Afb-daemon make no distinction between lower case
+and upper case when searching for an API by its name.</p>
+
+<a name="Names.for.arguments"></a>
+<h3>Names for arguments</h3>
+
+<p>The names for arguments are not restricted and can be
+anything.</p>
+
+<p>The arguments are searched with the case sensitive
+string comparison. Thus the names “index” and “Index”
+are not the same.</p>
+
+<a name="Forging.names.widely.available"></a>
+<h3>Forging names widely available</h3>
+
+<p>The key names of javascript object can be almost
+anything using the arrayed notation:</p>
+
+<pre><code>object[key] = value
+</code></pre>
+
+<p>That is not the case with the dot notation:</p>
+
+<pre><code>object.key = value
+</code></pre>
+
+<p>Using the dot notation, the key must be a valid javascript
+identifier.</p>
+
+<p>For this reason, the chosen names should better be
+valid javascript identifier.</p>
+
+<p>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.</p>
+
+<a name="Options.to.set.when.compiling.plugins"></a>
+<h2>Options to set when compiling plugins</h2>
+
+<p>Afb-daemon provides a configuration file for <em>pkg-config</em>.
+Typing the command</p>
+
+<pre><code>pkg-config --cflags afb-daemon
+</code></pre>
+
+<p>will print the flags to use for compiling, like this:</p>
+
+<pre><code>$ pkg-config --cflags afb-daemon
+-I/opt/local/include -I/usr/include/json-c
+</code></pre>
+
+<p>For linking, you should use</p>
+
+<pre><code>$ pkg-config --libs afb-daemon
+-ljson-c
+</code></pre>
+
+<p>As you see, afb-daemon automatically includes dependency to json-c.
+This is done through the <strong>Requires</strong> keyword of pkg-config.</p>
+
+<p>If this behaviour is a problem, let us know.</p>
+
+<a name="Header.files.to.include"></a>
+<h2>Header files to include</h2>
+
+<p>The plugin <em>tictactoe</em> has the following lines for its includes:</p>
+
+<pre><code>#define _GNU_SOURCE
+#include <stdio.h>
+#include <string.h>
+#include <json-c/json.h>
+#include <afb/afb-plugin.h>
+</code></pre>
+
+<p>The header <em>afb/afb-plugin.h</em> includes all the features that a plugin
+needs except two foreign header that must be included by the plugin
+if it needs it:</p>
+
+<ul>
+<li><em>json-c/json.h</em>: this header must be include to handle json objects;</li>
+<li><em>systemd/sd-event.h</em>: this must be include to access the main loop;</li>
+<li><em>systemd/sd-bus.h</em>: this may be include to use dbus connections.</li>
+</ul>
+
+
+<p>The <em>tictactoe</em> plugin does not use systemd features so it is not included.</p>
+
+<p>When including <em>afb/afb-plugin.h</em>, the macro <strong>_GNU_SOURCE</strong> must be
+defined.</p>
+
+<a name="Writing.a.synchronous.verb.implementation"></a>
+<h2>Writing a synchronous verb implementation</h2>
+
+<p>The verb <strong>tictactoe/board</strong> is a synchronous implementation.
+Here is its listing:</p>
+
+<pre><code>/*
+ * 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);
+}
+</code></pre>
+
+<p>This examples show many aspects of writing a synchronous
+verb implementation.</p>
+
+<a name="The.incoming.request"></a>
+<h3>The incoming request</h3>
+
+<p>For any implementation, the request is received by a structure of type
+<strong>struct afb_req</strong>.</p>
+
+<p><strong><em>Important: note that this is a PLAIN structure, not a pointer to a structure.</em></strong></p>
+
+<p>This structure, here named <em>req</em>, is used</p>
+
+<p><em>req</em> is used to get arguments of the request, to send
+answer, to store session data.</p>
+
+<p>This object and its interface is defined and documented
+in the file names <em>afb/afb-req-itf.h</em></p>
+
+<p>The above example uses 2 times the request object <em>req</em>.</p>
+
+<p>The first time, it is used for retrieving the board attached to
+the session of the request.</p>
+
+<p>The second time, it is used to send the reply: an object that
+describes the current board.</p>
+
+<a name="Associating.an.object.to.the.session.for.the.plugin"></a>
+<h3>Associating an object to the session for the plugin</h3>
+
+<p>When the plugin <em>tic-tac-toe</em> receives a request, it musts regain
+the board that describes the game associated to the session.</p>
+
+<p>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 <em>tic-tac-toe</em>, the context is the board.</p>
+
+<p>The requests <em>afb_req</em> offer four functions for
+storing and retrieving the context associated to the session.</p>
+
+<p>These functions are:</p>
+
+<ul>
+<li><p><strong>afb_req_context_get</strong>:
+retrieves the context data stored for the plugin.</p></li>
+<li><p><strong>afb_req_context_set</strong>:
+store the context data of the plugin.</p></li>
+<li><p><strong>afb_req_context</strong>:
+retrieves the context data of the plugin,
+if needed, creates the context and store it.</p></li>
+<li><p><strong>afb_req_context_clear</strong>:
+reset the stored data.</p></li>
+</ul>
+
+
+<p>The plugin <em>tictactoe</em> use a convenient function to retrieve
+its context: the board. This function is <em>board_of_req</em>:</p>
+
+<pre><code>/*
+ * 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);
+}
+</code></pre>
+
+<p>This function is very simple because it merely wraps
+a call to the function <strong>afb_req_context</strong>, providing
+all needed arguments.
+The casts are required to avoid a warning when compiling.</p>
+
+<p>Here is the definition of the function <strong>afb_req_context</strong></p>
+
+<pre><code>/*
+ * 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;
+}
+</code></pre>
+
+<p>This powerful function ensures that the context exists and is
+stored for the session.</p>
+
+<p>The function <strong>get_new_board</strong> 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.</p>
+
+<p>The function <strong>release_board</strong></p>
+
+<a name="Sending.the.reply.to.a.request"></a>
+<h3>Sending the reply to a request</h3>
+
+<a name="Getting.argument.of.invocation"></a>
+<h2>Getting argument of invocation</h2>
+
+<a name="How.to.build.a.plugin"></a>
+<h2>How to build a plugin</h2>
+
+<p>Afb-daemon provides a The packaging of afb-daemon</p>
+</body>
+</html>
--- /dev/null
+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 <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:
+
+- *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
+
+
Code Review / src / app-framework-binder.git / commitdiff
