diff options
| author |   José Bollo <jose.bollo@iot.bzh> | 2016-05-24 23:49:18 +0200 |
|---|---|---|
| committer | José Bollo <jose.bollo@iot.bzh> | 2016-05-25 00:13:33 +0200 |
| commit | 302353aa3b90bf3b70d33f05e6c78754d2f1bc7a (patch) | |
| tree | 081da81f522a3bd27b41862b6c83f538d891c510 | |
| parent | 01740abeafa96e11103b1366ae0129d4e87281aa (diff) | |
begins the documentation
Change-Id: I560725dfa5dd7ab1ae5e91b45f5ba613c3a2c1de
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
| -rw-r--r-- | doc/FAQ.html | 19 | ||||
| -rw-r--r-- | doc/FAQ.md | 9 | ||||
| -rw-r--r-- | doc/README.html | 22 | ||||
| -rw-r--r-- | doc/afb-daemon-vocabulary.html | 77 | ||||
| -rw-r--r-- | doc/afb-daemon-vocabulary.md | 39 | ||||
| -rw-r--r-- | doc/doc.css | 15 | ||||
| -rw-r--r-- | doc/triskel_iot_bzh.svg | 110 | ||||
| -rwxr-xr-x | doc/updt.sh | 31 | ||||
| -rw-r--r-- | doc/writing-afb-plugins.html | 482 | ||||
| -rw-r--r-- | doc/writing-afb-plugins.md | 404 |
10 files changed, 1208 insertions, 0 deletions
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 @@ +<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> 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 @@ +<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> 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 @@ +<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> 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 @@ +<?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> 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='<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 + 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 @@ +<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> 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 <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 + + |
