diff options
Diffstat (limited to 'doc/writing-afb-plugins.html')
| -rw-r--r-- | doc/writing-afb-plugins.html | 482 |
1 files changed, 0 insertions, 482 deletions
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> |