-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>
+Date: 09 juin 2016
+Author: José Bollo</code></pre>
+<h2 id="summary">Summary</h2>
+<p>Afb-daemon binders serve files through HTTP protocol and offers to developers the capability to expose application API methods through HTTP or WebSocket protocol.</p>
+<p>Binder plugins are used to add API to afb-daemon. This part describes how to write a plugin for afb-daemon.</p>
+<p>Excepting this summary, this document target developers.</p>
+<p>Before moving further through an example, here after a short overview of binder plugins fundamentals.</p>
+<h3 id="nature-of-a-plugin">Nature of a plugin</h3>
+<p>A plugin is an independent piece of software. A plugin is self contain and exposes application logic as sharable library. A plugin is intended to be dynamically loaded by afb-daemon to expose application API.</p>
+<p>Technically, a binder plugin does not reference and is not linked with any afb-daemon library.</p>
+<h3 id="class-of-plugins">Class of plugins</h3>
+<p>Application binder supports two kinds of plugins: application plugins and service plugins. Technically both class of plugin are equivalent are use the same coding convention. Only sharing mode and security context diverge.</p>
+<h4 id="application-plugins">Application-plugins</h4>
+<p>Application-plugins implements the glue in between application's UI and services. Every AGL application has a corresponding binder that typically activates one or many plugins to interface the application logic with lower platform services. When an application is started by the AGL application framework, a dedicate binder is started that loads/activates application plugin(s). API expose by application-plugin are executed within corresponding application security context.</p>
+<p>Application plugins generally handle a unique context for a unique client. As the application framework start a dedicated instance of afb_daemon for each AGL application, if a given plugin is used within multiple application each of those application get a new and private instance of eventually "shared" plugin.</p>
+<h4 id="service-plugins">Service-plugins</h4>
+<p>Service-plugins enable API activation within corresponding service security context and not within calling application context. Service-plugins are intended to run as a unique instance. Service-plugins can be shared in between multiple clients.</p>
+<p>Service-plugins can either be stateless or manage client context. When managing context each client get a private context.</p>
+<p>Sharing may either be global to the platform (ie: GPS service) or dedicated to a given user (ie: user preferences)</p>
+<h3 id="live-cycle-of-plugins-within-afb-daemon">Live cycle of plugins within afb-daemon</h3>
+<p>Application and service plugins are loaded and activated each time a new afb-daemon is started.</p>
+<p>At launch time, every loaded plugin initialise itself. If a single plugin initialisation fail corresponding instance of afb-daemon self aborts.</p>
+<p>Conversely, when a plugin initialisation succeeds, it should register its unique name as well as the list of verbs attached to the methods it exposes.</p>
+<p>When initialised, on request from application clients to the right API/verb, plugin methods are activated by the afb-daemon attached to the application or service.</p>
+<p>At exit time, no special action is enforced by afb-daemon. When a specific actions is required at afb-daemon stop, developers should use 'atexit/on_exit' during plugin initialisation sequence to register a custom exit function.</p>
+<h3 id="plugin-contend">Plugin Contend</h3>
+<p>Afb-daemon's plugin register two classes of objects: names and functions.</p>
+<p>Plugins declare categories of names: - A unique plugin name to access all API expose by this plugin, - One name for each methods/verbs provided by this plugin.</p>
+<p>Plugins declare two categories of functions: - function use for the initialisation - functions implementing exposed API methods</p>
+<p>Afb-daemon parses URI requests to extract the API(plugin name) and the VERB(method to activate). As an example, URI <strong>foo/bar</strong> translates to plugin named <strong>foo</strong> and method named <strong>bar</strong>. To serve such a request, afb-daemon looks for an active plugin named <strong>foo</strong> and then within this plugin for a method named <strong>bar</strong>. When find afb-daemon calls corresponding method with attached parameter if any.</p>
+<p>Afb-daemon ignores letter case when parsing URI. Thus <strong>TicTacToe/Board</strong> and <strong>tictactoe/board</strong> are equivalent.</p>
+<h4 id="the-name-of-the-plugin">The name of the plugin</h4>
+<p>The name of a given plugin is also known as the name of the API prefix that defines the plugin.</p>
+<p>The name of a plugin SHOULD be unique within a given afb-daemon instance.</p>
+<p>For example, when a client of afb-daemon calls a URI named <strong>foo/bar</strong>. Afb-daemon extracts the prefix <strong>foo</strong> and the suffix <strong>bar</strong>. <strong>foo</strong> must match a plugin name and <strong>bar</strong> a VERB attached to some method.</p>
+<h4 id="names-of-methods">Names of methods</h4>
+<p>Each plugin exposes a set of methods that can be called by the clients of a given afb-daemon.</p>
+<p>VERB's name attached to a given plugin (API) MUST be unique within a plugin.</p>
+<p>Plugins static declaration link VERBS to corresponding methods. When clients emit requests on a given API/VERB corresponding method is called by afb-daemon.</p>
+<h4 id="initialisation-function">Initialisation function</h4>
+<p>Plugin's initialisation function serves several purposes.</p>
+<ol type="1">
+<li><p>It allows afb-daemon to control plugin version depending on initialisation function name. As today, the only supported initialisation function is <strong>pluginAfbV1Register</strong>. This identifies version "one" of plugins.</p></li>
+<li><p>It allows plugins to initialise itself.</p></li>
+<li><p>It enables names declarations: descriptions, requirements and implementations of exposed API/VERB.</p></li>