add_compile_options(-Werror=maybe-uninitialized)
add_compile_options(-Werror=implicit-function-declaration)
add_compile_options(-ffunction-sections -fdata-sections)
-add_compile_options(-Wl,--as-needed -Wl,--gc-sections)
add_compile_options(-fPIC)
add_compile_options(-g)
ADD_SUBDIRECTORY(plugins)
############################################################
-# installs the pkgconfig file
+# installs the pkgconfig files
CONFIGURE_FILE(afb-daemon.pc.in afb-daemon.pc @ONLY)
+CONFIGURE_FILE(afb-wsc.pc.in afb-wsc.pc @ONLY)
INSTALL(FILES
${CMAKE_CURRENT_BINARY_DIR}/afb-daemon.pc
+ ${CMAKE_CURRENT_BINARY_DIR}/afb-wsc.pc
DESTINATION
${CMAKE_INSTALL_LIBDIR}/pkgconfig
)
--- /dev/null
+##
+## Copyright (C) 2016 "IoT.bzh"
+## Author: José Bollo <jose.bollo@iot.bzh>
+##
+## This file is part of afb-daemon project.
+##
+## Licensed under the Apache License, Version 2.0 (the "License");
+## you may not use this file except in compliance with the License.
+## You may obtain a copy of the License at
+##
+## http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+##
+
+includedir=@CMAKE_INSTALL_FULL_INCLUDEDIR@
+libdir=@CMAKE_INSTALL_FULL_LIBDIR@
+
+Name: @PROJECT_PRETTY_NAME@
+Description: @PROJECT_DESCRIPTION@
+Version: @PROJECT_VERSION@
+URL: @PROJECT_URL@
+
+Requires: json-c libsystemd
+Cflags: -I${includedir}
+Libs: -L${libdir} -lafbwsc
+
<h1>Frequently Asked Question about AFB-DAEMON</h1>
<pre><code>version: 1
-Date: 24 mai 2016
+Date: 27 mai 2016
Author: José Bollo
</code></pre>
Frequently Asked Question about AFB-DAEMON
==========================================
version: 1
- Date: 24 mai 2016
+ Date: 27 mai 2016
Author: José Bollo
TABLE-OF-CONTENT-HERE
<h1>Vocabulary for AFB-DAEMON</h1>
<pre><code>version: 1
-Date: 24 mai 2016
+Date: 27 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="#Event">Event</a></li>
+ <li><a href="#Level.of.assurance..LOA.">Level of assurance (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="#Session">Session</a></li>
<li><a href="#Token">Token</a></li>
<li><a href="#UUID">UUID</a></li>
+ <li><a href="#x-afb-reqid">x-afb-reqid</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="Event"></a>
+<h2>Event</h2>
-<a name="Context"></a>
-<h2>Context</h2>
+<p>Message with data propagated from the services to the client and not expecting
+any reply.</p>
-<a name="Level.of.authorisation..LOA."></a>
-<h2>Level of authorisation (LOA)</h2>
+<p>The current implementation allows to widely broadcast events to all clients.</p>
+
+<a name="Level.of.assurance..LOA."></a>
+<h2>Level of assurance (LOA)</h2>
+
+<p>This level that can be from 0 to 3 represent the level of
+assurance that the services can expect from the session.</p>
+
+<p>The exact definition of the meaning of this levels and of
+how to use it remains to be achived.</p>
<a name="Plugin"></a>
<h2>Plugin</h2>
+<p>A shared library object intended to be plug to an afb-daemon instance
+to implement an API.</p>
+
<a name="Request"></a>
<h2>Request</h2>
+<p>A request is an invocation by a client to a method of a plugin using a message
+transfered through some protocol: HTTP, WebSocket, DBUS… served by afb-daemon</p>
+
<a name="Reply.Response"></a>
<h2>Reply/Response</h2>
+<p>This is a message sent to client as the result of the request.</p>
+
<a name="Service"></a>
<h2>Service</h2>
+<p>Service are made of plugins runnning by their side on their binder.
+It can serve many client. Each one being attached to one session.</p>
+
+<p>The framework establishes the connection between the services and
+the clients. Using DBus currently.</p>
+
<a name="Session"></a>
<h2>Session</h2>
-<p>A session records data as</p>
+<p>A session is meant to be the unic context of an instance of client,
+identifying that instance across requests.</p>
+
+<p>Each session has an identifier. Session identifier generated by afb-daemon are UUIDs.</p>
+
+<p>Internally, afb-daemon offers a mechanism to attach data to sessions.
+When the session is closed or disappears, the data attached to that session
+are freed.</p>
<a name="Token"></a>
<h2>Token</h2>
+<p>The token is an identifier that the the client must give to be authentificated.</p>
+
+<p>At start, afb-daemon get an initial token. This initial token must be presented
+incoming client to be authentificated.</p>
+
+<p>A token is valid only for a period.</p>
+
+<p>The token must be renewed periodically. When the token is renewed, afb-daemon
+sends the new token to the client.</p>
+
+<p>Tokens generated by afb-daemon are UUIDs.</p>
+
<a name="UUID"></a>
<h2>UUID</h2>
<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-reqid"></a>
+<h2>x-afb-reqid</h2>
+
+<p>Argument name that can be used with HTTP request.
+When this argument is given, it is automatically added to the “request” object of the
+answer.</p>
+
<a name="x-afb-token"></a>
<h2>x-afb-token</h2>
+<p>Argument name for giving the token without ambiguity.
+You can also use the name <strong>token</strong> but it may conflicts with other arguments.</p>
+
<a name="x-afb-uuid"></a>
<h2>x-afb-uuid</h2>
+
+<p>Argument name for giving explicitely the session identifier without ambiguity.
+You can also use the name <strong>uuid</strong> but it may conflicts with other arguments.</p>
</body>
</html>
Vocabulary for AFB-DAEMON
=========================
version: 1
- Date: 24 mai 2016
+ Date: 27 mai 2016
Author: José Bollo
TABLE-OF-CONTENT-HERE
-## Authentification
+## Event
-## Context
+Message with data propagated from the services to the client and not expecting
+any reply.
-## Level of authorisation (LOA)
+The current implementation allows to widely broadcast events to all clients.
+
+## Level of assurance (LOA)
+
+This level that can be from 0 to 3 represent the level of
+assurance that the services can expect from the session.
+
+The exact definition of the meaning of this levels and of
+how to use it remains to be achived.
## Plugin
+A shared library object intended to be plug to an afb-daemon instance
+to implement an API.
+
## Request
+A request is an invocation by a client to a method of a plugin using a message
+transfered through some protocol: HTTP, WebSocket, DBUS... served by afb-daemon
+
## Reply/Response
+This is a message sent to client as the result of the request.
+
## Service
+Service are made of plugins runnning by their side on their binder.
+It can serve many client. Each one being attached to one session.
+
+The framework establishes the connection between the services and
+the clients. Using DBus currently.
+
## Session
-A session records data as
+A session is meant to be the unic context of an instance of client,
+identifying that instance across requests.
+
+Each session has an identifier. Session identifier generated by afb-daemon are UUIDs.
+
+Internally, afb-daemon offers a mechanism to attach data to sessions.
+When the session is closed or disappears, the data attached to that session
+are freed.
## Token
+The token is an identifier that the the client must give to be authentificated.
+
+At start, afb-daemon get an initial token. This initial token must be presented
+incoming client to be authentificated.
+
+A token is valid only for a period.
+
+The token must be renewed periodically. When the token is renewed, afb-daemon
+sends the new token to the client.
+
+Tokens generated by afb-daemon are UUIDs.
## UUID
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-reqid
+
+Argument name that can be used with HTTP request.
+When this argument is given, it is automatically added to the "request" object of the
+answer.
+
## x-afb-token
+Argument name for giving the token without ambiguity.
+You can also use the name **token** but it may conflicts with other arguments.
+
## x-afb-uuid
+
+Argument name for giving explicitely the session identifier without ambiguity.
+You can also use the name **uuid** but it may conflicts with other arguments.
+
--- /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: 27 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="#Kinds.of.plugins">Kinds of plugins</a>
+ <ul>
+ <li><a href="#Application.plugins">Application plugins</a></li>
+ <li><a href="#Service.plugins">Service plugins</a></li>
+ </ul>
+ </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="#Dependencies.when.compiling">Dependencies when compiling</a></li>
+ <li><a href="#Header.files.to.include">Header files to include</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="#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.a.context.to.the.session">Associating a context to the session</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>
+ <ul>
+ <li><a href="#Basic.functions.for.querying.arguments">Basic functions for querying arguments</a></li>
+ <li><a href="#Arguments.for.received.files">Arguments for received files</a></li>
+ <li><a href="#Arguments.as.a.JSON.object">Arguments as a JSON object</a></li>
+ </ul>
+ </li>
+ <li><a href="#Initialisation.of.the.plugin.and.declaration.of.verbs">Initialisation of the plugin and declaration of verbs</a></li>
+ <li><a href="#Sending.messages.to.the.log.system">Sending messages to the log system</a>
+ <ul>
+ <li><a href="#Verbs.for.logging.messages">Verbs for logging messages</a></li>
+ <li><a href="#Managing.verbosity">Managing verbosity</a></li>
+ <li><a href="#Output.format.and.destination">Output format and destination</a></li>
+ </ul>
+ </li>
+ <li><a href="#Sending.events">Sending events</a></li>
+ <li><a href="#Writing.an.asynchronous.verb.implementation">Writing an asynchronous verb implementation</a></li>
+ <li><a href="#How.to.build.a.plugin">How to build a plugin</a>
+ <ul>
+ <li><a href="#Example.for.cmake.meta.build.system">Example for cmake meta build system</a></li>
+ <li><a href="#Exporting.the.function.pluginAfbV1Register">Exporting the function pluginAfbV1Register</a></li>
+ <li><a href="#Building.within.yocto">Building within yocto</a></li>
+ </ul>
+ </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="Kinds.of.plugins"></a>
+<h3>Kinds of plugins</h3>
+
+<p>There is two kinds of plugins: application plugins and service
+plugins.</p>
+
+<a name="Application.plugins"></a>
+<h4>Application plugins</h4>
+
+<p>Application plugins are intended to be instanciated for each
+application: when an application using that plugin is started,
+its binder starts a new instance of the plugin.</p>
+
+<p>It means that the application plugins mainly have only one
+context to manage for one client.</p>
+
+<a name="Service.plugins"></a>
+<h4>Service plugins</h4>
+
+<p>Service plugins are intended to be instanciated only one time
+only and connected to many clients.</p>
+
+<p>So either it does not manage context at all or otherwise,
+if it manages context, it should be able to manage one context
+per client.</p>
+
+<p>In details, it may be useful to have service plugins at a user
+level.</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="Dependencies.when.compiling"></a>
+<h2>Dependencies when compiling</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
+because almost all plugin will use <strong>json-c</strong>.</p>
+
+<p>If this behaviour is a problem, let us know.</p>
+
+<p>Internally, afb-daemon uses <strong>libsystemd</strong> for its event loop
+and for its binding to D-Bus.
+Plugins developpers are encouraged to also use this library.
+But it is a matter of choice.
+Thus there is no dependency to <strong>libsystemd</strong>.</p>
+
+<blockquote><p>Afb-daemon provides no library for plugins.
+The functions that the plugin need to have are given
+to the plugin at runtime through pointer using read-only
+memory.</p></blockquote>
+
+<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="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="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. Let summarize it:</p>
+
+<ol>
+<li><p>The function <strong>board_of_req</strong> retrieves the context stored
+for the plugin: the board.</p></li>
+<li><p>The macro <strong>INFO</strong> sends a message of kind <em>INFO</em>
+to the logging system. The global variable named <strong>afbitf</strong>
+used represents the interface to afb-daemon.</p></li>
+<li><p>The function <strong>describe</strong> creates a json_object representing
+the board.</p></li>
+<li><p>The function <strong>afb_req_success</strong> sends the reply, attaching to
+it the object <em>description</em>.</p></li>
+</ol>
+
+
+<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>
+
+<blockquote><p>Note that this is a PLAIN structure, not a pointer to a structure.</p></blockquote>
+
+<p>The definition of <strong>struct afb_req</strong> is:</p>
+
+<pre><code>/*
+ * Describes the request by plugins from afb-daemon
+ */
+struct afb_req {
+ const struct afb_req_itf *itf; /* the interfacing functions */
+ void *closure; /* the closure for functions */
+};
+</code></pre>
+
+<p>It contains two pointers: one, <em>itf</em>, points to the functions needed
+to handle the internal request represented by the second pointer, <em>closure</em>.</p>
+
+<blockquote><p>The structure must never be used directly.
+Insted, use the intended functions provided
+by afb-daemon and described here.</p></blockquote>
+
+<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.a.context.to.the.session"></a>
+<h3>Associating a context to the session</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>The function <strong>afb_req_context</strong> ensure an existing context
+for the session of the request.
+Its two last arguments are functions. Here, 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>The second argument if the function that creates the context.
+For the plugin <em>tic-tac-toe</em> it is the function <strong>get_new_board</strong>.
+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 third argument if the function that frees the context.
+For the plugin <em>tic-tac-toe</em> it is the function <strong>release_board</strong>.
+The function <strong>release_board</strong> decrease the the count of use of
+the board given as argument. If the use count decrease to zero,
+the board data are freed.</p>
+
+<p>The definition of the other functions for dealing with contexts are:</p>
+
+<pre><code>/*
+ * Gets the pointer stored by the plugin for the session of 'req'.
+ * When the plugin has not yet recorded a pointer, NULL is returned.
+ */
+void *afb_req_context_get(struct afb_req req);
+
+/*
+ * Stores for the plugin the pointer 'context' to the session of 'req'.
+ * The function 'free_context' will be called when the session is closed
+ * or if plugin stores an other pointer.
+ */
+void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
+
+/*
+ * Frees the pointer stored by the plugin for the session of 'req'
+ * and sets it to NULL.
+ *
+ * Shortcut for: afb_req_context_set(req, NULL, NULL)
+ */
+static inline void afb_req_context_clear(struct afb_req req)
+{
+ afb_req_context_set(req, NULL, NULL);
+}
+</code></pre>
+
+<a name="Sending.the.reply.to.a.request"></a>
+<h3>Sending the reply to a request</h3>
+
+<p>Two kinds of replies can be made: successful replies and
+failure replies.</p>
+
+<blockquote><p>Sending a reply to a request must be done at most one time.</p></blockquote>
+
+<p>The two functions to send a reply of kind “success” are
+<strong>afb_req_success</strong> and <strong>afb_req_success_f</strong>.</p>
+
+<pre><code>/*
+ * Sends a reply of kind success to the request 'req'.
+ * The status of the reply is automatically set to "success".
+ * Its send the object 'obj' (can be NULL) with an
+ * informationnal comment 'info (can also be NULL).
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_success(struct afb_req req, struct json_object *obj, const char *info);
+
+/*
+ * Same as 'afb_req_success' but the 'info' is a formatting
+ * string followed by arguments.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...);
+</code></pre>
+
+<p>The two functions to send a reply of kind “failure” are
+<strong>afb_req_fail</strong> and <strong>afb_req_fail_f</strong>.</p>
+
+<pre><code>/*
+ * Sends a reply of kind failure to the request 'req'.
+ * The status of the reply is set to 'status' and an
+ * informationnal comment 'info' (can also be NULL) can be added.
+ *
+ * Note that calling afb_req_fail("success", info) is equivalent
+ * to call afb_req_success(NULL, info). Thus even if possible it
+ * is strongly recommanded to NEVER use "success" for status.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_fail(struct afb_req req, const char *status, const char *info);
+
+/*
+ * Same as 'afb_req_fail' but the 'info' is a formatting
+ * string followed by arguments.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...);
+</code></pre>
+
+<blockquote><p>For conveniency, these functions call <strong>json_object_put</strong> to release the object <strong>obj</strong>
+that they send. Then <strong>obj</strong> can not be used after calling one of these reply functions.
+When it is not the expected behaviour, calling the function <strong>json_object_get</strong> on the object <strong>obj</strong>
+before cancels the effect of <strong>json_object_put</strong>.</p></blockquote>
+
+<a name="Getting.argument.of.invocation"></a>
+<h2>Getting argument of invocation</h2>
+
+<p>Many verbs expect arguments. Afb-daemon let plugins
+retrieve their arguments by name not by position.</p>
+
+<p>Arguments are given by the requests either through HTTP
+or through WebSockets.</p>
+
+<p>For example, the verb <strong>join</strong> of the plugin <strong>tic-tac-toe</strong>
+expects one argument: the <em>boardid</em> to join. Here is an extract:</p>
+
+<pre><code>/*
+ * Join a board
+ */
+static void join(struct afb_req req)
+{
+ struct board *board, *new_board;
+ const char *id;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'join' called for boardid %d", board->id);
+
+ /* retrieves the argument */
+ id = afb_req_value(req, "boardid");
+ if (id == NULL)
+ goto bad_request;
+ ...
+</code></pre>
+
+<p>The function <strong>afb_req_value</strong> search in the request <em>req</em>
+for an argument whose name is given. When no argument of the
+given name was passed, <strong>afb_req_value</strong> returns NULL.</p>
+
+<blockquote><p>The search is case sensitive. So the name <em>boardid</em> is not the
+same name than <em>BoardId</em>. But this must not be assumed so two
+expected names of argument should not differ only by case.</p></blockquote>
+
+<a name="Basic.functions.for.querying.arguments"></a>
+<h3>Basic functions for querying arguments</h3>
+
+<p>The function <strong>afb_req_value</strong> is defined as below:</p>
+
+<pre><code>/*
+ * Gets from the request 'req' the string value of the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name'.
+ * Returns the value of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).value
+ */
+static inline const char *afb_req_value(struct afb_req req, const char *name)
+{
+ return afb_req_get(req, name).value;
+}
+</code></pre>
+
+<p>It is defined as a shortcut to call the function <strong>afb_req_get</strong>.
+That function is defined as below:</p>
+
+<pre><code>/*
+ * Gets from the request 'req' the argument of 'name'.
+ * Returns a PLAIN structure of type 'struct afb_arg'.
+ * When the argument of 'name' is not found, all fields of result are set to NULL.
+ * When the argument of 'name' is found, the fields are filled,
+ * in particular, the field 'result.name' is set to 'name'.
+ *
+ * There is a special name value: the empty string.
+ * The argument of name "" is defined only if the request was made using
+ * an HTTP POST of Content-Type "application/json". In that case, the
+ * argument of name "" receives the value of the body of the HTTP request.
+ */
+struct afb_arg afb_req_get(struct afb_req req, const char *name);
+</code></pre>
+
+<p>That function takes 2 parameters: the request and the name
+of the argument to retrieve. It returns a PLAIN structure of
+type <strong>struct afb_arg</strong>.</p>
+
+<p>There is a special name that is defined when the request is
+of type HTTP/POST with a Content-Type being application/json.
+This name is <strong>“”</strong> (the empty string). In that case, the value
+of this argument of empty name is the string received as a body
+of the post and is supposed to be a JSON string.</p>
+
+<p>The definition of <strong>struct afb_arg</strong> is:</p>
+
+<pre><code>/*
+ * Describes an argument (or parameter) of a request
+ */
+struct afb_arg {
+ const char *name; /* name of the argument or NULL if invalid */
+ const char *value; /* string representation of the value of the argument */
+ /* original filename of the argument if path != NULL */
+ const char *path; /* if not NULL, path of the received file for the argument */
+ /* when the request is finalized this file is removed */
+};
+</code></pre>
+
+<p>The structure returns the data arguments that are known for the
+request. This data include a field named <strong>path</strong>. This <strong>path</strong>
+can be accessed using the function <strong>afb_req_path</strong> defined as
+below:</p>
+
+<pre><code>/*
+ * Gets from the request 'req' the path for file attached to the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name' or when there is no file.
+ * Returns the path of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).path
+ */
+static inline const char *afb_req_path(struct afb_req req, const char *name)
+{
+ return afb_req_get(req, name).path;
+}
+</code></pre>
+
+<p>The path is only defined for HTTP/POST requests that send file.</p>
+
+<a name="Arguments.for.received.files"></a>
+<h3>Arguments for received files</h3>
+
+<p>As it is explained just above, clients can send files using
+HTTP/POST requests.</p>
+
+<p>Received files are attached to a arguments. For example, the
+following HTTP fragment (from test/sample-post.html)
+will send an HTTP/POST request to the method
+<strong>post/upload-image</strong> with 2 arguments named <em>file</em> and
+<em>hidden</em>.</p>
+
+<pre><code><h2>Sample Post File</h2>
+<form enctype="multipart/form-data">
+ <input type="file" name="file" />
+ <input type="hidden" name="hidden" value="bollobollo" />
+ <br>
+ <button formmethod="POST" formaction="api/post/upload-image">Post File</button>
+</form>
+</code></pre>
+
+<p>In that case, the argument named <strong>file</strong> has its value and its
+path defined and not NULL.</p>
+
+<p>The value is the name of the file as it was
+set by the HTTP client and is generally the filename on the
+client side.</p>
+
+<p>The path is the path of the file saved on the temporary local storage
+area of the application. This is a randomly generated and unic filename
+not linked in any way with the original filename on the client.</p>
+
+<p>The plugin can use the file at the given path the way that it wants:
+read, write, remove, copy, rename…
+But when the reply is sent and the query is terminated, the file at
+this path is destroyed if it still exist.</p>
+
+<a name="Arguments.as.a.JSON.object"></a>
+<h3>Arguments as a JSON object</h3>
+
+<p>Plugins can get all the arguments as one single object.
+This feature is provided by the function <strong>afb_req_json</strong>
+that is defined as below:</p>
+
+<pre><code>/*
+ * Gets from the request 'req' the json object hashing the arguments.
+ * The returned object must not be released using 'json_object_put'.
+ */
+struct json_object *afb_req_json(struct afb_req req);
+</code></pre>
+
+<p>It returns a json object. This object depends on how the request was
+made:</p>
+
+<ul>
+<li><p>For HTTP requests, this is an object whose keys are the names of the
+arguments and whose values are either a string for common arguments or
+an object like { “file”: “…”, “path”: “…” }</p></li>
+<li><p>For WebSockets requests, the returned object is the object
+given by the client transparently transported.</p></li>
+</ul>
+
+
+<blockquote><p>In fact, for Websockets requests, the function <strong>afb_req_value</strong>
+can be seen as a shortcut to
+<strong><em>json_object_get_string(json_object_object_get(afb_req_json(req), name))</em></strong></p></blockquote>
+
+<a name="Initialisation.of.the.plugin.and.declaration.of.verbs"></a>
+<h2>Initialisation of the plugin and declaration of verbs</h2>
+
+<p>To be active, the verbs of the plugin should be declared to
+afb-daemon. And even more, the plugin itself must be recorded.</p>
+
+<p>The mechanism for doing this is very simple: when afb-need starts,
+it loads the plugins that are listed in its argument or configuration.</p>
+
+<p>Loading a plugin follows the following steps:</p>
+
+<ol>
+<li><p>It loads the plugin using <em>dlopen</em>.</p></li>
+<li><p>It searchs for the symbol named <strong>pluginAfbV1Register</strong> using <em>dlsym</em>.
+This symbol is assumed to be the exported initialisation function of the plugin.</p></li>
+<li><p>It build an interface object for the plugin.</p></li>
+<li><p>It calls the found function <strong>pluginAfbV1Register</strong> and pass it the pointer
+to its interface.</p></li>
+<li><p>The function <strong>pluginAfbV1Register</strong> setup the plugin, initialize it.</p></li>
+<li><p>The function <strong>pluginAfbV1Register</strong> returns the pointer to a structure
+that describes the plugin: its version, its name (prefix or API name), and the
+list of its verbs.</p></li>
+<li><p>Afb-daemon checks that the returned version and name can be managed.
+If it can manage it, the plugin and its verbs are recorded and can be used
+when afb-daemon finishes it initialisation.</p></li>
+</ol>
+
+
+<p>Here is the listing of the function <strong>pluginAfbV1Register</strong> of the plugin
+<em>tic-tac-toe</em>:</p>
+
+<pre><code>/*
+ * activation function for registering the plugin called by afb-daemon
+ */
+const struct AFB_plugin *pluginAfbV1Register(const struct AFB_interface *itf)
+{
+ afbitf = itf; // records the interface for accessing afb-daemon
+ return &plugin_description; // returns the description of the plugin
+}
+</code></pre>
+
+<p>This is a very small function because the <em>tic-tac-toe</em> plugin doesn’t have initialisation step.
+It merely record the daemon’s interface and returns its descritption.</p>
+
+<p>The variable <strong>afbitf</strong> is a variable global to the plugin. It records the
+interface to afb-daemon and is used for logging and pushing events.
+Here is its declaration:</p>
+
+<pre><code>/*
+ * the interface to afb-daemon
+ */
+const struct AFB_interface *afbitf;
+</code></pre>
+
+<p>The description of the plugin is defined as below.</p>
+
+<pre><code>/*
+ * array of the verbs exported to afb-daemon
+ */
+static const struct AFB_verb_desc_v1 plugin_verbs[] = {
+ /* VERB'S NAME SESSION MANAGEMENT FUNCTION TO CALL SHORT DESCRIPTION */
+ { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" },
+ { .name= "play", .session= AFB_SESSION_NONE, .callback= play, .info= "Asks the server to play" },
+ { .name= "move", .session= AFB_SESSION_NONE, .callback= move, .info= "Tells the client move" },
+ { .name= "board", .session= AFB_SESSION_NONE, .callback= board, .info= "Get the current board" },
+ { .name= "level", .session= AFB_SESSION_NONE, .callback= level, .info= "Set the server level" },
+ { .name= "join", .session= AFB_SESSION_CHECK,.callback= join, .info= "Join a board" },
+ { .name= "undo", .session= AFB_SESSION_NONE, .callback= undo, .info= "Undo the last move" },
+ { .name= "wait", .session= AFB_SESSION_NONE, .callback= wait, .info= "Wait for a change" },
+ { .name= NULL } /* marker for end of the array */
+};
+
+/*
+ * description of the plugin for afb-daemon
+ */
+static const struct AFB_plugin plugin_description =
+{
+ /* description conforms to VERSION 1 */
+ .type= AFB_PLUGIN_VERSION_1,
+ .v1= { /* fills the v1 field of the union when AFB_PLUGIN_VERSION_1 */
+ .prefix= "tictactoe", /* the API name (or plugin name or prefix) */
+ .info= "Sample tac-tac-toe game", /* short description of of the plugin */
+ .verbs = plugin_verbs /* the array describing the verbs of the API */
+ }
+};
+</code></pre>
+
+<p>The structure <strong>plugin_description</strong> describes the plugin.
+It declares the type and version of the plugin, its name, a description
+and a list of its verbs.</p>
+
+<p>The list of verbs is an array of structures describing the verbs and terminated by a marker:
+a verb whose name is NULL.</p>
+
+<p>The description of the verbs for this version is made of 4 fields:</p>
+
+<ul>
+<li><p>the name of the verbs,</p></li>
+<li><p>the session management flags,</p></li>
+<li><p>the implementation function to be call for the verb,</p></li>
+<li><p>a short description.</p></li>
+</ul>
+
+
+<p>The structure describing verbs is defined as follows:</p>
+
+<pre><code>/*
+ * Description of one verb of the API provided by the plugin
+ * This enumeration is valid for plugins of type 1
+ */
+struct AFB_verb_desc_v1
+{
+ const char *name; /* name of the verb */
+ enum AFB_session_v1 session; /* authorisation and session requirements of the verb */
+ void (*callback)(struct afb_req req); /* callback function implementing the verb */
+ const char *info; /* textual description of the verb */
+};
+</code></pre>
+
+<p>For technical reasons, the enumeration <strong>enum AFB_session_v1</strong> is not exactly an
+enumeration but the wrapper of constant definitions that can be mixed using bitwise or
+(the C operator |).</p>
+
+<p>The constants that can bit mixed are:</p>
+
+<table>
+<thead>
+<tr>
+<th>Constant name </th>
+<th> Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>AFB_SESSION_CREATE</strong> </td>
+<td> Equals to AFB_SESSION_LOA_EQ_0|AFB_SESSION_RENEW</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_CLOSE</strong> </td>
+<td> Closes the session after the reply and set the LOA to 0</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_RENEW</strong> </td>
+<td> Refreshes the token of authentification</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_CHECK</strong> </td>
+<td> Just requires the token authentification</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_LE_0</strong> </td>
+<td> Requires the current LOA to be lesser then or equal to 0</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_LE_1</strong> </td>
+<td> Requires the current LOA to be lesser then or equal to 1</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_LE_2</strong> </td>
+<td> Requires the current LOA to be lesser then or equal to 2</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_LE_3</strong> </td>
+<td> Requires the current LOA to be lesser then or equal to 3</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_GE_0</strong> </td>
+<td> Requires the current LOA to be greater then or equal to 0</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_GE_1</strong> </td>
+<td> Requires the current LOA to be greater then or equal to 1</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_GE_2</strong> </td>
+<td> Requires the current LOA to be greater then or equal to 2</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_GE_3</strong> </td>
+<td> Requires the current LOA to be greater then or equal to 3</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_EQ_0</strong> </td>
+<td> Requires the current LOA to be equal to 0</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_EQ_1</strong> </td>
+<td> Requires the current LOA to be equal to 1</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_EQ_2</strong> </td>
+<td> Requires the current LOA to be equal to 2</td>
+</tr>
+<tr>
+<td><strong>AFB_SESSION_LOA_EQ_3</strong> </td>
+<td> Requires the current LOA to be equal to 3</td>
+</tr>
+</tbody>
+</table>
+
+
+<p>If any of this flags is set, afb-daemon requires the token authentification
+as if the flag <strong>AFB_SESSION_CHECK</strong> had been set.</p>
+
+<p>The special value <strong>AFB_SESSION_NONE</strong> is zero and can be used to avoid any check.</p>
+
+<blockquote><p>Note that <strong>AFB_SESSION_CREATE</strong> and <strong>AFB_SESSION_CLOSE</strong> might be removed in later versions.</p></blockquote>
+
+<a name="Sending.messages.to.the.log.system"></a>
+<h2>Sending messages to the log system</h2>
+
+<p>Afb-daemon provides 4 levels of verbosity and 5 verbs for logging messages.</p>
+
+<p>The verbosity is managed. Options allow the change the verbosity of afb-daemon
+and the verbosity of the plugins can be set plugin by plugin.</p>
+
+<p>The verbs for logging messages are defined as macros that test the
+verbosity level and that call the real logging function only if the
+message must be output. This avoid evaluation of arguments of the
+formatting messages if the message must not be output.</p>
+
+<a name="Verbs.for.logging.messages"></a>
+<h3>Verbs for logging messages</h3>
+
+<p>The 5 logging verbs are:</p>
+
+<table>
+<thead>
+<tr>
+<th>Macro </th>
+<th style="text-align:center;"> Verbosity </th>
+<th> Meaning </th>
+<th style="text-align:center;"> syslog level</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>ERROR </td>
+<td style="text-align:center;"> 0 </td>
+<td> Error conditions </td>
+<td style="text-align:center;"> 3</td>
+</tr>
+<tr>
+<td>WARNING </td>
+<td style="text-align:center;"> 1 </td>
+<td> Warning conditions </td>
+<td style="text-align:center;"> 4</td>
+</tr>
+<tr>
+<td>NOTICE </td>
+<td style="text-align:center;"> 1 </td>
+<td> Normal but significant condition </td>
+<td style="text-align:center;"> 5</td>
+</tr>
+<tr>
+<td>INFO </td>
+<td style="text-align:center;"> 2 </td>
+<td> Informational </td>
+<td style="text-align:center;"> 6</td>
+</tr>
+<tr>
+<td>DEBUG </td>
+<td style="text-align:center;"> 3 </td>
+<td> Debug-level messages </td>
+<td style="text-align:center;"> 7</td>
+</tr>
+</tbody>
+</table>
+
+
+<p>You can note that the 2 verbs <strong>WARNING</strong> and <strong>INFO</strong> have the same level
+of verbosity. But they don’t have the same <em>syslog level</em>. It means that
+they are output with a different level on the logging system.</p>
+
+<p>All of these verbs have the same signature:</p>
+
+<pre><code>void ERROR(const struct AFB_interface *afbitf, const char *message, ...);
+</code></pre>
+
+<p>The first argument <strong>afbitf</strong> is the interface to afb daemon that the
+plugin received at its initialisation when <strong>pluginAfbV1Register</strong> was called.</p>
+
+<p>The second argument <strong>message</strong> is a formatting string compatible with printf/sprintf.</p>
+
+<p>The remaining arguments are arguments of the formating message like for printf.</p>
+
+<a name="Managing.verbosity"></a>
+<h3>Managing verbosity</h3>
+
+<p>Depending on the level of verbosity, the messages are output or not.
+The following table explains what messages will be output depending
+ont the verbosity level.</p>
+
+<table>
+<thead>
+<tr>
+<th style="text-align:center;">Level of verbosity </th>
+<th> Outputed macro</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center;">0 </td>
+<td> ERROR</td>
+</tr>
+<tr>
+<td style="text-align:center;">1 </td>
+<td> ERROR + WARNING + NOTICE</td>
+</tr>
+<tr>
+<td style="text-align:center;">2 </td>
+<td> ERROR + WARNING + NOTICE + INFO</td>
+</tr>
+<tr>
+<td style="text-align:center;">3 </td>
+<td> ERROR + WARNING + NOTICE + INFO + DEBUG</td>
+</tr>
+</tbody>
+</table>
+
+
+<a name="Output.format.and.destination"></a>
+<h3>Output format and destination</h3>
+
+<p>The syslog level is used for forging a prefix to the message.
+The prefixes are:</p>
+
+<table>
+<thead>
+<tr>
+<th style="text-align:center;">syslog level </th>
+<th> prefix</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center;">0 </td>
+<td> <0> EMERGENCY</td>
+</tr>
+<tr>
+<td style="text-align:center;">1 </td>
+<td> <1> ALERT</td>
+</tr>
+<tr>
+<td style="text-align:center;">2 </td>
+<td> <2> CRITICAL</td>
+</tr>
+<tr>
+<td style="text-align:center;">3 </td>
+<td> <3> ERROR</td>
+</tr>
+<tr>
+<td style="text-align:center;">4 </td>
+<td> <4> WARNING</td>
+</tr>
+<tr>
+<td style="text-align:center;">5 </td>
+<td> <5> NOTICE</td>
+</tr>
+<tr>
+<td style="text-align:center;">6 </td>
+<td> <6> INFO</td>
+</tr>
+<tr>
+<td style="text-align:center;">7 </td>
+<td> <7> DEBUG</td>
+</tr>
+</tbody>
+</table>
+
+
+<p>The message is issued to the standard error.
+The final destination of the message depends on how the systemd service
+was configured through the variable <strong>StandardError</strong>: It can be
+journal, syslog or kmsg. (See man sd-daemon).</p>
+
+<a name="Sending.events"></a>
+<h2>Sending events</h2>
+
+<p>Since version 0.5, plugins can broadcast events to any potential listener.
+This kind of bradcast is not targeted. Event targeted will come in a future
+version of afb-daemon.</p>
+
+<p>The plugin <em>tic-tac-toe</em> broadcasts events when the board changes.
+This is done in the function <strong>changed</strong>:</p>
+
+<pre><code>/*
+ * signals a change of the board
+ */
+static void changed(struct board *board, const char *reason)
+{
+ ...
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ ...
+
+ afb_daemon_broadcast_event(afbitf->daemon, reason, description);
+}
+</code></pre>
+
+<p>The description of the changed board is pushed via the daemon interface.</p>
+
+<p>Within the plugin <em>tic-tac-toe</em>, the <em>reason</em> indicates the origin of
+the change. For the function <strong>afb_daemon_broadcast_event</strong>, the second
+parameter is the name of the broadcasted event. The third argument is the
+object that is transmitted with the event.</p>
+
+<p>The function <strong>afb_daemon_broadcast_event</strong> is defined as below:</p>
+
+<pre><code>/*
+ * Broadcasts widely the event of 'name' with the data 'object'.
+ * 'object' can be NULL.
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'object'.
+ * Thus, in the case where 'object' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+void afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object);
+</code></pre>
+
+<blockquote><p>Be aware, as for reply functions, the <strong>object</strong> is automatically released using
+<strong>json_object_put</strong> by the function. Then call <strong>json_object_get</strong> before
+calling <strong>afb_daemon_broadcast_event</strong> to keep <strong>object</strong> available
+after the returning of the function.</p></blockquote>
+
+<p>In fact the event name received by the listener is prefixed with
+the name of the plugin. So when the change occurs after a move, the
+reason is <strong>move</strong> and then the clients receive the event <strong>tictactoe/move</strong>.</p>
+
+<blockquote><p>Note that nothing is said about the case sensitivity of event names.
+However, the event is always prefixed with the name that the plugin
+declared, with the same case, followed with a slash /.
+Thus it is safe to compare event using a case sensitive comparison.</p></blockquote>
+
+<a name="Writing.an.asynchronous.verb.implementation"></a>
+<h2>Writing an asynchronous verb implementation</h2>
+
+<p>The <em>tic-tac-toe</em> example allows two clients or more to share the same board.
+This is implemented by the verb <strong>join</strong> that illustrated partly the how to
+retrieve arguments.</p>
+
+<p>When two or more clients are sharing a same board, one of them can wait
+until the state of the board changes. (This coulded also be implemented using
+events because an even is generated each time the board changes).</p>
+
+<p>In this case, the reply to the wait is sent only when the board changes.
+See the diagram below:</p>
+
+<pre><code>CLIENT A CLIENT B TIC-TAC-TOE
+ | | |
+ +--------------|----------------->| wait . . . . . . . .
+ | | | .
+ : : : .
+ : : : .
+ | | | .
+ | +----------------->| move . . . .
+ | | | V .
+ | |<-----------------+ success of move .
+ | | | .
+ |<-------------|------------------+ success of wait <
+</code></pre>
+
+<p>Here, this is an invocation of the plugin by an other client that
+unblock the suspended <em>wait</em> call.
+But in general, this will be a timer, a hardware event, the sync with
+a concurrent process or thread, …</p>
+
+<p>So the case is common, this is an asynchronous implementation.</p>
+
+<p>Here is the listing of the function <strong>wait</strong>:</p>
+
+<pre><code>static void wait(struct afb_req req)
+{
+ struct board *board;
+ struct waiter *waiter;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'wait' called for boardid %d", board->id);
+
+ /* creates the waiter and enqueues it */
+ waiter = calloc(1, sizeof *waiter);
+ waiter->req = req;
+ waiter->next = board->waiters;
+ afb_req_addref(req);
+ board->waiters = waiter;
+}
+</code></pre>
+
+<p>After retrieving the board, the function adds a new waiter to the
+current list of waiters and returns without sending a reply.</p>
+
+<p>Before returning, it increases the reference count of the
+request <strong>req</strong> using the function <strong>afb_req_addref</strong>.</p>
+
+<blockquote><p>When the implentation of a verb returns without sending a reply,
+it <strong>MUST</strong> increment the reference count of the request
+using <strong>afb_req_addref</strong>. If it doesn’t bad things can happen.</p></blockquote>
+
+<p>Later, when the board changes, it calls the function <strong>changed</strong>
+of <em>tic-tac-toe</em> with the reason of the change.</p>
+
+<p>Here is the full listing of the function <strong>changed</strong>:</p>
+
+<pre><code>/*
+ * signals a change of the board
+ */
+static void changed(struct board *board, const char *reason)
+{
+ struct waiter *waiter, *next;
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ waiter = board->waiters;
+ board->waiters = NULL;
+ while (waiter != NULL) {
+ next = waiter->next;
+ afb_req_success(waiter->req, json_object_get(description), reason);
+ afb_req_unref(waiter->req);
+ free(waiter);
+ waiter = next;
+ }
+
+ afb_event_sender_push(afb_daemon_get_event_sender(afbitf->daemon), reason, description);
+}
+</code></pre>
+
+<p>The list of waiters is walked and a reply is sent to each waiter.
+After the sending the reply, the reference count of the request
+is decremented using <strong>afb_req_unref</strong> to allow its resources to be freed.</p>
+
+<blockquote><p>The reference count <strong>MUST</strong> be decremented using <strong>afb_req_unref</strong> because,
+otherwise, there is a leak of resources.
+It must be decremented <strong>AFTER</strong> the sending of the reply, because, otherwise,
+bad things may happen.</p></blockquote>
+
+<a name="How.to.build.a.plugin"></a>
+<h2>How to build a plugin</h2>
+
+<p>Afb-daemon provides a <em>pkg-config</em> configuration file that can be
+queried by the name <strong>afb-daemon</strong>.
+This configuration file provides data that should be used
+for compiling plugins. Examples:</p>
+
+<pre><code>$ pkg-config --cflags afb-daemon
+$ pkg-config --libs afb-daemon
+</code></pre>
+
+<a name="Example.for.cmake.meta.build.system"></a>
+<h3>Example for cmake meta build system</h3>
+
+<p>This example is the extract for building the plugin <em>afm-main</em> using <em>CMAKE</em>.</p>
+
+<pre><code>pkg_check_modules(afb afb-daemon)
+if(afb_FOUND)
+ message(STATUS "Creation afm-main-plugin for AFB-DAEMON")
+ add_library(afm-main-plugin MODULE afm-main-plugin.c)
+ target_compile_options(afm-main-plugin PRIVATE ${afb_CFLAGS})
+ target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS})
+ target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES})
+ set_target_properties(afm-main-plugin PROPERTIES
+ PREFIX ""
+ LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map"
+ )
+ install(TARGETS afm-main-plugin LIBRARY DESTINATION ${plugin_dir})
+else()
+ message(STATUS "Not creating the plugin for AFB-DAEMON")
+endif()
+</code></pre>
+
+<p>Let now describe some of these lines.</p>
+
+<pre><code>pkg_check_modules(afb afb-daemon)
+</code></pre>
+
+<p>This first lines searches to the <em>pkg-config</em> configuration file for
+<strong>afb-daemon</strong>. Resulting data are stored in the following variables:</p>
+
+<table>
+<thead>
+<tr>
+<th>Variable </th>
+<th> Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>afb_FOUND </td>
+<td> Set to 1 if afb-daemon plugin development files exist</td>
+</tr>
+<tr>
+<td>afb_LIBRARIES </td>
+<td> Only the libraries (w/o the ‘-l’) for compiling afb-daemon plugins</td>
+</tr>
+<tr>
+<td>afb_LIBRARY_DIRS </td>
+<td> The paths of the libraries (w/o the ‘-L’) for compiling afb-daemon plugins</td>
+</tr>
+<tr>
+<td>afb_LDFLAGS </td>
+<td> All required linker flags for compiling afb-daemon plugins</td>
+</tr>
+<tr>
+<td>afb_INCLUDE_DIRS </td>
+<td> The ‘-I’ preprocessor flags (w/o the ‘-I’) for compiling afb-daemon plugins</td>
+</tr>
+<tr>
+<td>afb_CFLAGS </td>
+<td> All required cflags for compiling afb-daemon plugins</td>
+</tr>
+</tbody>
+</table>
+
+
+<p>If development files are found, the plugin can be added to the set of
+target to build.</p>
+
+<pre><code>add_library(afm-main-plugin MODULE afm-main-plugin.c)
+</code></pre>
+
+<p>This line asks to create a shared library having only the
+source file afm-main-plugin.c (that is compiled).
+The default name of the created shared object is
+<strong>libafm-main-plugin.so</strong>.</p>
+
+<pre><code>set_target_properties(afm-main-plugin PROPERTIES
+ PREFIX ""
+ LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map"
+)
+</code></pre>
+
+<p>This lines are doing two things:</p>
+
+<ol>
+<li><p>It renames the built library from <strong>libafm-main-plugin.so</strong> to <strong>afm-main-plugin.so</strong>
+by removing the implicitely added prefix <em>lib</em>. This step is not mandatory
+at all because afb-daemon doesn’t check names of files when loading it.
+The only convention that use afb-daemon is that extension is <strong>.so</strong>
+but this convention is used only when afb-daemon discovers plugin
+from a directory hierarchy.</p></li>
+<li><p>It applies a version script at link to only export the conventional name
+of the entry point: <strong>pluginAfbV1Register</strong>. See below. By default, the linker
+that creates the shared object exports all the public symbols (C functions that
+are not <strong>static</strong>).</p></li>
+</ol>
+
+
+<p>Next line are:</p>
+
+<pre><code>target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS})
+target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES})
+</code></pre>
+
+<p>As you can see it uses the variables computed by <strong><em>pkg_check_modules(afb afb-daemon)</em></strong>
+to configure the compiler and the linker.</p>
+
+<a name="Exporting.the.function.pluginAfbV1Register"></a>
+<h3>Exporting the function pluginAfbV1Register</h3>
+
+<p>The function <strong>pluginAfbV1Register</strong> must be exported. This can be achieved
+using a version script when linking. Here is the version script that is
+used for <em>tic-tac-toe</em> (plugins/samples/export.map).</p>
+
+<pre><code>{ global: pluginAfbV1Register; local: *; };
+</code></pre>
+
+<p>This sample <a href="https://sourceware.org/binutils/docs-2.26/ld/VERSION.html#VERSION">version script</a>
+exports as global the symbol <em>pluginAfbV1Register</em> and hides any
+other symbols.</p>
+
+<p>This version script is added to the link options using the
+option <strong>–version-script=export.map</strong> is given directly to the
+linker or using th option <strong>-Wl,–version-script=export.map</strong>
+when the option is given to the C compiler.</p>
+
+<a name="Building.within.yocto"></a>
+<h3>Building within yocto</h3>
+
+<p>Adding a dependency to afb-daemon is enough. See below:</p>
+
+<pre><code>DEPENDS += " afb-daemon "
+</code></pre>
+</body>
+</html>
--- /dev/null
+HOWTO WRITE a PLUGIN for AFB-DAEMON
+===================================
+ version: 1
+ Date: 27 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.
+
+### Kinds of plugins
+
+There is two kinds of plugins: application plugins and service
+plugins.
+
+#### Application plugins
+
+Application plugins are intended to be instanciated for each
+application: when an application using that plugin is started,
+its binder starts a new instance of the plugin.
+
+It means that the application plugins mainly have only one
+context to manage for one client.
+
+#### Service plugins
+
+Service plugins are intended to be instanciated only one time
+only and connected to many clients.
+
+So either it does not manage context at all or otherwise,
+if it manages context, it should be able to manage one context
+per client.
+
+In details, it may be useful to have service plugins at a user
+level.
+
+### 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***.
+
+Dependencies when compiling
+---------------------------
+
+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
+because almost all plugin will use **json-c**.
+
+If this behaviour is a problem, let us know.
+
+Internally, afb-daemon uses **libsystemd** for its event loop
+and for its binding to D-Bus.
+Plugins developpers are encouraged to also use this library.
+But it is a matter of choice.
+Thus there is no dependency to **libsystemd**.
+
+> Afb-daemon provides no library for plugins.
+> The functions that the plugin need to have are given
+> to the plugin at runtime through pointer using read-only
+> memory.
+
+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.
+
+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.
+
+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. Let summarize it:
+
+1. The function **board_of_req** retrieves the context stored
+for the plugin: the board.
+
+2. The macro **INFO** sends a message of kind *INFO*
+to the logging system. The global variable named **afbitf**
+used represents the interface to afb-daemon.
+
+3. The function **describe** creates a json_object representing
+the board.
+
+4. The function **afb_req_success** sends the reply, attaching to
+it the object *description*.
+
+### The incoming request
+
+For any implementation, the request is received by a structure of type
+**struct afb_req**.
+
+> Note that this is a PLAIN structure, not a pointer to a structure.
+
+The definition of **struct afb_req** is:
+
+ /*
+ * Describes the request by plugins from afb-daemon
+ */
+ struct afb_req {
+ const struct afb_req_itf *itf; /* the interfacing functions */
+ void *closure; /* the closure for functions */
+ };
+
+It contains two pointers: one, *itf*, points to the functions needed
+to handle the internal request represented by the second pointer, *closure*.
+
+> The structure must never be used directly.
+> Insted, use the intended functions provided
+> by afb-daemon and described here.
+
+*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 a context to the session
+
+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);
+ }
+
+The function **afb_req_context** ensure an existing context
+for the session of the request.
+Its two last arguments are functions. Here, 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;
+ }
+
+The second argument if the function that creates the context.
+For the plugin *tic-tac-toe* it is the function **get_new_board**.
+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 third argument if the function that frees the context.
+For the plugin *tic-tac-toe* it is the function **release_board**.
+The function **release_board** decrease the the count of use of
+the board given as argument. If the use count decrease to zero,
+the board data are freed.
+
+The definition of the other functions for dealing with contexts are:
+
+ /*
+ * Gets the pointer stored by the plugin for the session of 'req'.
+ * When the plugin has not yet recorded a pointer, NULL is returned.
+ */
+ void *afb_req_context_get(struct afb_req req);
+
+ /*
+ * Stores for the plugin the pointer 'context' to the session of 'req'.
+ * The function 'free_context' will be called when the session is closed
+ * or if plugin stores an other pointer.
+ */
+ void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
+
+ /*
+ * Frees the pointer stored by the plugin for the session of 'req'
+ * and sets it to NULL.
+ *
+ * Shortcut for: afb_req_context_set(req, NULL, NULL)
+ */
+ static inline void afb_req_context_clear(struct afb_req req)
+ {
+ afb_req_context_set(req, NULL, NULL);
+ }
+
+### Sending the reply to a request
+
+Two kinds of replies can be made: successful replies and
+failure replies.
+
+> Sending a reply to a request must be done at most one time.
+
+The two functions to send a reply of kind "success" are
+**afb_req_success** and **afb_req_success_f**.
+
+ /*
+ * Sends a reply of kind success to the request 'req'.
+ * The status of the reply is automatically set to "success".
+ * Its send the object 'obj' (can be NULL) with an
+ * informationnal comment 'info (can also be NULL).
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+ void afb_req_success(struct afb_req req, struct json_object *obj, const char *info);
+
+ /*
+ * Same as 'afb_req_success' but the 'info' is a formatting
+ * string followed by arguments.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+ void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...);
+
+The two functions to send a reply of kind "failure" are
+**afb_req_fail** and **afb_req_fail_f**.
+
+ /*
+ * Sends a reply of kind failure to the request 'req'.
+ * The status of the reply is set to 'status' and an
+ * informationnal comment 'info' (can also be NULL) can be added.
+ *
+ * Note that calling afb_req_fail("success", info) is equivalent
+ * to call afb_req_success(NULL, info). Thus even if possible it
+ * is strongly recommanded to NEVER use "success" for status.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+ void afb_req_fail(struct afb_req req, const char *status, const char *info);
+
+ /*
+ * Same as 'afb_req_fail' but the 'info' is a formatting
+ * string followed by arguments.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+ void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...);
+
+> For conveniency, these functions call **json_object_put** to release the object **obj**
+> that they send. Then **obj** can not be used after calling one of these reply functions.
+> When it is not the expected behaviour, calling the function **json_object_get** on the object **obj**
+> before cancels the effect of **json_object_put**.
+
+Getting argument of invocation
+------------------------------
+
+Many verbs expect arguments. Afb-daemon let plugins
+retrieve their arguments by name not by position.
+
+Arguments are given by the requests either through HTTP
+or through WebSockets.
+
+For example, the verb **join** of the plugin **tic-tac-toe**
+expects one argument: the *boardid* to join. Here is an extract:
+
+ /*
+ * Join a board
+ */
+ static void join(struct afb_req req)
+ {
+ struct board *board, *new_board;
+ const char *id;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'join' called for boardid %d", board->id);
+
+ /* retrieves the argument */
+ id = afb_req_value(req, "boardid");
+ if (id == NULL)
+ goto bad_request;
+ ...
+
+The function **afb_req_value** search in the request *req*
+for an argument whose name is given. When no argument of the
+given name was passed, **afb_req_value** returns NULL.
+
+> The search is case sensitive. So the name *boardid* is not the
+> same name than *BoardId*. But this must not be assumed so two
+> expected names of argument should not differ only by case.
+
+### Basic functions for querying arguments
+
+The function **afb_req_value** is defined as below:
+
+ /*
+ * Gets from the request 'req' the string value of the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name'.
+ * Returns the value of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).value
+ */
+ static inline const char *afb_req_value(struct afb_req req, const char *name)
+ {
+ return afb_req_get(req, name).value;
+ }
+
+It is defined as a shortcut to call the function **afb_req_get**.
+That function is defined as below:
+
+ /*
+ * Gets from the request 'req' the argument of 'name'.
+ * Returns a PLAIN structure of type 'struct afb_arg'.
+ * When the argument of 'name' is not found, all fields of result are set to NULL.
+ * When the argument of 'name' is found, the fields are filled,
+ * in particular, the field 'result.name' is set to 'name'.
+ *
+ * There is a special name value: the empty string.
+ * The argument of name "" is defined only if the request was made using
+ * an HTTP POST of Content-Type "application/json". In that case, the
+ * argument of name "" receives the value of the body of the HTTP request.
+ */
+ struct afb_arg afb_req_get(struct afb_req req, const char *name);
+
+That function takes 2 parameters: the request and the name
+of the argument to retrieve. It returns a PLAIN structure of
+type **struct afb_arg**.
+
+There is a special name that is defined when the request is
+of type HTTP/POST with a Content-Type being application/json.
+This name is **""** (the empty string). In that case, the value
+of this argument of empty name is the string received as a body
+of the post and is supposed to be a JSON string.
+
+The definition of **struct afb_arg** is:
+
+ /*
+ * Describes an argument (or parameter) of a request
+ */
+ struct afb_arg {
+ const char *name; /* name of the argument or NULL if invalid */
+ const char *value; /* string representation of the value of the argument */
+ /* original filename of the argument if path != NULL */
+ const char *path; /* if not NULL, path of the received file for the argument */
+ /* when the request is finalized this file is removed */
+ };
+
+The structure returns the data arguments that are known for the
+request. This data include a field named **path**. This **path**
+can be accessed using the function **afb_req_path** defined as
+below:
+
+ /*
+ * Gets from the request 'req' the path for file attached to the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name' or when there is no file.
+ * Returns the path of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).path
+ */
+ static inline const char *afb_req_path(struct afb_req req, const char *name)
+ {
+ return afb_req_get(req, name).path;
+ }
+
+The path is only defined for HTTP/POST requests that send file.
+
+### Arguments for received files
+
+As it is explained just above, clients can send files using
+HTTP/POST requests.
+
+Received files are attached to a arguments. For example, the
+following HTTP fragment (from test/sample-post.html)
+will send an HTTP/POST request to the method
+**post/upload-image** with 2 arguments named *file* and
+*hidden*.
+
+ <h2>Sample Post File</h2>
+ <form enctype="multipart/form-data">
+ <input type="file" name="file" />
+ <input type="hidden" name="hidden" value="bollobollo" />
+ <br>
+ <button formmethod="POST" formaction="api/post/upload-image">Post File</button>
+ </form>
+
+In that case, the argument named **file** has its value and its
+path defined and not NULL.
+
+The value is the name of the file as it was
+set by the HTTP client and is generally the filename on the
+client side.
+
+The path is the path of the file saved on the temporary local storage
+area of the application. This is a randomly generated and unic filename
+not linked in any way with the original filename on the client.
+
+The plugin can use the file at the given path the way that it wants:
+read, write, remove, copy, rename...
+But when the reply is sent and the query is terminated, the file at
+this path is destroyed if it still exist.
+
+### Arguments as a JSON object
+
+Plugins can get all the arguments as one single object.
+This feature is provided by the function **afb_req_json**
+that is defined as below:
+
+ /*
+ * Gets from the request 'req' the json object hashing the arguments.
+ * The returned object must not be released using 'json_object_put'.
+ */
+ struct json_object *afb_req_json(struct afb_req req);
+
+It returns a json object. This object depends on how the request was
+made:
+
+- For HTTP requests, this is an object whose keys are the names of the
+arguments and whose values are either a string for common arguments or
+an object like { "file": "...", "path": "..." }
+
+- For WebSockets requests, the returned object is the object
+given by the client transparently transported.
+
+> In fact, for Websockets requests, the function **afb_req_value**
+> can be seen as a shortcut to
+> ***json_object_get_string(json_object_object_get(afb_req_json(req), name))***
+
+Initialisation of the plugin and declaration of verbs
+-----------------------------------------------------
+
+To be active, the verbs of the plugin should be declared to
+afb-daemon. And even more, the plugin itself must be recorded.
+
+The mechanism for doing this is very simple: when afb-need starts,
+it loads the plugins that are listed in its argument or configuration.
+
+Loading a plugin follows the following steps:
+
+1. It loads the plugin using *dlopen*.
+
+2. It searchs for the symbol named **pluginAfbV1Register** using *dlsym*.
+This symbol is assumed to be the exported initialisation function of the plugin.
+
+3. It build an interface object for the plugin.
+
+4. It calls the found function **pluginAfbV1Register** and pass it the pointer
+to its interface.
+
+5. The function **pluginAfbV1Register** setup the plugin, initialize it.
+
+6. The function **pluginAfbV1Register** returns the pointer to a structure
+that describes the plugin: its version, its name (prefix or API name), and the
+list of its verbs.
+
+7. Afb-daemon checks that the returned version and name can be managed.
+If it can manage it, the plugin and its verbs are recorded and can be used
+when afb-daemon finishes it initialisation.
+
+Here is the listing of the function **pluginAfbV1Register** of the plugin
+*tic-tac-toe*:
+
+ /*
+ * activation function for registering the plugin called by afb-daemon
+ */
+ const struct AFB_plugin *pluginAfbV1Register(const struct AFB_interface *itf)
+ {
+ afbitf = itf; // records the interface for accessing afb-daemon
+ return &plugin_description; // returns the description of the plugin
+ }
+
+This is a very small function because the *tic-tac-toe* plugin doesn't have initialisation step.
+It merely record the daemon's interface and returns its descritption.
+
+The variable **afbitf** is a variable global to the plugin. It records the
+interface to afb-daemon and is used for logging and pushing events.
+Here is its declaration:
+
+ /*
+ * the interface to afb-daemon
+ */
+ const struct AFB_interface *afbitf;
+
+The description of the plugin is defined as below.
+
+ /*
+ * array of the verbs exported to afb-daemon
+ */
+ static const struct AFB_verb_desc_v1 plugin_verbs[] = {
+ /* VERB'S NAME SESSION MANAGEMENT FUNCTION TO CALL SHORT DESCRIPTION */
+ { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" },
+ { .name= "play", .session= AFB_SESSION_NONE, .callback= play, .info= "Asks the server to play" },
+ { .name= "move", .session= AFB_SESSION_NONE, .callback= move, .info= "Tells the client move" },
+ { .name= "board", .session= AFB_SESSION_NONE, .callback= board, .info= "Get the current board" },
+ { .name= "level", .session= AFB_SESSION_NONE, .callback= level, .info= "Set the server level" },
+ { .name= "join", .session= AFB_SESSION_CHECK,.callback= join, .info= "Join a board" },
+ { .name= "undo", .session= AFB_SESSION_NONE, .callback= undo, .info= "Undo the last move" },
+ { .name= "wait", .session= AFB_SESSION_NONE, .callback= wait, .info= "Wait for a change" },
+ { .name= NULL } /* marker for end of the array */
+ };
+
+ /*
+ * description of the plugin for afb-daemon
+ */
+ static const struct AFB_plugin plugin_description =
+ {
+ /* description conforms to VERSION 1 */
+ .type= AFB_PLUGIN_VERSION_1,
+ .v1= { /* fills the v1 field of the union when AFB_PLUGIN_VERSION_1 */
+ .prefix= "tictactoe", /* the API name (or plugin name or prefix) */
+ .info= "Sample tac-tac-toe game", /* short description of of the plugin */
+ .verbs = plugin_verbs /* the array describing the verbs of the API */
+ }
+ };
+
+The structure **plugin_description** describes the plugin.
+It declares the type and version of the plugin, its name, a description
+and a list of its verbs.
+
+The list of verbs is an array of structures describing the verbs and terminated by a marker:
+a verb whose name is NULL.
+
+The description of the verbs for this version is made of 4 fields:
+
+- the name of the verbs,
+
+- the session management flags,
+
+- the implementation function to be call for the verb,
+
+- a short description.
+
+The structure describing verbs is defined as follows:
+
+ /*
+ * Description of one verb of the API provided by the plugin
+ * This enumeration is valid for plugins of type 1
+ */
+ struct AFB_verb_desc_v1
+ {
+ const char *name; /* name of the verb */
+ enum AFB_session_v1 session; /* authorisation and session requirements of the verb */
+ void (*callback)(struct afb_req req); /* callback function implementing the verb */
+ const char *info; /* textual description of the verb */
+ };
+
+For technical reasons, the enumeration **enum AFB_session_v1** is not exactly an
+enumeration but the wrapper of constant definitions that can be mixed using bitwise or
+(the C operator |).
+
+The constants that can bit mixed are:
+
+Constant name | Meaning
+-------------------------|-------------------------------------------------------------
+**AFB_SESSION_CREATE** | Equals to AFB_SESSION_LOA_EQ_0|AFB_SESSION_RENEW
+**AFB_SESSION_CLOSE** | Closes the session after the reply and set the LOA to 0
+**AFB_SESSION_RENEW** | Refreshes the token of authentification
+**AFB_SESSION_CHECK** | Just requires the token authentification
+**AFB_SESSION_LOA_LE_0** | Requires the current LOA to be lesser then or equal to 0
+**AFB_SESSION_LOA_LE_1** | Requires the current LOA to be lesser then or equal to 1
+**AFB_SESSION_LOA_LE_2** | Requires the current LOA to be lesser then or equal to 2
+**AFB_SESSION_LOA_LE_3** | Requires the current LOA to be lesser then or equal to 3
+**AFB_SESSION_LOA_GE_0** | Requires the current LOA to be greater then or equal to 0
+**AFB_SESSION_LOA_GE_1** | Requires the current LOA to be greater then or equal to 1
+**AFB_SESSION_LOA_GE_2** | Requires the current LOA to be greater then or equal to 2
+**AFB_SESSION_LOA_GE_3** | Requires the current LOA to be greater then or equal to 3
+**AFB_SESSION_LOA_EQ_0** | Requires the current LOA to be equal to 0
+**AFB_SESSION_LOA_EQ_1** | Requires the current LOA to be equal to 1
+**AFB_SESSION_LOA_EQ_2** | Requires the current LOA to be equal to 2
+**AFB_SESSION_LOA_EQ_3** | Requires the current LOA to be equal to 3
+
+If any of this flags is set, afb-daemon requires the token authentification
+as if the flag **AFB_SESSION_CHECK** had been set.
+
+The special value **AFB_SESSION_NONE** is zero and can be used to avoid any check.
+
+> Note that **AFB_SESSION_CREATE** and **AFB_SESSION_CLOSE** might be removed in later versions.
+
+Sending messages to the log system
+----------------------------------
+
+Afb-daemon provides 4 levels of verbosity and 5 verbs for logging messages.
+
+The verbosity is managed. Options allow the change the verbosity of afb-daemon
+and the verbosity of the plugins can be set plugin by plugin.
+
+The verbs for logging messages are defined as macros that test the
+verbosity level and that call the real logging function only if the
+message must be output. This avoid evaluation of arguments of the
+formatting messages if the message must not be output.
+
+### Verbs for logging messages
+
+The 5 logging verbs are:
+
+Macro | Verbosity | Meaning | syslog level
+--------|:---------:|-----------------------------------|:-----------:
+ERROR | 0 | Error conditions | 3
+WARNING | 1 | Warning conditions | 4
+NOTICE | 1 | Normal but significant condition | 5
+INFO | 2 | Informational | 6
+DEBUG | 3 | Debug-level messages | 7
+
+You can note that the 2 verbs **WARNING** and **INFO** have the same level
+of verbosity. But they don't have the same *syslog level*. It means that
+they are output with a different level on the logging system.
+
+All of these verbs have the same signature:
+
+ void ERROR(const struct AFB_interface *afbitf, const char *message, ...);
+
+The first argument **afbitf** is the interface to afb daemon that the
+plugin received at its initialisation when **pluginAfbV1Register** was called.
+
+The second argument **message** is a formatting string compatible with printf/sprintf.
+
+The remaining arguments are arguments of the formating message like for printf.
+
+### Managing verbosity
+
+Depending on the level of verbosity, the messages are output or not.
+The following table explains what messages will be output depending
+ont the verbosity level.
+
+Level of verbosity | Outputed macro
+:-----------------:|--------------------------
+ 0 | ERROR
+ 1 | ERROR + WARNING + NOTICE
+ 2 | ERROR + WARNING + NOTICE + INFO
+ 3 | ERROR + WARNING + NOTICE + INFO + DEBUG
+
+### Output format and destination
+
+The syslog level is used for forging a prefix to the message.
+The prefixes are:
+
+syslog level | prefix
+:-----------:|---------------
+ 0 | <0> EMERGENCY
+ 1 | <1> ALERT
+ 2 | <2> CRITICAL
+ 3 | <3> ERROR
+ 4 | <4> WARNING
+ 5 | <5> NOTICE
+ 6 | <6> INFO
+ 7 | <7> DEBUG
+
+
+The message is issued to the standard error.
+The final destination of the message depends on how the systemd service
+was configured through the variable **StandardError**: It can be
+journal, syslog or kmsg. (See man sd-daemon).
+
+Sending events
+--------------
+
+Since version 0.5, plugins can broadcast events to any potential listener.
+This kind of bradcast is not targeted. Event targeted will come in a future
+version of afb-daemon.
+
+The plugin *tic-tac-toe* broadcasts events when the board changes.
+This is done in the function **changed**:
+
+ /*
+ * signals a change of the board
+ */
+ static void changed(struct board *board, const char *reason)
+ {
+ ...
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ ...
+
+ afb_daemon_broadcast_event(afbitf->daemon, reason, description);
+ }
+
+The description of the changed board is pushed via the daemon interface.
+
+Within the plugin *tic-tac-toe*, the *reason* indicates the origin of
+the change. For the function **afb_daemon_broadcast_event**, the second
+parameter is the name of the broadcasted event. The third argument is the
+object that is transmitted with the event.
+
+The function **afb_daemon_broadcast_event** is defined as below:
+
+ /*
+ * Broadcasts widely the event of 'name' with the data 'object'.
+ * 'object' can be NULL.
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'object'.
+ * Thus, in the case where 'object' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+ void afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object);
+
+> Be aware, as for reply functions, the **object** is automatically released using
+> **json_object_put** by the function. Then call **json_object_get** before
+> calling **afb_daemon_broadcast_event** to keep **object** available
+> after the returning of the function.
+
+In fact the event name received by the listener is prefixed with
+the name of the plugin. So when the change occurs after a move, the
+reason is **move** and then the clients receive the event **tictactoe/move**.
+
+> Note that nothing is said about the case sensitivity of event names.
+> However, the event is always prefixed with the name that the plugin
+> declared, with the same case, followed with a slash /.
+> Thus it is safe to compare event using a case sensitive comparison.
+
+
+
+Writing an asynchronous verb implementation
+-------------------------------------------
+
+The *tic-tac-toe* example allows two clients or more to share the same board.
+This is implemented by the verb **join** that illustrated partly the how to
+retrieve arguments.
+
+When two or more clients are sharing a same board, one of them can wait
+until the state of the board changes. (This coulded also be implemented using
+events because an even is generated each time the board changes).
+
+In this case, the reply to the wait is sent only when the board changes.
+See the diagram below:
+
+ CLIENT A CLIENT B TIC-TAC-TOE
+ | | |
+ +--------------|----------------->| wait . . . . . . . .
+ | | | .
+ : : : .
+ : : : .
+ | | | .
+ | +----------------->| move . . . .
+ | | | V .
+ | |<-----------------+ success of move .
+ | | | .
+ |<-------------|------------------+ success of wait <
+
+Here, this is an invocation of the plugin by an other client that
+unblock the suspended *wait* call.
+But in general, this will be a timer, a hardware event, the sync with
+a concurrent process or thread, ...
+
+So the case is common, this is an asynchronous implementation.
+
+Here is the listing of the function **wait**:
+
+ static void wait(struct afb_req req)
+ {
+ struct board *board;
+ struct waiter *waiter;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'wait' called for boardid %d", board->id);
+
+ /* creates the waiter and enqueues it */
+ waiter = calloc(1, sizeof *waiter);
+ waiter->req = req;
+ waiter->next = board->waiters;
+ afb_req_addref(req);
+ board->waiters = waiter;
+ }
+
+After retrieving the board, the function adds a new waiter to the
+current list of waiters and returns without sending a reply.
+
+Before returning, it increases the reference count of the
+request **req** using the function **afb_req_addref**.
+
+> When the implentation of a verb returns without sending a reply,
+> it **MUST** increment the reference count of the request
+> using **afb_req_addref**. If it doesn't bad things can happen.
+
+Later, when the board changes, it calls the function **changed**
+of *tic-tac-toe* with the reason of the change.
+
+Here is the full listing of the function **changed**:
+
+ /*
+ * signals a change of the board
+ */
+ static void changed(struct board *board, const char *reason)
+ {
+ struct waiter *waiter, *next;
+ struct json_object *description;
+
+ /* get the description */
+ description = describe(board);
+
+ waiter = board->waiters;
+ board->waiters = NULL;
+ while (waiter != NULL) {
+ next = waiter->next;
+ afb_req_success(waiter->req, json_object_get(description), reason);
+ afb_req_unref(waiter->req);
+ free(waiter);
+ waiter = next;
+ }
+
+ afb_event_sender_push(afb_daemon_get_event_sender(afbitf->daemon), reason, description);
+ }
+
+The list of waiters is walked and a reply is sent to each waiter.
+After the sending the reply, the reference count of the request
+is decremented using **afb_req_unref** to allow its resources to be freed.
+
+> The reference count **MUST** be decremented using **afb_req_unref** because,
+> otherwise, there is a leak of resources.
+> It must be decremented **AFTER** the sending of the reply, because, otherwise,
+> bad things may happen.
+
+How to build a plugin
+---------------------
+
+Afb-daemon provides a *pkg-config* configuration file that can be
+queried by the name **afb-daemon**.
+This configuration file provides data that should be used
+for compiling plugins. Examples:
+
+ $ pkg-config --cflags afb-daemon
+ $ pkg-config --libs afb-daemon
+
+### Example for cmake meta build system
+
+This example is the extract for building the plugin *afm-main* using *CMAKE*.
+
+ pkg_check_modules(afb afb-daemon)
+ if(afb_FOUND)
+ message(STATUS "Creation afm-main-plugin for AFB-DAEMON")
+ add_library(afm-main-plugin MODULE afm-main-plugin.c)
+ target_compile_options(afm-main-plugin PRIVATE ${afb_CFLAGS})
+ target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS})
+ target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES})
+ set_target_properties(afm-main-plugin PROPERTIES
+ PREFIX ""
+ LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map"
+ )
+ install(TARGETS afm-main-plugin LIBRARY DESTINATION ${plugin_dir})
+ else()
+ message(STATUS "Not creating the plugin for AFB-DAEMON")
+ endif()
+
+Let now describe some of these lines.
+
+ pkg_check_modules(afb afb-daemon)
+
+This first lines searches to the *pkg-config* configuration file for
+**afb-daemon**. Resulting data are stored in the following variables:
+
+Variable | Meaning
+------------------|------------------------------------------------
+afb_FOUND | Set to 1 if afb-daemon plugin development files exist
+afb_LIBRARIES | Only the libraries (w/o the '-l') for compiling afb-daemon plugins
+afb_LIBRARY_DIRS | The paths of the libraries (w/o the '-L') for compiling afb-daemon plugins
+afb_LDFLAGS | All required linker flags for compiling afb-daemon plugins
+afb_INCLUDE_DIRS | The '-I' preprocessor flags (w/o the '-I') for compiling afb-daemon plugins
+afb_CFLAGS | All required cflags for compiling afb-daemon plugins
+
+If development files are found, the plugin can be added to the set of
+target to build.
+
+ add_library(afm-main-plugin MODULE afm-main-plugin.c)
+
+This line asks to create a shared library having only the
+source file afm-main-plugin.c (that is compiled).
+The default name of the created shared object is
+**libafm-main-plugin.so**.
+
+ set_target_properties(afm-main-plugin PROPERTIES
+ PREFIX ""
+ LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map"
+ )
+
+This lines are doing two things:
+
+1. It renames the built library from **libafm-main-plugin.so** to **afm-main-plugin.so**
+by removing the implicitely added prefix *lib*. This step is not mandatory
+at all because afb-daemon doesn't check names of files when loading it.
+The only convention that use afb-daemon is that extension is **.so**
+but this convention is used only when afb-daemon discovers plugin
+from a directory hierarchy.
+
+2. It applies a version script at link to only export the conventional name
+of the entry point: **pluginAfbV1Register**. See below. By default, the linker
+that creates the shared object exports all the public symbols (C functions that
+are not **static**).
+
+Next line are:
+
+ target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS})
+ target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES})
+
+As you can see it uses the variables computed by ***pkg_check_modules(afb afb-daemon)***
+to configure the compiler and the linker.
+
+### Exporting the function pluginAfbV1Register
+
+The function **pluginAfbV1Register** must be exported. This can be achieved
+using a version script when linking. Here is the version script that is
+used for *tic-tac-toe* (plugins/samples/export.map).
+
+ { global: pluginAfbV1Register; local: *; };
+
+This sample [version script](https://sourceware.org/binutils/docs-2.26/ld/VERSION.html#VERSION)
+exports as global the symbol *pluginAfbV1Register* and hides any
+other symbols.
+
+This version script is added to the link options using the
+option **--version-script=export.map** is given directly to the
+linker or using th option **-Wl,--version-script=export.map**
+when the option is given to the C compiler.
+
+### Building within yocto
+
+Adding a dependency to afb-daemon is enough. See below:
+
+ DEPENDS += " afb-daemon "
+
color: #000;
}
-h1, h2, h3 { color: #306; }
+h1, h2, h3, h4 {
+ color: #306;
+ text-decoration: underline;
+}
pre {
border: medium dashed #306;
- background: #ccc;
- margin-left: 4em;
+ border-width: 0.1em;
+ background-color: #eee;
+ margin-left: 2em;
+ margin-right: 2em;
padding: 1em;
+ outline: #555;
}
+pre:first-of-type { width: 20em; }
+
+blockquote {
+ border-left: solid thick black;
+ background-color: #ff8;
+ font: bolder;
+ padding: 0.7em 1.5em;
+}
+
+table {
+ margin-left: 2em;
+ background-color: #dff;
+ outline: 0.25em solid #a6f;
+/* padding: 0.25em;*/
+}
+thead {background-color: #a6f;}
+tr:nth-child(even) {background-color: #aee;}
+td { padding: 0.1em 0.5em; }
-#!/bin/sh
-
-subst() {
- awk -v pat="$1" -v rep="$(sed 's:\\:\\\\:g' $2)" '{gsub(pat,rep);gsub(pat,"\\&");print}'
-}
+#!/bin/bash
+# the HTML template
main='<html>
<head>
<link rel="stylesheet" type="text/css" href="doc.css">
</body>
</html>'
-for x in *.md; do
- t=$(git log -n 1 --format=%ct $x)
+# substitute the pattern $1 by the content of the file $2
+subst() {
+ awk -v pat="$1" -v rep="$(sed 's:\\:\\\\:g' $2)" '{gsub(pat,rep);gsub(pat,"\\&");print}'
+}
+
+# update the date field of file $1
+updadate() {
+ local x=$1
+ local t=$(git log -n 1 --format=%ct $x)
[[ -n "$t" ]] || t=$(stat -c %Y $x)
- d=$(LANG= date -d @$t +"%d %B %Y")
+ local 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
+}
+
+# make the html file for $1
+mkhtml() {
+ local x=$1
+ local h=${x%%.md}.html
+ expand -i $x | sed 's: : :' > $h.pre
+ markdown -f toc,autolink $h.pre > $h.toc.no
+ markdown -Tf toc,autolink $h.pre > $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*
+ rm $h.*
+}
+
+# apply
+for x in *.md; do
+ updadate $x
+ mkhtml $x
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: 25 May 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. Let summarize it:
-
-1. The function **board_of_req** retrieves the context stored
-for the plugin: the board.
-
-2. The macro **INFO** sends a message of kind *INFO*
-to the logging system. The global variable named **afbitf**
-used represents the interface to afb-daemon.
-
-3. The function **describe** creates a json_object representing
-the board.
-
-4. The function **afb_req_success** sends the reply, attaching to
-it the object *description*.
-
-### The incoming request
-
-For any implementation, the request is received by a structure of type
-**struct afb_req**.
-
-***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);
- }
-
-The function **afb_req_context** ensure an existing context
-for the session of the request.
-Its two last arguments are functions. Here, 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;
- }
-
-The second argument if the function that creates the context.
-For the plugin *tic-tac-toe* it is the function **get_new_board**.
-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 third argument if the function that frees the context.
-For the plugin *tic-tac-toe* it is the function **release_board**.
-The function **release_board** decrease the the count of use of
-the board given as argument. If the use count decrease to zero,
-the board data are freed.
-
-### Sending the reply to a request
-
-Sending a reply to a request must be done at most one time.
-
-Two kinds of replies can be made: successful replies and
-failure replies.
-
-The functions to send replies are defined as below:
-
- /*
- * Sends a reply of kind success to the request 'req'.
- * The status of the reply is automatically set to "success".
- * Its send the object 'obj' (can be NULL) with an
- * informationnal comment 'info (can also be NULL).
- */
- static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info)
- {
- req.itf->success(req.closure, obj, info);
- }
-
- /*
- * Same as 'afb_req_success' but the 'info' is a formatting
- * string followed by arguments.
- */
- static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...)
- {
- char *message;
- va_list args;
- va_start(args, info);
- if (info == NULL || vasprintf(&message, info, args) < 0)
- message = NULL;
- va_end(args);
- afb_req_success(req, obj, message);
- free(message);
- }
-
- /*
- * Sends a reply of kind failure to the request 'req'.
- * The status of the reply is set to 'status' and an
- * informationnal comment 'info' (can also be NULL) can be added.
- *
- * Note that calling afb_req_fail("success", info) is equivalent
- * to call afb_req_success(NULL, info). Thus even if possible it
- * is strongly recommanded to NEVER use "success" for status.
- */
- static inline void afb_req_fail(struct afb_req req, const char *status, const char *info)
- {
- req.itf->fail(req.closure, status, info);
- }
-
- /*
- * Same as 'afb_req_fail' but the 'info' is a formatting
- * string followed by arguments.
- */
- static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...)
- {
- char *message;
- va_list args;
- va_start(args, info);
- if (info == NULL || vasprintf(&message, info, args) < 0)
- message = NULL;
- va_end(args);
- afb_req_fail(req, status, message);
- free(message);
- }
-
-
-
-Getting argument of invocation
-------------------------------
-
-Sending messages to the log system
-----------------------------------
-
-How to build a plugin
----------------------
-
-Afb-daemon provides a *pkg-config* configuration file.
-
-
};
/*
- * Enum for Session/Token/Authentication middleware.
+ * Enum for Session/Token/Assurance middleware.
* This enumeration is valid for plugins of type 1
*/
enum AFB_session_v1
{
- AFB_SESSION_NONE = 0, /* no session and no authentification required */
- AFB_SESSION_CREATE = 1, /* requires authentification and first call of the session */
- AFB_SESSION_CLOSE = 2, /* closes the session after authentification */
- AFB_SESSION_RENEW = 4, /* refreshes the token after authentification */
- AFB_SESSION_CHECK = 8, /* enforce authentification */
+ AFB_SESSION_NONE = 0, /* nothing required */
+ AFB_SESSION_CREATE = 1, /* Obsolete */
+ AFB_SESSION_CLOSE = 2, /* After token authentification, closes the session at end */
+ AFB_SESSION_RENEW = 4, /* After token authentification, refreshes the token at end */
+ AFB_SESSION_CHECK = 8, /* Requires token authentification */
AFB_SESSION_LOA_GE = 16, /* check that the LOA is greater or equal to the given value */
AFB_SESSION_LOA_LE = 32, /* check that the LOA is lesser or equal to the given value */
AFB_SESSION_LOA_EQ = 48, /* check that the LOA is equal to the given value */
AFB_SESSION_LOA_SHIFT = 6, /* shift for LOA */
- AFB_SESSION_LOA_MASK = 3, /* mask for LOA */
+ AFB_SESSION_LOA_MASK = 7, /* mask for LOA */
AFB_SESSION_LOA_0 = 0, /* value for LOA of 0 */
AFB_SESSION_LOA_1 = 64, /* value for LOA of 1 */
AFB_SESSION_LOA_2 = 128, /* value for LOA of 2 */
AFB_SESSION_LOA_3 = 192, /* value for LOA of 3 */
+ AFB_SESSION_LOA_4 = 256, /* value for LOA of 4 */
AFB_SESSION_LOA_LE_0 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_0, /* check LOA <= 0 */
AFB_SESSION_LOA_LE_1 = AFB_SESSION_LOA_LE | AFB_SESSION_LOA_1, /* check LOA <= 1 */
return daemon.itf->get_system_bus(daemon.closure);
}
+/*
+ * Broadcasts widely the event of 'name' with the data 'object'.
+ * 'object' can be NULL.
+ * 'daemon' MUST be the daemon given in interface when activating the plugin.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'object'.
+ * Thus, in the case where 'object' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
+ */
+static inline void afb_daemon_broadcast_event(struct afb_daemon daemon, const char *name, struct json_object *object)
+{
+ return afb_event_sender_push(afb_daemon_get_event_sender(daemon), name, object);
+}
+
/*
* Send a message described by 'fmt' and following parameters
* to the journal for the verbosity 'level'.
* 'file' and 'line' are indicators of position of the code in source files.
* 'daemon' MUST be the daemon given in interface when activating the plugin.
*/
+static inline void afb_daemon_verbose(struct afb_daemon daemon, int level, const char *file, int line, const char *fmt, ...) __attribute__((format(printf, 5, 6)));
static inline void afb_daemon_verbose(struct afb_daemon daemon, int level, const char *file, int line, const char *fmt, ...)
{
va_list args;
}
#if !defined(NO_PLUGIN_VERBOSE_MACRO)
-# define ERROR(itf,...) do{if(itf->verbosity>=0)afb_daemon_verbose(itf->daemon,3,__FILE__,__LINE__,__VA_ARGS__);}while(0)
-# define WARNING(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,4,__FILE__,__LINE__,__VA_ARGS__);}while(0)
-# define NOTICE(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,5,__FILE__,__LINE__,__VA_ARGS__);}while(0)
-# define INFO(itf,...) do{if(itf->verbosity>=2)afb_daemon_verbose(itf->daemon,6,__FILE__,__LINE__,__VA_ARGS__);}while(0)
-# define DEBUG(itf,...) do{if(itf->verbosity>=3)afb_daemon_verbose(itf->daemon,7,__FILE__,__LINE__,__VA_ARGS__);}while(0)
+# if !defined(NO_PLUGIN_FILE_LINE_INDICATION)
+# define ERROR(itf,...) do{if(itf->verbosity>=0)afb_daemon_verbose(itf->daemon,3,__FILE__,__LINE__,__VA_ARGS__);}while(0)
+# define WARNING(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,4,__FILE__,__LINE__,__VA_ARGS__);}while(0)
+# define NOTICE(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,5,__FILE__,__LINE__,__VA_ARGS__);}while(0)
+# define INFO(itf,...) do{if(itf->verbosity>=2)afb_daemon_verbose(itf->daemon,6,__FILE__,__LINE__,__VA_ARGS__);}while(0)
+# define DEBUG(itf,...) do{if(itf->verbosity>=3)afb_daemon_verbose(itf->daemon,7,__FILE__,__LINE__,__VA_ARGS__);}while(0)
+# else
+# define ERROR(itf,...) do{if(itf->verbosity>=0)afb_daemon_verbose(itf->daemon,3,NULL,0,__VA_ARGS__);}while(0)
+# define WARNING(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,4,NULL,0,__VA_ARGS__);}while(0)
+# define NOTICE(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,5,NULL,0,__VA_ARGS__);}while(0)
+# define INFO(itf,...) do{if(itf->verbosity>=2)afb_daemon_verbose(itf->daemon,6,NULL,0,__VA_ARGS__);}while(0)
+# define DEBUG(itf,...) do{if(itf->verbosity>=3)afb_daemon_verbose(itf->daemon,7,NULL,0,__VA_ARGS__);}while(0)
+# endif
#endif
+
* The status of the reply is automatically set to "success".
* Its send the object 'obj' (can be NULL) with an
* informationnal comment 'info (can also be NULL).
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
*/
static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info)
{
/*
* Same as 'afb_req_success' but the 'info' is a formatting
* string followed by arguments.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
*/
static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...)
{
* Note that calling afb_req_fail("success", info) is equivalent
* to call afb_req_success(NULL, info). Thus even if possible it
* is strongly recommanded to NEVER use "success" for status.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
*/
static inline void afb_req_fail(struct afb_req req, const char *status, const char *info)
{
/*
* Same as 'afb_req_fail' but the 'info' is a formatting
* string followed by arguments.
+ *
+ * For conveniency, the function calls 'json_object_put' for 'obj'.
+ * Thus, in the case where 'obj' should remain available after
+ * the function returns, the function 'json_object_get' shall be used.
*/
static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...)
{
}
/*
- * Sets the level of authorisation of the session of 'req'
+ * Sets the level of assurance of the session of 'req'
* to 'level'. The effect of this function is subject of
* security policies.
* Returns 1 on success or 0 if failed.
/* 1 second should be sufficient to retrieve sink info */
gettimeofday (&tv_start, NULL);
gettimeofday (&tv_now, NULL);
- while (tv_now.tv_sec - tv_start.tv_sec <= 1) {
+ while (tv_now.tv_sec - tv_start.tv_sec <= 2) {
pa_mainloop_iterate (pa_loop, 0, &ret);
if (ret == -1) {
fprintf (stderr, "Stopping PulseAudio backend...\n");
return 0;
}
- if (ret >= 0) {
+
+ /* 0 and >100 are returned by PulseAudio itself */
+ if ((ret > 0)&&(ret < 100)) {
/* found a matching sink from callback */
- fprintf (stderr, "Success : using sink n.%d\n", error);
- ctx->audio_dev = (void*)dev_ctx_p[ret];
+ fprintf (stderr, "Success : using sink n.%d\n", ret-1);
+ ctx->audio_dev = (void*)dev_ctx_p[ret-1];
break;
}
gettimeofday (&tv_now, NULL);
return 0;
/* make the client context aware of current card state */
- ctx->mute = (unsigned char)dev_ctx_p[ret]->mute;
- ctx->channels = (unsigned int)dev_ctx_p[ret]->volume.channels;
+ ctx->mute = (unsigned char)dev_ctx_p[ret-1]->mute;
+ ctx->channels = (unsigned int)dev_ctx_p[ret-1]->volume.channels;
for (i = 0; i < ctx->channels; i++)
- ctx->volume[i] = dev_ctx_p[ret]->volume.values[i];
- ctx->idx = ret;
+ ctx->volume[i] = dev_ctx_p[ret-1]->volume.values[i];
+ ctx->idx = ret-1;
/* open matching sink for playback */
pa_spec = (pa_sample_spec*) malloc (sizeof(pa_sample_spec));
pa_spec->rate = 22050;
pa_spec->channels = (uint8_t)ctx->channels;
- if (!(pa = pa_simple_new (NULL, "afb-audio-plugin", PA_STREAM_PLAYBACK, dev_ctx_p[ret]->sink_name,
+ if (!(pa = pa_simple_new (NULL, "afb-audio-plugin", PA_STREAM_PLAYBACK, dev_ctx_p[ret-1]->sink_name,
"afb-audio-output", pa_spec, NULL, NULL, &error))) {
fprintf (stderr, "Error opening PulseAudio sink %s : %s\n",
- dev_ctx_p[ret]->sink_name, pa_strerror(error));
+ dev_ctx_p[ret-1]->sink_name, pa_strerror(error));
return 0;
}
- dev_ctx_p[ret]->pa = pa;
+ dev_ctx_p[ret-1]->pa = pa;
free (pa_spec);
client_count++;
client_count--;
if (client_count > 0) return;
- for (num = 0; num < (sizeof(dev_ctx_p)/sizeof(dev_ctx_pulse_T)); num++) {
+ for (num = 0; num < (sizeof(dev_ctx_p)/sizeof(dev_ctx_pulse_T*)); num++) {
for (i = 0; num < (sizeof(dev_ctx_p[num]->card_name)/sizeof(char*)); i++) {
free (dev_ctx_p[num]->card_name[i]);
int new_info, i, num = 0;
/* allocate the global alsa array */
- alsa_info = (alsa_info_T**) malloc (sizeof(alsa_info_T));
+ alsa_info = (alsa_info_T**) malloc (sizeof(alsa_info_T*));
alsa_info[0] = (alsa_info_T*) malloc (sizeof(alsa_info_T));
alsa_info[0]->device = NULL;
alsa_info[0]->synonyms = NULL;
if (found) card_name[found-card_name] = '\0';
/* was the card name already listed in the global alsa array ? */
- for (i = 0; i < (sizeof(alsa_info)/sizeof(alsa_info_T)); i++) {
+ for (i = 0; i < (sizeof(alsa_info)/sizeof(alsa_info_T*)); i++) {
if (alsa_info[i]->device &&
!strcmp (alsa_info[i]->device, card_name)) {
}
/* it was not ; create it */
if (new_info) {
- alsa_info = (alsa_info_T**) realloc (alsa_info, (num+1)*sizeof(alsa_info_T));
+ alsa_info = (alsa_info_T**) realloc (alsa_info, (num+1)*sizeof(alsa_info_T*));
alsa_info[num]->device = strdup (card_name);
asprintf (&alsa_info[num]->synonyms, ":%s", alsa_name);
num++;
asprintf (&needle, ":%s", name);
- for (num = 0; num < (sizeof(alsa_info)/sizeof(alsa_info_T)); num++) {
+ for (num = 0; num < (sizeof(alsa_info)/sizeof(alsa_info_T*)); num++) {
found = strstr (alsa_info[num]->synonyms, needle);
while (found) {
/* if next character is not ':' or '\0', we are wrong */
- if ((found[strlen(name)] != ':') && (found[strlen(name)] != '\0')) {
+ if ((found[strlen(name)+1] != ':') && (found[strlen(name)+1] != '\0')) {
found = strstr (found+1, needle);
continue;
}
found = strstr (alsa_info[num]->synonyms, ":");
while (found) {
next = strstr (found+1, ":");
+ if (!next) break;
cards = (char**) realloc (cards, (i+1)*sizeof(char*));
cards[i] = (char*) malloc (next-found+1);
strncpy (cards[i], found+1, next-found);
- cards[i][next-found] = '\0';
- i++;
+ cards[i][next-found-1] = '\0';
+ found = next; i++;
}
}
}
dev_ctx_pulse_T *dev_ctx_p_t = (dev_ctx_pulse_T *)data;
const char *device_string;
+ char *device, *found;
char **cards;
int num, i;
if (eol != 0)
return;
+ device_string = pa_proplist_gets (info->proplist, "device.string");
/* ignore sinks with no cards */
- if (!pa_proplist_contains (info->proplist, "device.string"))
+ if (!device_string)
return;
- device_string = pa_proplist_gets (info->proplist, "device.string");
-
/* was a sink with similar name already found ? */
- for (num = 0; num < (sizeof(dev_ctx_p)/sizeof(dev_ctx_pulse_T)); num++) {
+ for (num = 0; num < (sizeof(dev_ctx_p)/sizeof(dev_ctx_pulse_T*)); num++) {
if (dev_ctx_p[num]->sink_name &&
!strcmp (dev_ctx_p[num]->sink_name, info->name)) {
if (!strcmp (cards[i], dev_ctx_p_t->card_name[0])) {
/* it did : stop there and succeed */
fprintf (stderr, "Found matching sink : %s\n", info->name);
- pa_mainloop_quit (dev_ctx_p_t->pa_loop, num);
+ /* we return num+1 because '0' is already used */
+ pa_mainloop_quit (dev_ctx_p_t->pa_loop, num+1);
}
}
/* it did not, ignore and return */
}
num++;
+ /* remove ending ":0",":1"... in device name */
+ device = strdup (device_string);
+ found = strstr (device, ":");
+ if (found) device[found-device] = '\0';
+
/* new sink, find all the cards it manages, fail if none */
- cards = _pulse_find_cards (device_string);
- if (!cards) return;
+ cards = _pulse_find_cards (device);
+ free (device);
+ if (!cards)
+ return;
/* everything is well, register it in global array */
dev_ctx_p_t->sink_name = strdup (info->name);
if (!strcmp (cards[i], dev_ctx_p_t->card_name[0])) {
/* it did : stop there and succeed */
fprintf (stderr, "Found matching sink : %s\n", info->name);
- pa_mainloop_quit (dev_ctx_p_t->pa_loop, num);
+ /* we return num+1 because '0' is already used */
+ pa_mainloop_quit (dev_ctx_p_t->pa_loop, num+1);
}
}
}
{"create", AFB_SESSION_CREATE, myCreate , "Create a new session"},
{"action", AFB_SESSION_CHECK , myAction , "Use Session Context"},
{"close" , AFB_SESSION_CLOSE , myClose , "Free Context"},
- {"set_loa_0", AFB_SESSION_RENEW, clientSetLOA0 ,"Set level of authorisation to 0"},
- {"set_loa_1", AFB_SESSION_RENEW, clientSetLOA1 ,"Set level of authorisation to 1"},
- {"set_loa_2", AFB_SESSION_RENEW, clientSetLOA2 ,"Set level of authorisation to 2"},
- {"set_loa_3", AFB_SESSION_RENEW, clientSetLOA3 ,"Set level of authorisation to 3"},
- {"check_loa_ge_0", AFB_SESSION_LOA_GE_0, clientCheckLOA ,"Check whether level of authorisation is greater or equal to 0"},
- {"check_loa_ge_1", AFB_SESSION_LOA_GE_1, clientCheckLOA ,"Check whether level of authorisation is greater or equal to 1"},
- {"check_loa_ge_2", AFB_SESSION_LOA_GE_2, clientCheckLOA ,"Check whether level of authorisation is greater or equal to 2"},
- {"check_loa_ge_3", AFB_SESSION_LOA_GE_3, clientCheckLOA ,"Check whether level of authorisation is greater or equal to 3"},
- {"check_loa_le_0", AFB_SESSION_LOA_LE_0, clientCheckLOA ,"Check whether level of authorisation is lesser or equal to 0"},
- {"check_loa_le_1", AFB_SESSION_LOA_LE_1, clientCheckLOA ,"Check whether level of authorisation is lesser or equal to 1"},
- {"check_loa_le_2", AFB_SESSION_LOA_LE_2, clientCheckLOA ,"Check whether level of authorisation is lesser or equal to 2"},
- {"check_loa_le_3", AFB_SESSION_LOA_LE_3, clientCheckLOA ,"Check whether level of authorisation is lesser or equal to 3"},
- {"check_loa_eq_0", AFB_SESSION_LOA_EQ_0, clientCheckLOA ,"Check whether level of authorisation is equal to 0"},
- {"check_loa_eq_1", AFB_SESSION_LOA_EQ_1, clientCheckLOA ,"Check whether level of authorisation is equal to 1"},
- {"check_loa_eq_2", AFB_SESSION_LOA_EQ_2, clientCheckLOA ,"Check whether level of authorisation is equal to 2"},
- {"check_loa_eq_3", AFB_SESSION_LOA_EQ_3, clientCheckLOA ,"Check whether level of authorisation is equal to 3"},
+ {"set_loa_0", AFB_SESSION_RENEW, clientSetLOA0 ,"Set level of assurance to 0"},
+ {"set_loa_1", AFB_SESSION_RENEW, clientSetLOA1 ,"Set level of assurance to 1"},
+ {"set_loa_2", AFB_SESSION_RENEW, clientSetLOA2 ,"Set level of assurance to 2"},
+ {"set_loa_3", AFB_SESSION_RENEW, clientSetLOA3 ,"Set level of assurance to 3"},
+ {"check_loa_ge_0", AFB_SESSION_LOA_GE_0, clientCheckLOA ,"Check whether level of assurance is greater or equal to 0"},
+ {"check_loa_ge_1", AFB_SESSION_LOA_GE_1, clientCheckLOA ,"Check whether level of assurance is greater or equal to 1"},
+ {"check_loa_ge_2", AFB_SESSION_LOA_GE_2, clientCheckLOA ,"Check whether level of assurance is greater or equal to 2"},
+ {"check_loa_ge_3", AFB_SESSION_LOA_GE_3, clientCheckLOA ,"Check whether level of assurance is greater or equal to 3"},
+ {"check_loa_le_0", AFB_SESSION_LOA_LE_0, clientCheckLOA ,"Check whether level of assurance is lesser or equal to 0"},
+ {"check_loa_le_1", AFB_SESSION_LOA_LE_1, clientCheckLOA ,"Check whether level of assurance is lesser or equal to 1"},
+ {"check_loa_le_2", AFB_SESSION_LOA_LE_2, clientCheckLOA ,"Check whether level of assurance is lesser or equal to 2"},
+ {"check_loa_le_3", AFB_SESSION_LOA_LE_3, clientCheckLOA ,"Check whether level of assurance is lesser or equal to 3"},
+ {"check_loa_eq_0", AFB_SESSION_LOA_EQ_0, clientCheckLOA ,"Check whether level of assurance is equal to 0"},
+ {"check_loa_eq_1", AFB_SESSION_LOA_EQ_1, clientCheckLOA ,"Check whether level of assurance is equal to 1"},
+ {"check_loa_eq_2", AFB_SESSION_LOA_EQ_2, clientCheckLOA ,"Check whether level of assurance is equal to 2"},
+ {"check_loa_eq_3", AFB_SESSION_LOA_EQ_3, clientCheckLOA ,"Check whether level of assurance is equal to 3"},
{NULL}
};
static void pingEvent(struct afb_req request)
{
json_object *query = afb_req_json(request);
- afb_event_sender_push(afb_daemon_get_event_sender(interface->daemon), "event", query);
- ping(request, json_object_get(query), "event");
+ afb_daemon_broadcast_event(interface->daemon, "event", json_object_get(query));
+ ping(request, query, "event");
}
waiter = next;
}
- afb_event_sender_push(afb_daemon_get_event_sender(afbitf->daemon), reason, description);
+ afb_daemon_broadcast_event(afbitf->daemon, reason, description);
}
/*
board = board_of_req(req);
INFO(afbitf, "method 'move' called for boardid %d", board->id);
- /* retrieves the parameters of the move */
+ /* retrieves the arguments of the move */
index = afb_req_value(req, "index");
i = index == NULL ? -1 : atoi(index);
- /* checks validity of parameters */
+ /* checks validity of arguments */
if (i < 0 || i > 8) {
WARNING(afbitf, "can't move to %s: %s", index?:"?", index?"wrong value":"not set");
afb_req_fail(req, "error", "bad request");
}
/* applies the move */
- INFO(afbitf, "method 'move' for boardid %d, index=%d", board->id, index);
+ INFO(afbitf, "method 'move' for boardid %d, index=%s", board->id, index);
add_move(board, i);
/* replies */
board = board_of_req(req);
INFO(afbitf, "method 'level' called for boardid %d", board->id);
- /* retrieves the parameters */
+ /* retrieves the arguments */
level = afb_req_value(req, "level");
l = level == NULL ? -1 : atoi(level);
- /* check validity of parameters */
+ /* check validity of arguments */
if (l < 1 || l > 10) {
WARNING(afbitf, "can't set level to %s: %s", level?:"?", level?"wrong value":"not set");
afb_req_fail(req, "error", "bad request");
board = board_of_req(req);
INFO(afbitf, "method 'join' called for boardid %d", board->id);
- /* retrieves the parameters */
+ /* retrieves the arguments */
id = afb_req_value(req, "boardid");
if (id == NULL)
goto bad_request;
static void wait(struct afb_req req)
{
- int count;
struct board *board;
struct waiter *waiter;
board = board_of_req(req);
INFO(afbitf, "method 'wait' called for boardid %d", board->id);
- /* counts the waiters */
- count = 0;
- waiter = board->waiters;
- while (waiter != NULL) {
- count++;
- waiter = waiter->next;
- }
-
- /* checks ability to wait */
- if (count + 1 >= board->use_count) {
- WARNING(afbitf, "can't wait: count=%d and use_count=%d", count, board->use_count);
- afb_req_fail(req, "error", "can't wait");
- return;
- }
-
/* creates the waiter and enqueues it */
waiter = calloc(1, sizeof *waiter);
waiter->req = req;
/*
* array of the verbs exported to afb-daemon
*/
-static const struct AFB_verb_desc_v1 verbs[] = {
+static const struct AFB_verb_desc_v1 plugin_verbs[] = {
/* VERB'S NAME SESSION MANAGEMENT FUNCTION TO CALL SHORT DESCRIPTION */
{ .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" },
- { .name= "play", .session= AFB_SESSION_NONE, .callback= play, .info= "Tells the server to play" },
+ { .name= "play", .session= AFB_SESSION_NONE, .callback= play, .info= "Asks the server to play" },
{ .name= "move", .session= AFB_SESSION_NONE, .callback= move, .info= "Tells the client move" },
{ .name= "board", .session= AFB_SESSION_NONE, .callback= board, .info= "Get the current board" },
{ .name= "level", .session= AFB_SESSION_NONE, .callback= level, .info= "Set the server level" },
{ .name= "join", .session= AFB_SESSION_CHECK,.callback= join, .info= "Join a board" },
{ .name= "undo", .session= AFB_SESSION_NONE, .callback= undo, .info= "Undo the last move" },
{ .name= "wait", .session= AFB_SESSION_NONE, .callback= wait, .info= "Wait for a change" },
- /* marker for end of the array */
- { .name= NULL }
+ { .name= NULL } /* marker for end of the array */
};
/*
.v1= { /* fills the v1 field of the union when AFB_PLUGIN_VERSION_1 */
.prefix= "tictactoe", /* the API name (or plugin name or prefix) */
.info= "Sample tac-tac-toe game", /* short description of of the plugin */
- .verbs = verbs /* the array describing the verbs of the API */
+ .verbs = plugin_verbs /* the array describing the verbs of the API */
}
};
websock.c
)
+###########################################
+# build and install afb-daemon
+###########################################
ADD_EXECUTABLE(afb-daemon main.c)
TARGET_LINK_LIBRARIES(afb-daemon
afb-lib
INSTALL(TARGETS afb-daemon
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+###########################################
+# build and install libafbwsc
+###########################################
+ADD_LIBRARY(afbwsc SHARED afb-ws.c afb-ws-client.c afb-wsj1.c websock.c afb-common.c)
+TARGET_LINK_LIBRARIES(afbwsc
+ ${libsystemd_LIBRARIES}
+ -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/export-afbwsc.map
+ -Wl,--as-needed
+ -Wl,--gc-sections
+)
+INSTALL(TARGETS afbwsc LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
+INSTALL(FILES afb-wsj1.h afb-ws-client.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/afb)
+
+###########################################
+# build and install afb-client-demo
+###########################################
ADD_EXECUTABLE(afb-client-demo afb-client-demo.c)
TARGET_LINK_LIBRARIES(afb-client-demo
- afb-lib
+ afbwsc
${link_libraries}
${libsystemd_LIBRARIES}
)
INSTALL(TARGETS afb-client-demo
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+
desc->interface.daemon.closure = desc;
/* init the plugin */
+ NOTICE("plugin [%s] calling registering function %s", path, plugin_register_function_v1);
desc->plugin = pluginAfbV1RegisterFct(&desc->interface);
if (desc->plugin == NULL) {
ERROR("plugin [%s] register function failed. continuing...", path);
#include <systemd/sd-event.h>
-#include "afb-common.h"
+#include "afb-common.h" /* TODO: remove dependency to afb-common.h */
#include "afb-wsj1.h"
#include "afb-ws-client.h"
--- /dev/null
+{
+global:
+ afb_ws_client_connect_wsj1;
+ afb_wsj1_*;
+ afb_common_*;
+local:
+ *;
+};
+
extern int verbosity;
extern void verbose_set_name(const char *name, int authority);
-extern void verbose(int level, const char *file, int line, const char *fmt, ...);
+extern void verbose(int level, const char *file, int line, const char *fmt, ...) __attribute__((format(printf, 4, 5)));
extern void vverbose(int level, const char *file, int line, const char *fmt, va_list args);
# define ERROR(...) do{if(verbosity>=0)verbose(3,__FILE__,__LINE__,__VA_ARGS__);}while(0)
<h2>Sample Post File</h2>
<form enctype="multipart/form-data">
- <input type="file" name="select input file" />
+ <input type="file" name="file"/>
<input type="hidden" name="hidden" value="bollobollo" />
<br>
<button formmethod="POST" formaction="api/post/upload-image">Post File</button>
</body>
-</html>
\ No newline at end of file
+</html>
Code Review / src / app-framework-binder.git / commitdiff