+++ /dev/null
-<html>
-<head>
- <link rel="stylesheet" type="text/css" href="doc.css">
- <meta charset="UTF-8">
-</head>
-<body>
-<h1 id="HOWTO.WRITE.a.PLUGIN.for.AFB-DAEMON">HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
-
-<pre><code>version: 1
-Date: 25 May 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="#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.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="#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>
-
-<h2 id="Summary">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>
-
-<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
-starts.</p>
-
-<p>Technically, a plugin is not linked to any library of afb-daemon.</p>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<h4 id="The.initialisation.function">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>
-
-
-<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
-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>
-
-<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
-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>
-
-<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
-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>
-
-<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>
-
-<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>
-
-<h3 id="Names.for.verbs">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>
-
-<h3 id="Names.for.arguments">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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-<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>
-
-
-<h3 id="The.incoming.request">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>
-
-<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>
-
-<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>
-
-<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>
-
-
-<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>
-
-<h2 id="Sending.messages.to.the.log.system">Sending messages to the log system</h2>
-
-<h2 id="How.to.build.a.plugin">How to build a plugin</h2>
-
-<p>Afb-daemon provides a <em>pkg-config</em> configuration file.</p>
-</body>
-</html>
Code Review / src / app-framework-binder.git / blobdiff