<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>
<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="#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
<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
<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>
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>
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>
<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>
<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>
</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
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
<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
<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>
<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>
<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>
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>
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>
<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>
<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>
*/
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>
<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>
*/
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>
*/
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>
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 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.
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.
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'.
* 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'.
* 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
----------------------------------
Code Review / src / app-framework-binder.git / commitdiff