diff options
| author |   jobol <jobol@nonadev.net> | 2016-05-26 18:12:12 +0200 |
|---|---|---|
| committer | jobol <jobol@nonadev.net> | 2016-05-26 18:12:12 +0200 |
| commit | ebb9bd69a97516763d5d9203245ded592b825a86 (patch) | |
| tree | 5c08595c5a3958311faab2698ece730fc18f6dc9 | |
| parent | cfa0067c4e1df2def1660e2da31efd62df6a3d30 (diff) | |
update documentation
Signed-off-by: jobol <jobol@nonadev.net>
| -rw-r--r-- | doc/FAQ.html | 5 | ||||
| -rw-r--r-- | doc/FAQ.md | 2 | ||||
| -rw-r--r-- | doc/README.html | 9 | ||||
| -rw-r--r-- | doc/afb-daemon-vocabulary.html | 41 | ||||
| -rw-r--r-- | doc/afb-daemon-vocabulary.md | 2 | ||||
| -rw-r--r-- | doc/doc.css | 7 | ||||
| -rwxr-xr-x | doc/updt.sh | 40 | ||||
| -rw-r--r-- | doc/writing-afb-plugins.html | 459 | ||||
| -rw-r--r-- | doc/writing-afb-plugins.md | 288 |
9 files changed, 687 insertions, 166 deletions
diff --git a/doc/FAQ.html b/doc/FAQ.html index 4ebefaa3..2bd963bb 100644 --- a/doc/FAQ.html +++ b/doc/FAQ.html @@ -4,11 +4,10 @@ <meta charset="UTF-8"> </head> <body> -<a name="Frequently.Asked.Question.about.AFB-DAEMON"></a> -<h1>Frequently Asked Question about AFB-DAEMON</h1> +<h1 id="Frequently.Asked.Question.about.AFB-DAEMON">Frequently Asked Question about AFB-DAEMON</h1> <pre><code>version: 1 -Date: 24 mai 2016 +Date: 25 May 2016 Author: José Bollo </code></pre> @@ -1,7 +1,7 @@ Frequently Asked Question about AFB-DAEMON ========================================== version: 1 - Date: 24 mai 2016 + Date: 25 May 2016 Author: José Bollo TABLE-OF-CONTENT-HERE diff --git a/doc/README.html b/doc/README.html index 0a7dffa8..04d68bf1 100644 --- a/doc/README.html +++ b/doc/README.html @@ -4,18 +4,15 @@ <meta charset="UTF-8"> </head> <body> -<a name="Inititial.Build"></a> -<h3>Inititial Build</h3> +<h3 id="Inititial.Build">Inititial Build</h3> <p>mkdir build cd build cmake ..</p> -<a name="Netbeans"></a> -<h3>Netbeans</h3> +<h3 id="Netbeans">Netbeans</h3> -<a name="Copy.nbprojet.at.project.base"></a> -<h1>Copy nbprojet at project base</h1> +<h1 id="Copy.nbprojet.at.project.base">Copy nbprojet at project base</h1> <p>cp -r doc/nbproject.template ./nbproject</p> </body> diff --git a/doc/afb-daemon-vocabulary.html b/doc/afb-daemon-vocabulary.html index b398aa33..4416db81 100644 --- a/doc/afb-daemon-vocabulary.html +++ b/doc/afb-daemon-vocabulary.html @@ -4,11 +4,10 @@ <meta charset="UTF-8"> </head> <body> -<a name="Vocabulary.for.AFB-DAEMON"></a> -<h1>Vocabulary for AFB-DAEMON</h1> +<h1 id="Vocabulary.for.AFB-DAEMON">Vocabulary for AFB-DAEMON</h1> <pre><code>version: 1 -Date: 24 mai 2016 +Date: 25 May 2016 Author: José Bollo </code></pre> @@ -31,47 +30,35 @@ Author: José Bollo </li> </ul></p> -<a name="Authentification"></a> -<h2>Authentification</h2> +<h2 id="Authentification">Authentification</h2> -<a name="Context"></a> -<h2>Context</h2> +<h2 id="Context">Context</h2> -<a name="Level.of.authorisation..LOA."></a> -<h2>Level of authorisation (LOA)</h2> +<h2 id="Level.of.authorisation..LOA.">Level of authorisation (LOA)</h2> -<a name="Plugin"></a> -<h2>Plugin</h2> +<h2 id="Plugin">Plugin</h2> -<a name="Request"></a> -<h2>Request</h2> +<h2 id="Request">Request</h2> -<a name="Reply.Response"></a> -<h2>Reply/Response</h2> +<h2 id="Reply.Response">Reply/Response</h2> -<a name="Service"></a> -<h2>Service</h2> +<h2 id="Service">Service</h2> -<a name="Session"></a> -<h2>Session</h2> +<h2 id="Session">Session</h2> <p>A session records data as</p> -<a name="Token"></a> -<h2>Token</h2> +<h2 id="Token">Token</h2> -<a name="UUID"></a> -<h2>UUID</h2> +<h2 id="UUID">UUID</h2> <p>It stand for Universal Unic IDentifier.</p> <p>Its is designed to create identifier in a way that avoid has much as possible conflicts. It means that if two differents instance create a UUID, the probability that they create the same UUID is very low, near to zero.</p> -<a name="x-afb-token"></a> -<h2>x-afb-token</h2> +<h2 id="x-afb-token">x-afb-token</h2> -<a name="x-afb-uuid"></a> -<h2>x-afb-uuid</h2> +<h2 id="x-afb-uuid">x-afb-uuid</h2> </body> </html> diff --git a/doc/afb-daemon-vocabulary.md b/doc/afb-daemon-vocabulary.md index 7a4b6537..2531c81a 100644 --- a/doc/afb-daemon-vocabulary.md +++ b/doc/afb-daemon-vocabulary.md @@ -1,7 +1,7 @@ Vocabulary for AFB-DAEMON ========================= version: 1 - Date: 24 mai 2016 + Date: 25 May 2016 Author: José Bollo TABLE-OF-CONTENT-HERE diff --git a/doc/doc.css b/doc/doc.css index a5c5be5c..d100bd1c 100644 --- a/doc/doc.css +++ b/doc/doc.css @@ -19,4 +19,11 @@ pre { outline: #555; } +pre:first-of-type { width: 20em; } +blockquote { + border-left: solid thick black; + background-color: #ff8; + font: bolder; + padding: 0.7em 1.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 index 5aeca0a5..712d30ee 100644 --- a/doc/writing-afb-plugins.html +++ b/doc/writing-afb-plugins.html @@ -4,11 +4,10 @@ <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> +<h1 id="HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</h1> <pre><code>version: 1 -Date: 24 mai 2016 +Date: 25 May 2016 Author: José Bollo </code></pre> @@ -18,6 +17,12 @@ Author: José Bollo <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> @@ -44,18 +49,24 @@ Author: José Bollo <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="#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></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="#Sending.messages.to.the.log.system">Sending messages to the log system</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> +<h2 id="Summary">Summary</h2> <p>The binder afb-daemon serves files through the HTTP protocol and offers access to API’s through @@ -69,8 +80,7 @@ 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> +<h3 id="Nature.of.a.plugin">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 @@ -78,8 +88,33 @@ 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> +<h3 id="Kinds.of.plugins">Kinds of plugins</h3> + +<p>There is two kinds of plugins: application plugins and service +plugins.</p> + +<h4 id="Application.plugins">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> + +<h4 id="Service.plugins">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> + +<h3 id="Live.cycle.of.a.plugin.within.afb-daemon">Live cycle of a plugin within afb-daemon</h3> <p>The plugins are loaded and activated when afb-daemon starts.</p> @@ -97,8 +132,7 @@ 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> +<h3 id="Content.of.a.plugin">Content of a plugin</h3> <p>For afb-daemon, a plugin contains 2 different things: names and functions.</p> @@ -124,8 +158,7 @@ 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> +<h4 id="The.name.of.the.plugin">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> @@ -140,8 +173,7 @@ 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> +<h4 id="Names.of.verbs">Names of verbs</h4> <p>Each plugin exposes a set of verbs that can be called by client of afb-daemon.</p> @@ -154,8 +186,7 @@ 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> +<h4 id="The.initialisation.function">The initialisation function</h4> <p>The initialisation function serves several purposes.</p> @@ -171,8 +202,7 @@ requirements and implmentations of the verbs that it exposes.</p></li> </ol> -<a name="Functions.implementing.verbs"></a> -<h4>Functions implementing verbs</h4> +<h4 id="Functions.implementing.verbs">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 @@ -198,8 +228,7 @@ returning are named <em>asynchronous implementations</em>.</p> 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> +<h2 id="The.Tic-Tac-Toe.example">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 @@ -208,8 +237,7 @@ 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> +<h2 id="Choosing.names">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 @@ -221,8 +249,7 @@ 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> +<h3 id="Names.for.API..plugin.">Names for API (plugin)</h3> <p>The names of the API are checked. All characters are authorised except:</p> @@ -241,8 +268,7 @@ All characters are authorised except:</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> +<h3 id="Names.for.verbs">Names for verbs</h3> <p>The names of the verbs are not checked.</p> @@ -253,8 +279,7 @@ 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> +<h3 id="Names.for.arguments">Names for arguments</h3> <p>The names for arguments are not restricted and can be anything.</p> @@ -263,8 +288,7 @@ anything.</p> 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> +<h3 id="Forging.names.widely.available">Forging names widely available</h3> <p>The key names of javascript object can be almost anything using the arrayed notation:</p> @@ -287,8 +311,7 @@ valid javascript identifier.</p> 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> +<h2 id="Options.to.set.when.compiling.plugins">Options to set when compiling plugins</h2> <p>Afb-daemon provides a configuration file for <em>pkg-config</em>. Typing the command</p> @@ -313,8 +336,7 @@ 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> +<h2 id="Header.files.to.include">Header files to include</h2> <p>The plugin <em>tictactoe</em> has the following lines for its includes:</p> @@ -341,8 +363,7 @@ if it needs it:</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> +<h2 id="Writing.a.synchronous.verb.implementation">Writing a synchronous verb implementation</h2> <p>The verb <strong>tictactoe/board</strong> is a synchronous implementation. Here is its listing:</p> @@ -352,33 +373,61 @@ Here is its listing:</p> */ static void board(struct afb_req req) { - struct board *board; - struct json_object *description; + 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); + /* 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); + /* describe the board */ + description = describe(board); - /* send the board's description */ - afb_req_success(req, description, NULL); + /* 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> +verb implementation. Let summarize it:</p> -<a name="The.incoming.request"></a> -<h3>The incoming request</h3> +<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> + + +<h3 id="The.incoming.request">The incoming request</h3> -<p>For any implementation, the request is received by a structure of type +<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> +<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> -<p>This structure, here named <em>req</em>, is used</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> @@ -394,8 +443,7 @@ 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> +<h3 id="Associating.a.context.to.the.session">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> @@ -430,14 +478,14 @@ its context: the board. This function is <em>board_of_req</em>:</p> */ static inline struct board *board_of_req(struct afb_req req) { - return afb_req_context(req, (void*)get_new_board, (void*)release_board); + 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>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> @@ -450,33 +498,286 @@ The casts are required to avoid a warning when compiling.</p> */ 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; + 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 +<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 function <strong>release_board</strong></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> + +<h3 id="Sending.the.reply.to.a.request">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). + */ +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. + */ +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. + */ +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. + */ +void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...); +</code></pre> + +<h2 id="Getting.argument.of.invocation">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> + +<h3 id="Basic.functions.for.querying.arguments">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> + +<h3 id="Arguments.for.received.files">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> + +<h3 id="Arguments.as.a.JSON.object">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> + -<a name="Sending.the.reply.to.a.request"></a> -<h3>Sending the reply to a request</h3> +<blockquote><p>In fact, for Websockets requests, the function <strong>afb_req_value</strong> +can be seen as a shortcut to +<em>json_object_get_string(json_object_object_get(afb_req_json(req), name))</em></p></blockquote> -<a name="Getting.argument.of.invocation"></a> -<h2>Getting argument of invocation</h2> +<h2 id="Sending.messages.to.the.log.system">Sending messages to the log system</h2> -<a name="How.to.build.a.plugin"></a> -<h2>How to build a plugin</h2> +<h2 id="How.to.build.a.plugin">How to build a plugin</h2> -<p>Afb-daemon provides a The packaging of afb-daemon</p> +<p>Afb-daemon provides a <em>pkg-config</em> configuration file.</p> </body> </html> diff --git a/doc/writing-afb-plugins.md b/doc/writing-afb-plugins.md index ba2e676a..7611600f 100644 --- a/doc/writing-afb-plugins.md +++ b/doc/writing-afb-plugins.md @@ -28,6 +28,32 @@ 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 @@ -312,12 +338,27 @@ it the object *description*. ### The incoming request -For any implementation, the request is received by a structure of type +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.*** +> 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*. -This structure, here named *req*, is used +> 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. @@ -333,7 +374,7 @@ 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 +### 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. @@ -407,14 +448,41 @@ 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 +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); -Sending a reply to a request must be done at most one time. + /* + * 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. -The functions to send replies are defined as below: +> 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'. @@ -422,26 +490,16 @@ The functions to send replies are defined as below: * 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); - } + 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. */ - 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); - } + 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'. @@ -452,31 +510,187 @@ The functions to send replies are defined as below: * 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); - } + 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. */ - static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...) + void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...); + +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) { - 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); + 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); -Getting argument of invocation ------------------------------- +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))* Sending messages to the log system ---------------------------------- |