diff options
| -rw-r--r-- | CMakeLists.txt | 5 | ||||
| -rw-r--r-- | afb-wsc.pc.in | 31 | ||||
| -rw-r--r-- | doc/FAQ.html | 2 | ||||
| -rw-r--r-- | doc/FAQ.md | 2 | ||||
| -rw-r--r-- | doc/afb-daemon-vocabulary.html | 76 | ||||
| -rw-r--r-- | doc/afb-daemon-vocabulary.md | 64 | ||||
| -rw-r--r-- | doc/afb-plugin-writing.html | 1542 | ||||
| -rw-r--r-- | doc/afb-plugin-writing.md | 1222 | ||||
| -rw-r--r-- | doc/doc.css | 30 | ||||
| -rwxr-xr-x | doc/updt.sh | 40 | ||||
| -rw-r--r-- | doc/writing-afb-plugins.html | 482 | ||||
| -rw-r--r-- | doc/writing-afb-plugins.md | 489 | ||||
| -rw-r--r-- | include/afb/afb-plugin.h | 49 | ||||
| -rw-r--r-- | include/afb/afb-req-itf.h | 18 | ||||
| -rw-r--r-- | plugins/audio/audio-pulse.c | 66 | ||||
| -rw-r--r-- | plugins/samples/ClientCtx.c | 32 | ||||
| -rw-r--r-- | plugins/samples/HelloWorld.c | 4 | ||||
| -rw-r--r-- | plugins/samples/tic-tac-toe.c | 39 | ||||
| -rw-r--r-- | src/CMakeLists.txt | 23 | ||||
| -rw-r--r-- | src/afb-api-so.c | 1 | ||||
| -rw-r--r-- | src/afb-client-demo.c | 2 | ||||
| -rw-r--r-- | src/export-afbwsc.map | 9 | ||||
| -rw-r--r-- | src/verbose.h | 2 | ||||
| -rw-r--r-- | test/sample-post.html | 4 |
24 files changed, 3137 insertions, 1097 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index d3b7a32d..c5094bb8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -25,7 +25,6 @@ add_compile_options(-Wno-sign-compare -Wno-sign-conversion) 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) @@ -68,11 +67,13 @@ ADD_SUBDIRECTORY(include) 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 ) diff --git a/afb-wsc.pc.in b/afb-wsc.pc.in new file mode 100644 index 00000000..a8b29d71 --- /dev/null +++ b/afb-wsc.pc.in @@ -0,0 +1,31 @@ +## +## 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 + diff --git a/doc/FAQ.html b/doc/FAQ.html index 4ebefaa3..98337815 100644 --- a/doc/FAQ.html +++ b/doc/FAQ.html @@ -8,7 +8,7 @@ <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> @@ -1,7 +1,7 @@ Frequently Asked Question about AFB-DAEMON ========================================== version: 1 - Date: 24 mai 2016 + Date: 27 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE diff --git a/doc/afb-daemon-vocabulary.html b/doc/afb-daemon-vocabulary.html index b398aa33..fadd1dee 100644 --- a/doc/afb-daemon-vocabulary.html +++ b/doc/afb-daemon-vocabulary.html @@ -8,16 +8,15 @@ <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> @@ -25,41 +24,83 @@ Author: José Bollo <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> @@ -68,10 +109,23 @@ Author: José Bollo <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> diff --git a/doc/afb-daemon-vocabulary.md b/doc/afb-daemon-vocabulary.md index 7a4b6537..8427b736 100644 --- a/doc/afb-daemon-vocabulary.md +++ b/doc/afb-daemon-vocabulary.md @@ -1,31 +1,72 @@ 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 @@ -34,6 +75,19 @@ It stand for Universal Unic IDentifier. Its is designed to create identifier in a way that avoid has much as possible conflicts. It means that if two differents instance create a UUID, the probability that they create the same UUID is very low, near to zero. +## x-afb-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. + diff --git a/doc/afb-plugin-writing.html b/doc/afb-plugin-writing.html new file mode 100644 index 00000000..20e25972 --- /dev/null +++ b/doc/afb-plugin-writing.html @@ -0,0 +1,1542 @@ +<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> diff --git a/doc/afb-plugin-writing.md b/doc/afb-plugin-writing.md new file mode 100644 index 00000000..486b141d --- /dev/null +++ b/doc/afb-plugin-writing.md @@ -0,0 +1,1222 @@ +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 " + diff --git a/doc/doc.css b/doc/doc.css index c11082fd..27be9dc7 100644 --- a/doc/doc.css +++ b/doc/doc.css @@ -4,12 +4,36 @@ body { 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; } diff --git a/doc/updt.sh b/doc/updt.sh index cd978e22..af64e31e 100755 --- a/doc/updt.sh +++ b/doc/updt.sh @@ -1,9 +1,6 @@ -#!/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"> @@ -14,18 +11,37 @@ GENERATED-MARKDOWN-HERE </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 diff --git a/doc/writing-afb-plugins.html b/doc/writing-afb-plugins.html deleted file mode 100644 index 5aeca0a5..00000000 --- a/doc/writing-afb-plugins.html +++ /dev/null @@ -1,482 +0,0 @@ -<html> -<head> - <link rel="stylesheet" type="text/css" href="doc.css"> - <meta charset="UTF-8"> -</head> -<body> -<a name="HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON"></a> -<h1>HOWTO WRITE a PLUGIN for AFB-DAEMON</h1> - -<pre><code>version: 1 -Date: 24 mai 2016 -Author: José Bollo -</code></pre> - -<p><ul> - <li><a href="#HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</a> - <ul> - <li><a href="#Summary">Summary</a> - <ul> - <li><a href="#Nature.of.a.plugin">Nature of a plugin</a></li> - <li><a href="#Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</a></li> - <li><a href="#Content.of.a.plugin">Content of a plugin</a> - <ul> - <li><a href="#The.name.of.the.plugin">The name of the plugin</a></li> - <li><a href="#Names.of.verbs">Names of verbs</a></li> - <li><a href="#The.initialisation.function">The initialisation function</a></li> - <li><a href="#Functions.implementing.verbs">Functions implementing verbs</a> -</li> - </ul> - </li> - </ul> - </li> - <li><a href="#The.Tic-Tac-Toe.example">The Tic-Tac-Toe example</a></li> - <li><a href="#Choosing.names">Choosing names</a> - <ul> - <li><a href="#Names.for.API..plugin.">Names for API (plugin)</a></li> - <li><a href="#Names.for.verbs">Names for verbs</a></li> - <li><a href="#Names.for.arguments">Names for arguments</a></li> - <li><a href="#Forging.names.widely.available">Forging names widely available</a></li> - </ul> - </li> - <li><a href="#Options.to.set.when.compiling.plugins">Options to set when compiling plugins</a></li> - <li><a href="#Header.files.to.include">Header files to include</a></li> - <li><a href="#Writing.a.synchronous.verb.implementation">Writing a synchronous verb implementation</a> - <ul> - <li><a href="#The.incoming.request">The incoming request</a></li> - <li><a href="#Associating.an.object.to.the.session.for.the.plugin">Associating an object to the session for the plugin</a></li> - <li><a href="#Sending.the.reply.to.a.request">Sending the reply to a request</a></li> - </ul> - </li> - <li><a href="#Getting.argument.of.invocation">Getting argument of invocation</a></li> - <li><a href="#How.to.build.a.plugin">How to build a plugin</a></li> - </ul> - </li> -</ul></p> - -<a name="Summary"></a> -<h2>Summary</h2> - -<p>The binder afb-daemon serves files through -the HTTP protocol and offers access to API’s through -HTTP or WebSocket protocol.</p> - -<p>The plugins are used to add API’s to afb-daemon. -This part describes how to write a plugin for afb-daemon. -Excepting this summary, this part is intended to be read -by developpers.</p> - -<p>Before going into details, through a tiny example, -a short overview plugins basis is needed.</p> - -<a name="Nature.of.a.plugin"></a> -<h3>Nature of a plugin</h3> - -<p>A plugin is a separate piece of code made of a shared library. -The plugin is loaded and activated by afb-daemon when afb-daemon -starts.</p> - -<p>Technically, a plugin is not linked to any library of afb-daemon.</p> - -<a name="Live.cycle.of.a.plugin.within.afb-daemon"></a> -<h3>Live cycle of a plugin within afb-daemon</h3> - -<p>The plugins are loaded and activated when afb-daemon starts.</p> - -<p>At start, the plugin initialise itself. -If it fails to initialise then afb-daemon stops.</p> - -<p>Conversely, if it success to initialize, it must declare -a name, that must be unique, and a list of API’s verbs.</p> - -<p>When initialized, the functions implementing the API’s verbs -of the plugin are activated on call.</p> - -<p>At the end, nothing special is done by afb-daemon. -Consequently, developpers of plugins should use ‘atexit’ -or ‘on_exit’ during initialisation if they need to -perform specific actions when stopping.</p> - -<a name="Content.of.a.plugin"></a> -<h3>Content of a plugin</h3> - -<p>For afb-daemon, a plugin contains 2 different -things: names and functions.</p> - -<p>There is two kind of names: - - the name of the plugin, - - the names of the verbs.</p> - -<p>There is two kind of functions: - - the initialisation function - - functions implementing verbs</p> - -<p>Afb-daemon translates the name of the method that is -invoked to a pair of API and verb names. For example, -the method named <strong>foo/bar</strong> translated to the API -name <strong>foo</strong> and the verb name <strong>bar</strong>. -To serve it, afb-daemon search the plugin that record -the name <strong>foo</strong> and if it also recorded the verb <strong>bar</strong>, -it calls the implementation function declared for this verb.</p> - -<p>Afb-daemon make no distinction between lower case -and upper case when searching for a method. -Thus, The names <strong>TicTacToe/Board</strong> and <strong>tictactoe/borad</strong> -are equals.</p> - -<a name="The.name.of.the.plugin"></a> -<h4>The name of the plugin</h4> - -<p>The name of the plugin is also known as the name -of the API that defines the plugin.</p> - -<p>This name is also known as the prefix.</p> - -<p>The name of a plugin MUST be unique within afb-daemon.</p> - -<p>For example, when a client of afb-daemon -calls a method named <strong>foo/bar</strong>. Afb-daemon -extracts the prefix <strong>foo</strong> and the suffix <strong>bar</strong>. -<strong>foo</strong> is the API name and must match a plugin name, -the plugin that implements the verb <strong>bar</strong>.</p> - -<a name="Names.of.verbs"></a> -<h4>Names of verbs</h4> - -<p>Each plugin exposes a set of verbs that can be called -by client of afb-daemon.</p> - -<p>The name of a verb MUST be unique within a plugin.</p> - -<p>Plugins link verbs to functions that are called -when clients emit requests for that verb.</p> - -<p>For example, when a client of afb-daemon -calls a method named <strong>foo/bar</strong>.</p> - -<a name="The.initialisation.function"></a> -<h4>The initialisation function</h4> - -<p>The initialisation function serves several purposes.</p> - -<ol> -<li><p>It allows afb-daemon to check the version -of the plugin using the name of the initialisation -functions that it found. Currently, the initialisation -function is named <strong>pluginAfbV1Register</strong>. It identifies -the first version of plugins.</p></li> -<li><p>It allows the plugin to initialise itself.</p></li> -<li><p>It serves to the plugin to declare names, descriptions, -requirements and implmentations of the verbs that it exposes.</p></li> -</ol> - - -<a name="Functions.implementing.verbs"></a> -<h4>Functions implementing verbs</h4> - -<p>When a method is called, afb-daemon constructs a request -object and pass it to the implementation function for verb -within the plugin of the API.</p> - -<p>An implementation function receives a request object that -is used to get arguments of the request, to send -answer, to store session data.</p> - -<p>A plugin MUST send an answer to the request.</p> - -<p>But it is not mandatory to send the answer -before to return from the implementing function. -This behaviour is important for implementing -asynchronous actions.</p> - -<p>Implementation functions that always reply to the request -before returning are named <em>synchronous implementations</em>. -Those that don’t always reply to the request before -returning are named <em>asynchronous implementations</em>.</p> - -<p>Asynchronous implementations typically initiate an -asynchronous action and record to send the reply -on completion of this action.</p> - -<a name="The.Tic-Tac-Toe.example"></a> -<h2>The Tic-Tac-Toe example</h2> - -<p>This part explains how to write an afb-plugin. -For the sake of being practical we will use many -examples from the tic-tac-toe example. -This plugin example is in <em>plugins/samples/tic-tac-toe.c</em>.</p> - -<p>This plugin is named <strong><em>tictactoe</em></strong>.</p> - -<a name="Choosing.names"></a> -<h2>Choosing names</h2> - -<p>The designer of a plugin must defines names for its plugin -(or its API) and for the verbs of its API. He also -must defines names for arguments given by name.</p> - -<p>While forging names, the designer should take into account -the rules for making valid names and some rules that make -the names easy to use across plaforms.</p> - -<p>The names and strings used ALL are UTF-8 encoded.</p> - -<a name="Names.for.API..plugin."></a> -<h3>Names for API (plugin)</h3> - -<p>The names of the API are checked. -All characters are authorised except:</p> - -<ul> -<li>the control characters (\u0000 .. \u001f)</li> -<li>the characters of the set { ‘ ’, ‘“’, ‘#’, ‘%’, ‘&’, -‘’‘, ’/‘, ’?‘, ’`‘, ’\x7f' }</li> -</ul> - - -<p>In other words the set of forbidden characters is -{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027, - \u002f, \u003f, \u0060, \u007f }.</p> - -<p>Afb-daemon make no distinction between lower case -and upper case when searching for an API by its name.</p> - -<a name="Names.for.verbs"></a> -<h3>Names for verbs</h3> - -<p>The names of the verbs are not checked.</p> - -<p>However, the validity rules for verb’s names are the -same as for API’s names except that the dot (.) character -is forbidden.</p> - -<p>Afb-daemon make no distinction between lower case -and upper case when searching for an API by its name.</p> - -<a name="Names.for.arguments"></a> -<h3>Names for arguments</h3> - -<p>The names for arguments are not restricted and can be -anything.</p> - -<p>The arguments are searched with the case sensitive -string comparison. Thus the names “index” and “Index” -are not the same.</p> - -<a name="Forging.names.widely.available"></a> -<h3>Forging names widely available</h3> - -<p>The key names of javascript object can be almost -anything using the arrayed notation:</p> - -<pre><code>object[key] = value -</code></pre> - -<p>That is not the case with the dot notation:</p> - -<pre><code>object.key = value -</code></pre> - -<p>Using the dot notation, the key must be a valid javascript -identifier.</p> - -<p>For this reason, the chosen names should better be -valid javascript identifier.</p> - -<p>It is also a good practice, even for arguments, to not -rely on the case sensitivity and to avoid the use of -names different only by the case.</p> - -<a name="Options.to.set.when.compiling.plugins"></a> -<h2>Options to set when compiling plugins</h2> - -<p>Afb-daemon provides a configuration file for <em>pkg-config</em>. -Typing the command</p> - -<pre><code>pkg-config --cflags afb-daemon -</code></pre> - -<p>will print the flags to use for compiling, like this:</p> - -<pre><code>$ pkg-config --cflags afb-daemon --I/opt/local/include -I/usr/include/json-c -</code></pre> - -<p>For linking, you should use</p> - -<pre><code>$ pkg-config --libs afb-daemon --ljson-c -</code></pre> - -<p>As you see, afb-daemon automatically includes dependency to json-c. -This is done through the <strong>Requires</strong> keyword of pkg-config.</p> - -<p>If this behaviour is a problem, let us know.</p> - -<a name="Header.files.to.include"></a> -<h2>Header files to include</h2> - -<p>The plugin <em>tictactoe</em> has the following lines for its includes:</p> - -<pre><code>#define _GNU_SOURCE -#include <stdio.h> -#include <string.h> -#include <json-c/json.h> -#include <afb/afb-plugin.h> -</code></pre> - -<p>The header <em>afb/afb-plugin.h</em> includes all the features that a plugin -needs except two foreign header that must be included by the plugin -if it needs it:</p> - -<ul> -<li><em>json-c/json.h</em>: this header must be include to handle json objects;</li> -<li><em>systemd/sd-event.h</em>: this must be include to access the main loop;</li> -<li><em>systemd/sd-bus.h</em>: this may be include to use dbus connections.</li> -</ul> - - -<p>The <em>tictactoe</em> plugin does not use systemd features so it is not included.</p> - -<p>When including <em>afb/afb-plugin.h</em>, the macro <strong>_GNU_SOURCE</strong> must be -defined.</p> - -<a name="Writing.a.synchronous.verb.implementation"></a> -<h2>Writing a synchronous verb implementation</h2> - -<p>The verb <strong>tictactoe/board</strong> is a synchronous implementation. -Here is its listing:</p> - -<pre><code>/* - * get the board - */ -static void board(struct afb_req req) -{ - struct board *board; - struct json_object *description; - - /* retrieves the context for the session */ - board = board_of_req(req); - INFO(afbitf, "method 'board' called for boardid %d", board->id); - - /* describe the board */ - description = describe(board); - - /* send the board's description */ - afb_req_success(req, description, NULL); -} -</code></pre> - -<p>This examples show many aspects of writing a synchronous -verb implementation.</p> - -<a name="The.incoming.request"></a> -<h3>The incoming request</h3> - -<p>For any implementation, the request is received by a structure of type -<strong>struct afb_req</strong>.</p> - -<p><strong><em>Important: note that this is a PLAIN structure, not a pointer to a structure.</em></strong></p> - -<p>This structure, here named <em>req</em>, is used</p> - -<p><em>req</em> is used to get arguments of the request, to send -answer, to store session data.</p> - -<p>This object and its interface is defined and documented -in the file names <em>afb/afb-req-itf.h</em></p> - -<p>The above example uses 2 times the request object <em>req</em>.</p> - -<p>The first time, it is used for retrieving the board attached to -the session of the request.</p> - -<p>The second time, it is used to send the reply: an object that -describes the current board.</p> - -<a name="Associating.an.object.to.the.session.for.the.plugin"></a> -<h3>Associating an object to the session for the plugin</h3> - -<p>When the plugin <em>tic-tac-toe</em> receives a request, it musts regain -the board that describes the game associated to the session.</p> - -<p>For a plugin, having data associated to a session is a common case. -This data is called the context of the plugin for the session. -For the plugin <em>tic-tac-toe</em>, the context is the board.</p> - -<p>The requests <em>afb_req</em> offer four functions for -storing and retrieving the context associated to the session.</p> - -<p>These functions are:</p> - -<ul> -<li><p><strong>afb_req_context_get</strong>: -retrieves the context data stored for the plugin.</p></li> -<li><p><strong>afb_req_context_set</strong>: -store the context data of the plugin.</p></li> -<li><p><strong>afb_req_context</strong>: -retrieves the context data of the plugin, -if needed, creates the context and store it.</p></li> -<li><p><strong>afb_req_context_clear</strong>: -reset the stored data.</p></li> -</ul> - - -<p>The plugin <em>tictactoe</em> use a convenient function to retrieve -its context: the board. This function is <em>board_of_req</em>:</p> - -<pre><code>/* - * retrieves the board of the request - */ -static inline struct board *board_of_req(struct afb_req req) -{ - return afb_req_context(req, (void*)get_new_board, (void*)release_board); -} -</code></pre> - -<p>This function is very simple because it merely wraps -a call to the function <strong>afb_req_context</strong>, providing -all needed arguments. -The casts are required to avoid a warning when compiling.</p> - -<p>Here is the definition of the function <strong>afb_req_context</strong></p> - -<pre><code>/* - * Gets the pointer stored by the plugin for the session of 'req'. - * If the stored pointer is NULL, indicating that no pointer was - * already stored, afb_req_context creates a new context by calling - * the function 'create_context' and stores it with the freeing function - * 'free_context'. - */ -static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*)) -{ - void *result = afb_req_context_get(req); - if (result == NULL) { - result = create_context(); - afb_req_context_set(req, result, free_context); - } - return result; -} -</code></pre> - -<p>This powerful function ensures that the context exists and is -stored for the session.</p> - -<p>The function <strong>get_new_board</strong> creates a new board and set its -count of use to 1. The boards are counting their count of use -to free there ressources when no more used.</p> - -<p>The function <strong>release_board</strong></p> - -<a name="Sending.the.reply.to.a.request"></a> -<h3>Sending the reply to a request</h3> - -<a name="Getting.argument.of.invocation"></a> -<h2>Getting argument of invocation</h2> - -<a name="How.to.build.a.plugin"></a> -<h2>How to build a plugin</h2> - -<p>Afb-daemon provides a The packaging of afb-daemon</p> -</body> -</html> diff --git a/doc/writing-afb-plugins.md b/doc/writing-afb-plugins.md deleted file mode 100644 index ba2e676a..00000000 --- a/doc/writing-afb-plugins.md +++ /dev/null @@ -1,489 +0,0 @@ -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. - - diff --git a/include/afb/afb-plugin.h b/include/afb/afb-plugin.h index 6f5cd08c..2b065b08 100644 --- a/include/afb/afb-plugin.h +++ b/include/afb/afb-plugin.h @@ -51,28 +51,29 @@ enum AFB_plugin_version }; /* - * 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 */ @@ -208,11 +209,26 @@ static inline struct sd_bus *afb_daemon_get_system_bus(struct afb_daemon daemon) } /* + * 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; @@ -222,9 +238,18 @@ static inline void afb_daemon_verbose(struct afb_daemon daemon, int level, const } #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 + diff --git a/include/afb/afb-req-itf.h b/include/afb/afb-req-itf.h index 8530e05d..f4fab551 100644 --- a/include/afb/afb-req-itf.h +++ b/include/afb/afb-req-itf.h @@ -130,6 +130,10 @@ static inline struct json_object *afb_req_json(struct afb_req 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. */ static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info) { @@ -139,6 +143,10 @@ static inline void afb_req_success(struct afb_req req, struct json_object *obj, /* * 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, ...) { @@ -160,6 +168,10 @@ static inline void afb_req_success_f(struct afb_req req, struct json_object *obj * 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) { @@ -169,6 +181,10 @@ static inline void afb_req_fail(struct afb_req req, const char *status, const ch /* * 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, ...) { @@ -259,7 +275,7 @@ static inline void afb_req_session_close(struct afb_req req) } /* - * 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. diff --git a/plugins/audio/audio-pulse.c b/plugins/audio/audio-pulse.c index 7f511be1..739b3774 100644 --- a/plugins/audio/audio-pulse.c +++ b/plugins/audio/audio-pulse.c @@ -58,17 +58,19 @@ unsigned char _pulse_init (const char *name, audioCtxHandleT *ctx) { /* 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); @@ -78,11 +80,11 @@ unsigned char _pulse_init (const char *name, audioCtxHandleT *ctx) { 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)); @@ -90,13 +92,13 @@ unsigned char _pulse_init (const char *name, audioCtxHandleT *ctx) { 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++; @@ -113,7 +115,7 @@ void _pulse_free (audioCtxHandleT *ctx) { 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]); @@ -245,7 +247,7 @@ void _pulse_enumerate_cards () { 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; @@ -276,7 +278,7 @@ void _pulse_enumerate_cards () { 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)) { @@ -288,7 +290,7 @@ void _pulse_enumerate_cards () { } /* 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++; @@ -309,12 +311,12 @@ char** _pulse_find_cards (const char *name) { 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; } @@ -322,11 +324,12 @@ char** _pulse_find_cards (const char *name) { 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++; } } } @@ -356,20 +359,20 @@ void _pulse_sink_list_cb (pa_context *context, const pa_sink_info *info, 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)) { @@ -379,7 +382,8 @@ void _pulse_sink_list_cb (pa_context *context, const pa_sink_info *info, 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 */ @@ -388,9 +392,16 @@ void _pulse_sink_list_cb (pa_context *context, const pa_sink_info *info, } 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); @@ -406,7 +417,8 @@ void _pulse_sink_list_cb (pa_context *context, const pa_sink_info *info, 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); } } } diff --git a/plugins/samples/ClientCtx.c b/plugins/samples/ClientCtx.c index 353185c3..ef703759 100644 --- a/plugins/samples/ClientCtx.c +++ b/plugins/samples/ClientCtx.c @@ -125,22 +125,22 @@ static const struct AFB_verb_desc_v1 verbs[]= { {"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} }; diff --git a/plugins/samples/HelloWorld.c b/plugins/samples/HelloWorld.c index 78a1eafd..fe117846 100644 --- a/plugins/samples/HelloWorld.c +++ b/plugins/samples/HelloWorld.c @@ -54,8 +54,8 @@ static void pingBug (struct afb_req request) 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"); } diff --git a/plugins/samples/tic-tac-toe.c b/plugins/samples/tic-tac-toe.c index a1630c50..31682d94 100644 --- a/plugins/samples/tic-tac-toe.c +++ b/plugins/samples/tic-tac-toe.c @@ -299,7 +299,7 @@ static void changed(struct board *board, const char *reason) waiter = next; } - afb_event_sender_push(afb_daemon_get_event_sender(afbitf->daemon), reason, description); + afb_daemon_broadcast_event(afbitf->daemon, reason, description); } /* @@ -364,11 +364,11 @@ static void move(struct afb_req req) 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"); @@ -390,7 +390,7 @@ static void move(struct afb_req req) } /* 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 */ @@ -413,11 +413,11 @@ static void level(struct afb_req req) 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"); @@ -447,7 +447,7 @@ static void join(struct afb_req req) 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; @@ -549,7 +549,6 @@ static void play(struct afb_req req) static void wait(struct afb_req req) { - int count; struct board *board; struct waiter *waiter; @@ -557,21 +556,6 @@ static void wait(struct afb_req req) 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; @@ -583,18 +567,17 @@ static void wait(struct afb_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 */ }; /* @@ -607,7 +590,7 @@ static const struct AFB_plugin plugin_description = .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 */ } }; diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 3b3c6fd4..f41a3a88 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -51,6 +51,9 @@ ADD_LIBRARY(afb-lib STATIC websock.c ) +########################################### +# build and install afb-daemon +########################################### ADD_EXECUTABLE(afb-daemon main.c) TARGET_LINK_LIBRARIES(afb-daemon afb-lib @@ -66,11 +69,29 @@ TARGET_LINK_LIBRARIES(afb-daemon 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}) + + diff --git a/src/afb-api-so.c b/src/afb-api-so.c index 3cf1feab..abe100b0 100644 --- a/src/afb-api-so.c +++ b/src/afb-api-so.c @@ -214,6 +214,7 @@ int afb_api_so_add_plugin(const char *path) 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); diff --git a/src/afb-client-demo.c b/src/afb-client-demo.c index 349a0274..6344d6a3 100644 --- a/src/afb-client-demo.c +++ b/src/afb-client-demo.c @@ -30,7 +30,7 @@ #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" diff --git a/src/export-afbwsc.map b/src/export-afbwsc.map new file mode 100644 index 00000000..c775a16f --- /dev/null +++ b/src/export-afbwsc.map @@ -0,0 +1,9 @@ +{ +global: + afb_ws_client_connect_wsj1; + afb_wsj1_*; + afb_common_*; +local: + *; +}; + diff --git a/src/verbose.h b/src/verbose.h index 3382d39f..7e10d252 100644 --- a/src/verbose.h +++ b/src/verbose.h @@ -23,7 +23,7 @@ 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) diff --git a/test/sample-post.html b/test/sample-post.html index b1486c3b..d28c5bc0 100644 --- a/test/sample-post.html +++ b/test/sample-post.html @@ -6,7 +6,7 @@ <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> @@ -58,4 +58,4 @@ </body> -</html>
\ No newline at end of file +</html> |