From b81bab801d1a39cce7254b0c056d991412ec4331 Mon Sep 17 00:00:00 2001 From: José Bollo Date: Fri, 27 May 2016 17:31:30 +0200 Subject: improves documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I5abae06cd5b5127fca97ba12aa8f18d037a95d79 Signed-off-by: José Bollo --- doc/FAQ.html | 5 +- doc/FAQ.md | 2 +- doc/README.html | 9 +- doc/afb-daemon-vocabulary.html | 103 ++- doc/afb-daemon-vocabulary.md | 64 +- doc/afb-plugin-writing.html | 1349 ++++++++++++++++++++++++++++++++++++++++ doc/afb-plugin-writing.md | 1034 ++++++++++++++++++++++++++++++ doc/doc.css | 12 +- doc/writing-afb-plugins.html | 783 ----------------------- doc/writing-afb-plugins.md | 703 --------------------- 10 files changed, 2548 insertions(+), 1516 deletions(-) create mode 100644 doc/afb-plugin-writing.html create mode 100644 doc/afb-plugin-writing.md delete mode 100644 doc/writing-afb-plugins.html delete mode 100644 doc/writing-afb-plugins.md diff --git a/doc/FAQ.html b/doc/FAQ.html index 2bd963bb..ffda81af 100644 --- a/doc/FAQ.html +++ b/doc/FAQ.html @@ -4,10 +4,11 @@ -

Frequently Asked Question about AFB-DAEMON

+ +

Frequently Asked Question about AFB-DAEMON

version: 1
-Date:    25 May 2016
+Date:    26 mai 2016
 Author:  José Bollo
diff --git a/doc/FAQ.md b/doc/FAQ.md index 76957c1f..93647311 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -1,7 +1,7 @@ Frequently Asked Question about AFB-DAEMON ========================================== version: 1 - Date: 25 May 2016 + Date: 26 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE diff --git a/doc/README.html b/doc/README.html index 04d68bf1..0a7dffa8 100644 --- a/doc/README.html +++ b/doc/README.html @@ -4,15 +4,18 @@ -

Inititial Build

+ +

Inititial Build

mkdir build cd build cmake ..

-

Netbeans

+ +

Netbeans

-

Copy nbprojet at project base

+ +

Copy nbprojet at project base

cp -r doc/nbproject.template ./nbproject

diff --git a/doc/afb-daemon-vocabulary.html b/doc/afb-daemon-vocabulary.html index 4416db81..096f5076 100644 --- a/doc/afb-daemon-vocabulary.html +++ b/doc/afb-daemon-vocabulary.html @@ -4,19 +4,19 @@ -

Vocabulary for AFB-DAEMON

+ +

Vocabulary for AFB-DAEMON

version: 1
-Date:    25 May 2016
+Date:    26 mai 2016
 Author:  José Bollo

-

Authentification

+ +

Event

-

Context

+

Message with data propagated from the services to the client and not expecting +any reply.

-

Level of authorisation (LOA)

+

The current implementation allows to widely broadcast events to all clients.

-

Plugin

+ +

Level of assurance (LOA)

-

Request

+

This level that can be from 0 to 3 represent the level of +assurance that the services can expect from the session.

-

Reply/Response

+

The exact definition of the meaning of this levels and of +how to use it remains to be achived.

-

Service

+ +

Plugin

-

Session

+

A shared library object intended to be plug to an afb-daemon instance +to implement an API.

-

A session records data as

+ +

Request

-

Token

+

A request is an invocation by a client to a method of a plugin using a message +transfered through some protocol: HTTP, WebSocket, DBUS… served by afb-daemon

-

UUID

+ +

Reply/Response

+ +

This is a message sent to client as the result of the request.

+ + +

Service

+ +

Service are made of plugins runnning by their side on their binder. +It can serve many client. Each one being attached to one session.

+ +

The framework establishes the connection between the services and +the clients. Using DBus currently.

+ + +

Session

+ +

A session is meant to be the unic context of an instance of client, +identifying that instance across requests.

+ +

Each session has an identifier. Session identifier generated by afb-daemon are UUIDs.

+ +

Internally, afb-daemon offers a mechanism to attach data to sessions. +When the session is closed or disappears, the data attached to that session +are freed.

+ + +

Token

+ +

The token is an identifier that the the client must give to be authentificated.

+ +

At start, afb-daemon get an initial token. This initial token must be presented +incoming client to be authentificated.

+ +

A token is valid only for a period.

+ +

The token must be renewed periodically. When the token is renewed, afb-daemon +sends the new token to the client.

+ +

Tokens generated by afb-daemon are UUIDs.

+ + +

UUID

It stand for Universal Unic IDentifier.

Its is designed to create identifier in a way that avoid has much as possible conflicts. It means that if two differents instance create a UUID, the probability that they create the same UUID is very low, near to zero.

-

x-afb-token

+ +

x-afb-reqid

+ +

Argument name that can be used with HTTP request. +When this argument is given, it is automatically added to the “request” object of the +answer.

+ + +

x-afb-token

+ +

Argument name for giving the token without ambiguity. +You can also use the name token but it may conflicts with other arguments.

+ + +

x-afb-uuid

-

x-afb-uuid

+

Argument name for giving explicitely the session identifier without ambiguity. +You can also use the name uuid but it may conflicts with other arguments.

diff --git a/doc/afb-daemon-vocabulary.md b/doc/afb-daemon-vocabulary.md index 2531c81a..71771947 100644 --- a/doc/afb-daemon-vocabulary.md +++ b/doc/afb-daemon-vocabulary.md @@ -1,31 +1,72 @@ Vocabulary for AFB-DAEMON ========================= version: 1 - Date: 25 May 2016 + Date: 26 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE -## Authentification +## Event -## Context +Message with data propagated from the services to the client and not expecting +any reply. -## Level of authorisation (LOA) +The current implementation allows to widely broadcast events to all clients. + +## Level of assurance (LOA) + +This level that can be from 0 to 3 represent the level of +assurance that the services can expect from the session. + +The exact definition of the meaning of this levels and of +how to use it remains to be achived. ## Plugin +A shared library object intended to be plug to an afb-daemon instance +to implement an API. + ## Request +A request is an invocation by a client to a method of a plugin using a message +transfered through some protocol: HTTP, WebSocket, DBUS... served by afb-daemon + ## Reply/Response +This is a message sent to client as the result of the request. + ## Service +Service are made of plugins runnning by their side on their binder. +It can serve many client. Each one being attached to one session. + +The framework establishes the connection between the services and +the clients. Using DBus currently. + ## Session -A session records data as +A session is meant to be the unic context of an instance of client, +identifying that instance across requests. + +Each session has an identifier. Session identifier generated by afb-daemon are UUIDs. + +Internally, afb-daemon offers a mechanism to attach data to sessions. +When the session is closed or disappears, the data attached to that session +are freed. ## Token +The token is an identifier that the the client must give to be authentificated. + +At start, afb-daemon get an initial token. This initial token must be presented +incoming client to be authentificated. + +A token is valid only for a period. + +The token must be renewed periodically. When the token is renewed, afb-daemon +sends the new token to the client. + +Tokens generated by afb-daemon are UUIDs. ## UUID @@ -34,6 +75,19 @@ It stand for Universal Unic IDentifier. Its is designed to create identifier in a way that avoid has much as possible conflicts. It means that if two differents instance create a UUID, the probability that they create the same UUID is very low, near to zero. +## x-afb-reqid + +Argument name that can be used with HTTP request. +When this argument is given, it is automatically added to the "request" object of the +answer. + ## x-afb-token +Argument name for giving the token without ambiguity. +You can also use the name **token** but it may conflicts with other arguments. + ## x-afb-uuid + +Argument name for giving explicitely the session identifier without ambiguity. +You can also use the name **uuid** but it may conflicts with other arguments. + diff --git a/doc/afb-plugin-writing.html b/doc/afb-plugin-writing.html new file mode 100644 index 00000000..9a98ffe9 --- /dev/null +++ b/doc/afb-plugin-writing.html @@ -0,0 +1,1349 @@ + + + + + + + +

HOWTO WRITE a PLUGIN for AFB-DAEMON

+ +
version: 1
+Date:    27 mai 2016
+Author:  José Bollo
+
+ +

+ + +

Summary

+ +

The binder afb-daemon serves files through +the HTTP protocol and offers access to API’s through +HTTP or WebSocket protocol.

+ +

The plugins are used to add API’s to afb-daemon. +This part describes how to write a plugin for afb-daemon. +Excepting this summary, this part is intended to be read +by developpers.

+ +

Before going into details, through a tiny example, +a short overview plugins basis is needed.

+ + +

Nature of a plugin

+ +

A plugin is a separate piece of code made of a shared library. +The plugin is loaded and activated by afb-daemon when afb-daemon +starts.

+ +

Technically, a plugin is not linked to any library of afb-daemon.

+ + +

Kinds of plugins

+ +

There is two kinds of plugins: application plugins and service +plugins.

+ + +

Application plugins

+ +

Application plugins are intended to be instanciated for each +application: when an application using that plugin is started, +its binder starts a new instance of the plugin.

+ +

It means that the application plugins mainly have only one +context to manage for one client.

+ + +

Service plugins

+ +

Service plugins are intended to be instanciated only one time +only and connected to many clients.

+ +

So either it does not manage context at all or otherwise, +if it manages context, it should be able to manage one context +per client.

+ +

In details, it may be useful to have service plugins at a user +level.

+ + +

Live cycle of a plugin within afb-daemon

+ +

The plugins are loaded and activated when afb-daemon starts.

+ +

At start, the plugin initialise itself. +If it fails to initialise then afb-daemon stops.

+ +

Conversely, if it success to initialize, it must declare +a name, that must be unique, and a list of API’s verbs.

+ +

When initialized, the functions implementing the API’s verbs +of the plugin are activated on call.

+ +

At the end, nothing special is done by afb-daemon. +Consequently, developpers of plugins should use ‘atexit’ +or ‘on_exit’ during initialisation if they need to +perform specific actions when stopping.

+ + +

Content of a plugin

+ +

For afb-daemon, a plugin contains 2 different +things: names and functions.

+ +

There is two kind of names: + - the name of the plugin, + - the names of the verbs.

+ +

There is two kind of functions: + - the initialisation function + - functions implementing verbs

+ +

Afb-daemon translates the name of the method that is +invoked to a pair of API and verb names. For example, +the method named foo/bar translated to the API +name foo and the verb name bar. +To serve it, afb-daemon search the plugin that record +the name foo and if it also recorded the verb bar, +it calls the implementation function declared for this verb.

+ +

Afb-daemon make no distinction between lower case +and upper case when searching for a method. +Thus, The names TicTacToe/Board and tictactoe/borad +are equals.

+ + +

The name of the plugin

+ +

The name of the plugin is also known as the name +of the API that defines the plugin.

+ +

This name is also known as the prefix.

+ +

The name of a plugin MUST be unique within afb-daemon.

+ +

For example, when a client of afb-daemon +calls a method named foo/bar. Afb-daemon +extracts the prefix foo and the suffix bar. +foo is the API name and must match a plugin name, +the plugin that implements the verb bar.

+ + +

Names of verbs

+ +

Each plugin exposes a set of verbs that can be called +by client of afb-daemon.

+ +

The name of a verb MUST be unique within a plugin.

+ +

Plugins link verbs to functions that are called +when clients emit requests for that verb.

+ +

For example, when a client of afb-daemon +calls a method named foo/bar.

+ + +

The initialisation function

+ +

The initialisation function serves several purposes.

+ +
    +

  1. It allows afb-daemon to check the version +of the plugin using the name of the initialisation +functions that it found. Currently, the initialisation +function is named pluginAfbV1Register. It identifies +the first version of plugins.

    2. +

  2. It allows the plugin to initialise itself.

    3. +

  3. It serves to the plugin to declare names, descriptions, +requirements and implmentations of the verbs that it exposes.

    4. +
+ + + +

Functions implementing verbs

+ +

When a method is called, afb-daemon constructs a request +object and pass it to the implementation function for verb +within the plugin of the API.

+ +

An implementation function receives a request object that +is used to get arguments of the request, to send +answer, to store session data.

+ +

A plugin MUST send an answer to the request.

+ +

But it is not mandatory to send the answer +before to return from the implementing function. +This behaviour is important for implementing +asynchronous actions.

+ +

Implementation functions that always reply to the request +before returning are named synchronous implementations. +Those that don’t always reply to the request before +returning are named asynchronous implementations.

+ +

Asynchronous implementations typically initiate an +asynchronous action and record to send the reply +on completion of this action.

+ + +

The Tic-Tac-Toe example

+ +

This part explains how to write an afb-plugin. +For the sake of being practical we will use many +examples from the tic-tac-toe example. +This plugin example is in plugins/samples/tic-tac-toe.c.

+ +

This plugin is named tictactoe.

+ + +

Choosing names

+ +

The designer of a plugin must defines names for its plugin +(or its API) and for the verbs of its API. He also +must defines names for arguments given by name.

+ +

While forging names, the designer should take into account +the rules for making valid names and some rules that make +the names easy to use across plaforms.

+ +

The names and strings used ALL are UTF-8 encoded.

+ + +

Names for API (plugin)

+ +

The names of the API are checked. +All characters are authorised except:

+ + + + +

In other words the set of forbidden characters is +{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027, + \u002f, \u003f, \u0060, \u007f }.

+ +

Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name.

+ + +

Names for verbs

+ +

The names of the verbs are not checked.

+ +

However, the validity rules for verb’s names are the +same as for API’s names except that the dot (.) character +is forbidden.

+ +

Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name.

+ + +

Names for arguments

+ +

The names for arguments are not restricted and can be +anything.

+ +

The arguments are searched with the case sensitive +string comparison. Thus the names “index” and “Index” +are not the same.

+ + +

Forging names widely available

+ +

The key names of javascript object can be almost +anything using the arrayed notation:

+ +
object[key] = value
+
+ +

That is not the case with the dot notation:

+ +
object.key = value
+
+ +

Using the dot notation, the key must be a valid javascript +identifier.

+ +

For this reason, the chosen names should better be +valid javascript identifier.

+ +

It is also a good practice, even for arguments, to not +rely on the case sensitivity and to avoid the use of +names different only by the case.

+ + +

Options to set when compiling plugins

+ +

Afb-daemon provides a configuration file for pkg-config. +Typing the command

+ +
pkg-config --cflags afb-daemon
+
+ +

will print the flags to use for compiling, like this:

+ +
$ pkg-config --cflags afb-daemon
+-I/opt/local/include -I/usr/include/json-c 
+
+ +

For linking, you should use

+ +
$ pkg-config --libs afb-daemon
+-ljson-c
+
+ +

As you see, afb-daemon automatically includes dependency to json-c. +This is done through the Requires keyword of pkg-config.

+ +

If this behaviour is a problem, let us know.

+ + +

Header files to include

+ +

The plugin tictactoe has the following lines for its includes:

+ +
#define _GNU_SOURCE
+#include <stdio.h>
+#include <string.h>
+#include <json-c/json.h>
+#include <afb/afb-plugin.h>
+
+ +

The header afb/afb-plugin.h includes all the features that a plugin +needs except two foreign header that must be included by the plugin +if it needs it:

+ + + + +

The tictactoe plugin does not use systemd features so it is not included.

+ +

When including afb/afb-plugin.h, the macro _GNU_SOURCE must be +defined.

+ + +

Writing a synchronous verb implementation

+ +

The verb tictactoe/board is a synchronous implementation. +Here is its listing:

+ +
/*
+ * get the board
+ */
+static void board(struct afb_req req)
+{
+        struct board *board;
+        struct json_object *description;
+
+        /* retrieves the context for the session */
+        board = board_of_req(req);
+        INFO(afbitf, "method 'board' called for boardid %d", board->id);
+
+        /* describe the board */
+        description = describe(board);
+
+        /* send the board's description */
+        afb_req_success(req, description, NULL);
+}
+
+ +

This examples show many aspects of writing a synchronous +verb implementation. Let summarize it:

+ +
    +

  1. The function board_of_req retrieves the context stored +for the plugin: the board.

    2. +

  2. The macro INFO sends a message of kind INFO +to the logging system. The global variable named afbitf +used represents the interface to afb-daemon.

    3. +

  3. The function describe creates a json_object representing +the board.

    4. +

  4. The function afb_req_success sends the reply, attaching to +it the object description.

    5. +
+ + + +

The incoming request

+ +

For any implementation, the request is received by a structure of type +struct afb_req.

+ +

Note that this is a PLAIN structure, not a pointer to a structure.

+ +

The definition of struct afb_req is:

+ +
/*
+ * Describes the request by plugins from afb-daemon
+ */
+struct afb_req {
+        const struct afb_req_itf *itf;  /* the interfacing functions */
+        void *closure;          /* the closure for functions */
+};
+
+ +

It contains two pointers: one, itf, points to the functions needed +to handle the internal request represented by the second pointer, closure.

+ +

The structure must never be used directly. +Insted, use the intended functions provided +by afb-daemon and described here.

+ +

req is used to get arguments of the request, to send +answer, to store session data.

+ +

This object and its interface is defined and documented +in the file names afb/afb-req-itf.h

+ +

The above example uses 2 times the request object req.

+ +

The first time, it is used for retrieving the board attached to +the session of the request.

+ +

The second time, it is used to send the reply: an object that +describes the current board.

+ + +

Associating a context to the session

+ +

When the plugin tic-tac-toe receives a request, it musts regain +the board that describes the game associated to the session.

+ +

For a plugin, having data associated to a session is a common case. +This data is called the context of the plugin for the session. +For the plugin tic-tac-toe, the context is the board.

+ +

The requests afb_req offer four functions for +storing and retrieving the context associated to the session.

+ +

These functions are:

+ + + + +

The plugin tictactoe use a convenient function to retrieve +its context: the board. This function is board_of_req:

+ +
/*
+ * retrieves the board of the request
+ */
+static inline struct board *board_of_req(struct afb_req req)
+{
+        return afb_req_context(req, (void*)get_new_board, (void*)release_board);
+}
+
+ +

The function afb_req_context ensure an existing context +for the session of the request. +Its two last arguments are functions. Here, the casts are required +to avoid a warning when compiling.

+ +

Here is the definition of the function afb_req_context

+ +
/*
+ * Gets the pointer stored by the plugin for the session of 'req'.
+ * If the stored pointer is NULL, indicating that no pointer was
+ * already stored, afb_req_context creates a new context by calling
+ * the function 'create_context' and stores it with the freeing function
+ * 'free_context'.
+ */
+static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
+{
+        void *result = afb_req_context_get(req);
+        if (result == NULL) {
+                result = create_context();
+                afb_req_context_set(req, result, free_context);
+        }
+        return result;
+}
+
+ +

The second argument if the function that creates the context. +For the plugin tic-tac-toe it is the function get_new_board. +The function get_new_board creates a new board and set its +count of use to 1. The boards are counting their count of use +to free there ressources when no more used.

+ +

The third argument if the function that frees the context. +For the plugin tic-tac-toe it is the function release_board. +The function release_board decrease the the count of use of +the board given as argument. If the use count decrease to zero, +the board data are freed.

+ +

The definition of the other functions for dealing with contexts are:

+ +
/*
+ * Gets the pointer stored by the plugin for the session of 'req'.
+ * When the plugin has not yet recorded a pointer, NULL is returned.
+ */
+void *afb_req_context_get(struct afb_req req);
+
+/*
+ * Stores for the plugin the pointer 'context' to the session of 'req'.
+ * The function 'free_context' will be called when the session is closed
+ * or if plugin stores an other pointer.
+ */
+void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
+
+/*
+ * Frees the pointer stored by the plugin for the session of 'req'
+ * and sets it to NULL.
+ *
+ * Shortcut for: afb_req_context_set(req, NULL, NULL)
+ */
+static inline void afb_req_context_clear(struct afb_req req)
+{
+        afb_req_context_set(req, NULL, NULL);
+}
+
+ + +

Sending the reply to a request

+ +

Two kinds of replies can be made: successful replies and +failure replies.

+ +

Sending a reply to a request must be done at most one time.

+ +

The two functions to send a reply of kind “success” are +afb_req_success and afb_req_success_f.

+ +
/*
+ * Sends a reply of kind success to the request 'req'.
+ * The status of the reply is automatically set to "success".
+ * Its send the object 'obj' (can be NULL) with an
+ * informationnal comment 'info (can also be NULL).
+ */
+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, ...);
+
+ +

The two functions to send a reply of kind “failure” are +afb_req_fail and afb_req_fail_f.

+ +
/*
+ * Sends a reply of kind failure to the request 'req'.
+ * The status of the reply is set to 'status' and an
+ * informationnal comment 'info' (can also be NULL) can be added.
+ *
+ * Note that calling afb_req_fail("success", info) is equivalent
+ * to call afb_req_success(NULL, info). Thus even if possible it
+ * is strongly recommanded to NEVER use "success" for status.
+ */
+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, ...);
+
+ + +

Getting argument of invocation

+ +

Many verbs expect arguments. Afb-daemon let plugins +retrieve their arguments by name not by position.

+ +

Arguments are given by the requests either through HTTP +or through WebSockets.

+ +

For example, the verb join of the plugin tic-tac-toe +expects one argument: the boardid to join. Here is an extract:

+ +
/*
+ * Join a board
+ */
+static void join(struct afb_req req)
+{
+        struct board *board, *new_board;
+        const char *id;
+
+        /* retrieves the context for the session */
+        board = board_of_req(req);
+        INFO(afbitf, "method 'join' called for boardid %d", board->id);
+
+        /* retrieves the argument */
+        id = afb_req_value(req, "boardid");
+        if (id == NULL)
+                goto bad_request;
+        ...
+
+ +

The function afb_req_value search in the request req +for an argument whose name is given. When no argument of the +given name was passed, afb_req_value returns NULL.

+ +

The search is case sensitive. So the name boardid is not the +same name than BoardId. But this must not be assumed so two +expected names of argument should not differ only by case.

+ + +

Basic functions for querying arguments

+ +

The function afb_req_value is defined as below:

+ +
/*
+ * Gets from the request 'req' the string value of the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name'.
+ * Returns the value of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).value
+ */
+static inline const char *afb_req_value(struct afb_req req, const char *name)
+{
+        return afb_req_get(req, name).value;
+}
+
+ +

It is defined as a shortcut to call the function afb_req_get. +That function is defined as below:

+ +
/*
+ * Gets from the request 'req' the argument of 'name'.
+ * Returns a PLAIN structure of type 'struct afb_arg'.
+ * When the argument of 'name' is not found, all fields of result are set to NULL.
+ * When the argument of 'name' is found, the fields are filled,
+ * in particular, the field 'result.name' is set to 'name'.
+ *
+ * There is a special name value: the empty string.
+ * The argument of name "" is defined only if the request was made using
+ * an HTTP POST of Content-Type "application/json". In that case, the
+ * argument of name "" receives the value of the body of the HTTP request.
+ */
+struct afb_arg afb_req_get(struct afb_req req, const char *name);
+
+ +

That function takes 2 parameters: the request and the name +of the argument to retrieve. It returns a PLAIN structure of +type struct afb_arg.

+ +

There is a special name that is defined when the request is +of type HTTP/POST with a Content-Type being application/json. +This name is “” (the empty string). In that case, the value +of this argument of empty name is the string received as a body +of the post and is supposed to be a JSON string.

+ +

The definition of struct afb_arg is:

+ +
/*
+ * Describes an argument (or parameter) of a request
+ */
+struct afb_arg {
+        const char *name;   /* name of the argument or NULL if invalid */
+        const char *value;  /* string representation of the value of the argument */
+                                /* original filename of the argument if path != NULL */
+        const char *path;   /* if not NULL, path of the received file for the argument */
+                                /* when the request is finalized this file is removed */
+};
+
+ +

The structure returns the data arguments that are known for the +request. This data include a field named path. This path +can be accessed using the function afb_req_path defined as +below:

+ +
/*
+ * Gets from the request 'req' the path for file attached to the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name' or when there is no file.
+ * Returns the path of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).path
+ */
+static inline const char *afb_req_path(struct afb_req req, const char *name)
+{
+        return afb_req_get(req, name).path;
+}
+
+ +

The path is only defined for HTTP/POST requests that send file.

+ + +

Arguments for received files

+ +

As it is explained just above, clients can send files using +HTTP/POST requests.

+ +

Received files are attached to a arguments. For example, the +following HTTP fragment (from test/sample-post.html) +will send an HTTP/POST request to the method +post/upload-image with 2 arguments named file and +hidden.

+ +
<h2>Sample Post File</h2>
+<form enctype="multipart/form-data">
+    <input type="file" name="file" />
+    <input type="hidden" name="hidden" value="bollobollo" />
+    <br>
+    <button formmethod="POST" formaction="api/post/upload-image">Post File</button>
+</form>
+
+ +

In that case, the argument named file has its value and its +path defined and not NULL.

+ +

The value is the name of the file as it was +set by the HTTP client and is generally the filename on the +client side.

+ +

The path is the path of the file saved on the temporary local storage +area of the application. This is a randomly generated and unic filename +not linked in any way with the original filename on the client.

+ +

The plugin can use the file at the given path the way that it wants: +read, write, remove, copy, rename… +But when the reply is sent and the query is terminated, the file at +this path is destroyed if it still exist.

+ + +

Arguments as a JSON object

+ +

Plugins can get all the arguments as one single object. +This feature is provided by the function afb_req_json +that is defined as below:

+ +
/*
+ * Gets from the request 'req' the json object hashing the arguments.
+ * The returned object must not be released using 'json_object_put'.
+ */
+struct json_object *afb_req_json(struct afb_req req);
+
+ +

It returns a json object. This object depends on how the request was +made:

+ + + + +

In fact, for Websockets requests, the function afb_req_value +can be seen as a shortcut to +json_object_get_string(json_object_object_get(afb_req_json(req), name))

+ + +

Initialisation of the plugin and declaration of verbs

+ +

To be active, the verbs of the plugin should be declared to +afb-daemon. And even more, the plugin itself must be recorded.

+ +

The mechanism for doing this is very simple: when afb-need starts, +it loads the plugins that are listed in its argument or configuration.

+ +

Loading a plugin follows the following steps:

+ +
    +

  1. It loads the plugin using dlopen.

    2. +

  2. It searchs for the symbol named pluginAfbV1Register using dlsym. +This symbol is assumed to be the exported initialisation function of the plugin.

    3. +

  3. It build an interface object for the plugin.

    4. +

  4. It calls the found function pluginAfbV1Register and pass it the pointer +to its interface.

    5. +

  5. The function pluginAfbV1Register setup the plugin, initialize it.

    6. +

  6. The function pluginAfbV1Register returns the pointer to a structure +that describes the plugin: its version, its name (prefix or API name), and the +list of its verbs.

    7. +

  7. Afb-daemon checks that the returned version and name can be managed. +If it can manage it, the plugin and its verbs are recorded and can be used +when afb-daemon finishes it initialisation.

    8. +
+ + +

Here is the listing of the function pluginAfbV1Register of the plugin +tic-tac-toe:

+ +
/*
+ * activation function for registering the plugin called by afb-daemon
+ */
+const struct AFB_plugin *pluginAfbV1Register(const struct AFB_interface *itf)
+{
+   afbitf = itf;         // records the interface for accessing afb-daemon
+   return &plugin_description;  // returns the description of the plugin
+}
+
+ +

This is a very small function because the tic-tac-toe plugin doesn’t have initialisation step. +It merely record the daemon’s interface and returns its descritption.

+ +

The variable afbitf is a variable global to the plugin. It records the +interface to afb-daemon and is used for logging and pushing events. +Here is its declaration:

+ +
/*
+ * the interface to afb-daemon
+ */
+const struct AFB_interface *afbitf;
+
+ +

The description of the plugin is defined as below.

+ +
/*
+ * array of the verbs exported to afb-daemon
+ */
+static const struct AFB_verb_desc_v1 plugin_verbs[] = {
+   /* VERB'S NAME     SESSION MANAGEMENT          FUNCTION TO CALL  SHORT DESCRIPTION */
+   { .name= "new",   .session= AFB_SESSION_NONE, .callback= new,   .info= "Starts a new game" },
+   { .name= "play",  .session= AFB_SESSION_NONE, .callback= play,  .info= "Tells the server to play" },
+   { .name= "move",  .session= AFB_SESSION_NONE, .callback= move,  .info= "Tells the client move" },
+   { .name= "board", .session= AFB_SESSION_NONE, .callback= board, .info= "Get the current board" },
+   { .name= "level", .session= AFB_SESSION_NONE, .callback= level, .info= "Set the server level" },
+   { .name= "join",  .session= AFB_SESSION_CHECK,.callback= join,  .info= "Join a board" },
+   { .name= "undo",  .session= AFB_SESSION_NONE, .callback= undo,  .info= "Undo the last move" },
+   { .name= "wait",  .session= AFB_SESSION_NONE, .callback= wait,  .info= "Wait for a change" },
+   { .name= NULL } /* marker for end of the array */
+};
+
+/*
+ * description of the plugin for afb-daemon
+ */
+static const struct AFB_plugin plugin_description =
+{
+   /* description conforms to VERSION 1 */
+   .type= AFB_PLUGIN_VERSION_1,
+   .v1= {               /* fills the v1 field of the union when AFB_PLUGIN_VERSION_1 */
+      .prefix= "tictactoe",     /* the API name (or plugin name or prefix) */
+      .info= "Sample tac-tac-toe game", /* short description of of the plugin */
+      .verbs = plugin_verbs     /* the array describing the verbs of the API */
+   }
+};
+
+ +

The structure plugin_description describes the plugin. +It declares the type and version of the plugin, its name, a description +and a list of its verbs.

+ +

The list of verbs is an array of structures describing the verbs and terminated by a marker: +a verb whose name is NULL.

+ +

The description of the verbs for this version is made of 4 fields:

+ + + + +

The structure describing verbs is defined as follows:

+ +
/*
+ * Description of one verb of the API provided by the plugin
+ * This enumeration is valid for plugins of type 1
+ */
+struct AFB_verb_desc_v1
+{
+       const char *name;                       /* name of the verb */
+       enum AFB_session_v1 session;            /* authorisation and session requirements of the verb */
+       void (*callback)(struct afb_req req);   /* callback function implementing the verb */
+       const char *info;                       /* textual description of the verb */
+};
+
+ +

For technical reasons, the enumeration enum AFB_session_v1 is not exactly an +enumeration but the wrapper of constant definitions that can be mixed using bitwise or +(the C operator |).

+ +

The constants that can bit mixed are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Constant name Meaning
AFB_SESSION_CREATE Equals to AFB_SESSION_LOA_EQ_0|AFB_SESSION_RENEW
AFB_SESSION_CLOSE Closes the session after the reply and set the LOA to 0
AFB_SESSION_RENEW Refreshes the token of authentification
AFB_SESSION_CHECK Just requires the token authentification
AFB_SESSION_LOA_LE_0 Requires the current LOA to be lesser then or equal to 0
AFB_SESSION_LOA_LE_1 Requires the current LOA to be lesser then or equal to 1
AFB_SESSION_LOA_LE_2 Requires the current LOA to be lesser then or equal to 2
AFB_SESSION_LOA_LE_3 Requires the current LOA to be lesser then or equal to 3
AFB_SESSION_LOA_GE_0 Requires the current LOA to be greater then or equal to 0
AFB_SESSION_LOA_GE_1 Requires the current LOA to be greater then or equal to 1
AFB_SESSION_LOA_GE_2 Requires the current LOA to be greater then or equal to 2
AFB_SESSION_LOA_GE_3 Requires the current LOA to be greater then or equal to 3
AFB_SESSION_LOA_EQ_0 Requires the current LOA to be equal to 0
AFB_SESSION_LOA_EQ_1 Requires the current LOA to be equal to 1
AFB_SESSION_LOA_EQ_2 Requires the current LOA to be equal to 2
AFB_SESSION_LOA_EQ_3 Requires the current LOA to be equal to 3
+ + +

If any of this flags is set, afb-daemon requires the token authentification +as if the flag AFB_SESSION_CHECK had been set.

+ +

The special value AFB_SESSION_NONE is zero and can be used to avoid any check.

+ +

Note that AFB_SESSION_CREATE and AFB_SESSION_CLOSE might be removed in later versions.

+ + +

Sending messages to the log system

+ +

Afb-daemon provides 4 levels of verbosity and 5 verbs for logging messages.

+ +

The verbosity is managed. Options allow the change the verbosity of afb-daemon +and the verbosity of the plugins can be set plugin by plugin.

+ +

The verbs for logging messages are defined as macros that test the +verbosity level and that call the real logging function only if the +message must be output. This avoid evaluation of arguments of the +formatting messages if the message must not be output.

+ + +

Verbs for logging messages

+ +

The 5 logging verbs are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Macro Verbosity Meaning syslog level
ERROR 0 Error conditions 3
WARNING 1 Warning conditions 4
NOTICE 1 Normal but significant condition 5
INFO 2 Informational 6
DEBUG 3 Debug-level messages 7
+ + +

You can note that the 2 verbs WARNING and INFO have the same level +of verbosity. But they don’t have the same syslog level. It means that +they are output with a different level on the logging system.

+ +

All of these verbs have the same signature:

+ +
void ERROR(const struct AFB_interface *afbitf, const char *message, ...);
+
+ +

The first argument afbitf is the interface to afb daemon that the +plugin received at its initialisation when pluginAfbV1Register was called.

+ +

The second argument message is a formatting string compatible with printf/sprintf.

+ +

The remaining arguments are arguments of the formating message like for printf.

+ + +

Managing verbosity

+ +

Depending on the level of verbosity, the messages are output or not. +The following table explains what messages will be output depending +ont the verbosity level.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Level of verbosity Outputed macro
0 ERROR
1 ERROR + WARNING + NOTICE
2 ERROR + WARNING + NOTICE + INFO
3 ERROR + WARNING + NOTICE + INFO + DEBUG
+ + + +

Output format and destination

+ +

The syslog level is used for forging a prefix to the message. +The prefixes are:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
syslog level prefix
0 <0> EMERGENCY
1 <1> ALERT
2 <2> CRITICAL
3 <3> ERROR
4 <4> WARNING
5 <5> NOTICE
6 <6> INFO
7 <7> DEBUG
+ + +

The message is issued to the standard error. +The final destination of the message depends on how the systemd service +was configured through the variable StandardError: It can be +journal, syslog or kmsg. (See man sd-daemon).

+ + +

Sending events

+ + +

Writing an asynchronous verb implementation

+ + +

How to build a plugin

+ +

Afb-daemon provides a pkg-config configuration file that can be +queried by the name afb-daemon. +This configuration file provides data that should be used +for compiling plugins. Examples:

+ +
$ pkg-config --cflags afb-daemon
+$ pkg-config --libs afb-daemon
+
+ + +

Example for cmake meta build system

+ +

This example is the extract for building the plugin afm-main using CMAKE.

+ +
pkg_check_modules(afb afb-daemon)
+if(afb_FOUND)
+        message(STATUS "Creation afm-main-plugin for AFB-DAEMON")
+        add_library(afm-main-plugin MODULE afm-main-plugin.c)
+        target_compile_options(afm-main-plugin PRIVATE ${afb_CFLAGS})
+        target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS})
+        target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES})
+        set_target_properties(afm-main-plugin PROPERTIES
+                PREFIX ""
+                LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map"
+        )
+        install(TARGETS afm-main-plugin LIBRARY DESTINATION ${plugin_dir})
+else()
+        message(STATUS "Not creating the plugin for AFB-DAEMON")
+endif()
+
+ +

Let now describe some of these lines.

+ +
pkg_check_modules(afb afb-daemon)
+
+ +

This first lines searches to the pkg-config configuration file for +afb-daemon. Resulting data are stored in the following variables:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variable Meaning
afb_FOUND Set to 1 if afb-daemon plugin development files exist
afb_LIBRARIES Only the libraries (w/o the ‘-l’) for compiling afb-daemon plugins
afb_LIBRARY_DIRS The paths of the libraries (w/o the ‘-L’) for compiling afb-daemon plugins
afb_LDFLAGS All required linker flags for compiling afb-daemon plugins
afb_INCLUDE_DIRS The ‘-I’ preprocessor flags (w/o the ‘-I’) for compiling afb-daemon plugins
afb_CFLAGS All required cflags for compiling afb-daemon plugins
+ + +

If development files are found, the plugin can be added to the set of +target to build.

+ +
add_library(afm-main-plugin MODULE afm-main-plugin.c)
+
+ +

This line asks to create a shared library having only the +source file afm-main-plugin.c (that is compiled). +The default name of the created shared object is +libafm-main-plugin.so.

+ +
set_target_properties(afm-main-plugin PROPERTIES
+        PREFIX ""
+        LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map"
+)
+
+ +

This lines are doing two things:

+ +
    +

  1. It renames the built library from libafm-main-plugin.so to afm-main-plugin.so +by removing the implicitely added prefix lib. This step is not mandatory +at all because afb-daemon doesn’t check names of files when loading it. +The only convention that use afb-daemon is that extension is .so +but this convention is used only when afb-daemon discovers plugin +from a directory hierarchy.

    2. +

  2. It applies a version script at link to only export the conventional name +of the entry point: pluginAfbV1Register. See below. By default, the linker +that creates the shared object exports all the public symbols (C functions that +are not static).

    3. +
+ + +

Next line are:

+ +
target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS})
+target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES})
+
+ +

As you can see it uses the variables computed by pkg_check_modules(afb afb-daemon) +to configure the compiler and the linker.

+ + +

Exporting the function pluginAfbV1Register

+ +

The function pluginAfbV1Register must be exported. This can be achieved +using a version script when linking. Here is the version script that is +used for tic-tac-toe (plugins/samples/export.map).

+ +
{ global: pluginAfbV1Register; local: *; };
+
+ +

This sample version script +exports as global the symbol pluginAfbV1Register and hides any +other symbols.

+ +

This version script is added to the link options using the +option –version-script=export.map is given directly to the +linker or using th option -Wl,–version-script=export.map +when the option is given to the C compiler.

+ + +

Building within yocto

+ +

Adding a dependency to afb-daemon is enough. See below:

+ +
DEPENDS += " afb-daemon "
+
+ + diff --git a/doc/afb-plugin-writing.md b/doc/afb-plugin-writing.md new file mode 100644 index 00000000..734b15a5 --- /dev/null +++ b/doc/afb-plugin-writing.md @@ -0,0 +1,1034 @@ +HOWTO WRITE a PLUGIN for AFB-DAEMON +=================================== + version: 1 + Date: 27 mai 2016 + Author: José Bollo + +TABLE-OF-CONTENT-HERE + +Summary +------- + +The binder afb-daemon serves files through +the HTTP protocol and offers access to API's through +HTTP or WebSocket protocol. + +The plugins are used to add API's to afb-daemon. +This part describes how to write a plugin for afb-daemon. +Excepting this summary, this part is intended to be read +by developpers. + +Before going into details, through a tiny example, +a short overview plugins basis is needed. + +### Nature of a plugin + +A plugin is a separate piece of code made of a shared library. +The plugin is loaded and activated by afb-daemon when afb-daemon +starts. + +Technically, a plugin is not linked to any library of afb-daemon. + +### Kinds of plugins + +There is two kinds of plugins: application plugins and service +plugins. + +#### Application plugins + +Application plugins are intended to be instanciated for each +application: when an application using that plugin is started, +its binder starts a new instance of the plugin. + +It means that the application plugins mainly have only one +context to manage for one client. + +#### Service plugins + +Service plugins are intended to be instanciated only one time +only and connected to many clients. + +So either it does not manage context at all or otherwise, +if it manages context, it should be able to manage one context +per client. + +In details, it may be useful to have service plugins at a user +level. + +### Live cycle of a plugin within afb-daemon + +The plugins are loaded and activated when afb-daemon starts. + +At start, the plugin initialise itself. +If it fails to initialise then afb-daemon stops. + +Conversely, if it success to initialize, it must declare +a name, that must be unique, and a list of API's verbs. + +When initialized, the functions implementing the API's verbs +of the plugin are activated on call. + +At the end, nothing special is done by afb-daemon. +Consequently, developpers of plugins should use 'atexit' +or 'on_exit' during initialisation if they need to +perform specific actions when stopping. + +### Content of a plugin + +For afb-daemon, a plugin contains 2 different +things: names and functions. + +There is two kind of names: + - the name of the plugin, + - the names of the verbs. + +There is two kind of functions: + - the initialisation function + - functions implementing verbs + +Afb-daemon translates the name of the method that is +invoked to a pair of API and verb names. For example, +the method named **foo/bar** translated to the API +name **foo** and the verb name **bar**. +To serve it, afb-daemon search the plugin that record +the name **foo** and if it also recorded the verb **bar**, +it calls the implementation function declared for this verb. + +Afb-daemon make no distinction between lower case +and upper case when searching for a method. +Thus, The names **TicTacToe/Board** and **tictactoe/borad** +are equals. + +#### The name of the plugin + +The name of the plugin is also known as the name +of the API that defines the plugin. + +This name is also known as the prefix. + +The name of a plugin MUST be unique within afb-daemon. + +For example, when a client of afb-daemon +calls a method named **foo/bar**. Afb-daemon +extracts the prefix **foo** and the suffix **bar**. +**foo** is the API name and must match a plugin name, +the plugin that implements the verb **bar**. + +#### Names of verbs + +Each plugin exposes a set of verbs that can be called +by client of afb-daemon. + +The name of a verb MUST be unique within a plugin. + +Plugins link verbs to functions that are called +when clients emit requests for that verb. + +For example, when a client of afb-daemon +calls a method named **foo/bar**. + +#### The initialisation function + +The initialisation function serves several purposes. + +1. It allows afb-daemon to check the version +of the plugin using the name of the initialisation +functions that it found. Currently, the initialisation +function is named **pluginAfbV1Register**. It identifies +the first version of plugins. + +2. It allows the plugin to initialise itself. + +3. It serves to the plugin to declare names, descriptions, +requirements and implmentations of the verbs that it exposes. + +#### Functions implementing verbs + +When a method is called, afb-daemon constructs a request +object and pass it to the implementation function for verb +within the plugin of the API. + +An implementation function receives a request object that +is used to get arguments of the request, to send +answer, to store session data. + +A plugin MUST send an answer to the request. + +But it is not mandatory to send the answer +before to return from the implementing function. +This behaviour is important for implementing +asynchronous actions. + +Implementation functions that always reply to the request +before returning are named *synchronous implementations*. +Those that don't always reply to the request before +returning are named *asynchronous implementations*. + +Asynchronous implementations typically initiate an +asynchronous action and record to send the reply +on completion of this action. + +The Tic-Tac-Toe example +----------------------- + +This part explains how to write an afb-plugin. +For the sake of being practical we will use many +examples from the tic-tac-toe example. +This plugin example is in *plugins/samples/tic-tac-toe.c*. + +This plugin is named ***tictactoe***. + +Choosing names +-------------- + +The designer of a plugin must defines names for its plugin +(or its API) and for the verbs of its API. He also +must defines names for arguments given by name. + +While forging names, the designer should take into account +the rules for making valid names and some rules that make +the names easy to use across plaforms. + +The names and strings used ALL are UTF-8 encoded. + +### Names for API (plugin) + +The names of the API are checked. +All characters are authorised except: + +- the control characters (\u0000 .. \u001f) +- the characters of the set { ' ', '"', '#', '%', '&', + '\'', '/', '?', '`', '\x7f' } + +In other words the set of forbidden characters is +{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027, + \u002f, \u003f, \u0060, \u007f }. + +Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name. + +### Names for verbs + +The names of the verbs are not checked. + +However, the validity rules for verb's names are the +same as for API's names except that the dot (.) character +is forbidden. + +Afb-daemon make no distinction between lower case +and upper case when searching for an API by its name. + +### Names for arguments + +The names for arguments are not restricted and can be +anything. + +The arguments are searched with the case sensitive +string comparison. Thus the names "index" and "Index" +are not the same. + +### Forging names widely available + +The key names of javascript object can be almost +anything using the arrayed notation: + + object[key] = value + +That is not the case with the dot notation: + + object.key = value + +Using the dot notation, the key must be a valid javascript +identifier. + +For this reason, the chosen names should better be +valid javascript identifier. + +It is also a good practice, even for arguments, to not +rely on the case sensitivity and to avoid the use of +names different only by the case. + +Options to set when compiling plugins +------------------------------------- + +Afb-daemon provides a configuration file for *pkg-config*. +Typing the command + + pkg-config --cflags afb-daemon + +will print the flags to use for compiling, like this: + + $ pkg-config --cflags afb-daemon + -I/opt/local/include -I/usr/include/json-c + +For linking, you should use + + $ pkg-config --libs afb-daemon + -ljson-c + +As you see, afb-daemon automatically includes dependency to json-c. +This is done through the **Requires** keyword of pkg-config. + +If this behaviour is a problem, let us know. + +Header files to include +----------------------- + +The plugin *tictactoe* has the following lines for its includes: + + #define _GNU_SOURCE + #include + #include + #include + #include + +The header *afb/afb-plugin.h* includes all the features that a plugin +needs except two foreign header that must be included by the plugin +if it needs it: + +- *json-c/json.h*: this header must be include to handle json objects; +- *systemd/sd-event.h*: this must be include to access the main loop; +- *systemd/sd-bus.h*: this may be include to use dbus connections. + +The *tictactoe* plugin does not use systemd features so it is not included. + +When including *afb/afb-plugin.h*, the macro **_GNU_SOURCE** must be +defined. + +Writing a synchronous verb implementation +----------------------------------------- + +The verb **tictactoe/board** is a synchronous implementation. +Here is its listing: + + /* + * get the board + */ + static void board(struct afb_req req) + { + struct board *board; + struct json_object *description; + + /* retrieves the context for the session */ + board = board_of_req(req); + INFO(afbitf, "method 'board' called for boardid %d", board->id); + + /* describe the board */ + description = describe(board); + + /* send the board's description */ + afb_req_success(req, description, NULL); + } + +This examples show many aspects of writing a synchronous +verb implementation. Let summarize it: + +1. The function **board_of_req** retrieves the context stored +for the plugin: the board. + +2. The macro **INFO** sends a message of kind *INFO* +to the logging system. The global variable named **afbitf** +used represents the interface to afb-daemon. + +3. The function **describe** creates a json_object representing +the board. + +4. The function **afb_req_success** sends the reply, attaching to +it the object *description*. + +### The incoming request + +For any implementation, the request is received by a structure of type +**struct afb_req**. + +> Note that this is a PLAIN structure, not a pointer to a structure. + +The definition of **struct afb_req** is: + + /* + * Describes the request by plugins from afb-daemon + */ + struct afb_req { + const struct afb_req_itf *itf; /* the interfacing functions */ + void *closure; /* the closure for functions */ + }; + +It contains two pointers: one, *itf*, points to the functions needed +to handle the internal request represented by the second pointer, *closure*. + +> The structure must never be used directly. +> Insted, use the intended functions provided +> by afb-daemon and described here. + +*req* is used to get arguments of the request, to send +answer, to store session data. + +This object and its interface is defined and documented +in the file names *afb/afb-req-itf.h* + +The above example uses 2 times the request object *req*. + +The first time, it is used for retrieving the board attached to +the session of the request. + +The second time, it is used to send the reply: an object that +describes the current board. + +### Associating a context to the session + +When the plugin *tic-tac-toe* receives a request, it musts regain +the board that describes the game associated to the session. + +For a plugin, having data associated to a session is a common case. +This data is called the context of the plugin for the session. +For the plugin *tic-tac-toe*, the context is the board. + +The requests *afb_req* offer four functions for +storing and retrieving the context associated to the session. + +These functions are: + +- **afb_req_context_get**: + retrieves the context data stored for the plugin. + +- **afb_req_context_set**: + store the context data of the plugin. + +- **afb_req_context**: + retrieves the context data of the plugin, + if needed, creates the context and store it. + +- **afb_req_context_clear**: + reset the stored data. + +The plugin *tictactoe* use a convenient function to retrieve +its context: the board. This function is *board_of_req*: + + /* + * retrieves the board of the request + */ + static inline struct board *board_of_req(struct afb_req req) + { + return afb_req_context(req, (void*)get_new_board, (void*)release_board); + } + +The function **afb_req_context** ensure an existing context +for the session of the request. +Its two last arguments are functions. Here, the casts are required +to avoid a warning when compiling. + +Here is the definition of the function **afb_req_context** + + /* + * Gets the pointer stored by the plugin for the session of 'req'. + * If the stored pointer is NULL, indicating that no pointer was + * already stored, afb_req_context creates a new context by calling + * the function 'create_context' and stores it with the freeing function + * 'free_context'. + */ + static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*)) + { + void *result = afb_req_context_get(req); + if (result == NULL) { + result = create_context(); + afb_req_context_set(req, result, free_context); + } + return result; + } + +The second argument if the function that creates the context. +For the plugin *tic-tac-toe* it is the function **get_new_board**. +The function **get_new_board** creates a new board and set its +count of use to 1. The boards are counting their count of use +to free there ressources when no more used. + +The third argument if the function that frees the context. +For the plugin *tic-tac-toe* it is the function **release_board**. +The function **release_board** decrease the the count of use of +the board given as argument. If the use count decrease to zero, +the board data are freed. + +The definition of the other functions for dealing with contexts are: + + /* + * Gets the pointer stored by the plugin for the session of 'req'. + * When the plugin has not yet recorded a pointer, NULL is returned. + */ + void *afb_req_context_get(struct afb_req req); + + /* + * Stores for the plugin the pointer 'context' to the session of 'req'. + * The function 'free_context' will be called when the session is closed + * or if plugin stores an other pointer. + */ + void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*)); + + /* + * Frees the pointer stored by the plugin for the session of 'req' + * and sets it to NULL. + * + * Shortcut for: afb_req_context_set(req, NULL, NULL) + */ + static inline void afb_req_context_clear(struct afb_req req) + { + afb_req_context_set(req, NULL, NULL); + } + +### Sending the reply to a request + +Two kinds of replies can be made: successful replies and +failure replies. + +> Sending a reply to a request must be done at most one time. + +The two functions to send a reply of kind "success" are +**afb_req_success** and **afb_req_success_f**. + + /* + * Sends a reply of kind success to the request 'req'. + * The status of the reply is automatically set to "success". + * Its send the object 'obj' (can be NULL) with an + * informationnal comment 'info (can also be NULL). + */ + 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, ...); + +The two functions to send a reply of kind "failure" are +**afb_req_fail** and **afb_req_fail_f**. + + /* + * Sends a reply of kind failure to the request 'req'. + * The status of the reply is set to 'status' and an + * informationnal comment 'info' (can also be NULL) can be added. + * + * Note that calling afb_req_fail("success", info) is equivalent + * to call afb_req_success(NULL, info). Thus even if possible it + * is strongly recommanded to NEVER use "success" for status. + */ + 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, ...); + +Getting argument of invocation +------------------------------ + +Many verbs expect arguments. Afb-daemon let plugins +retrieve their arguments by name not by position. + +Arguments are given by the requests either through HTTP +or through WebSockets. + +For example, the verb **join** of the plugin **tic-tac-toe** +expects one argument: the *boardid* to join. Here is an extract: + + /* + * Join a board + */ + static void join(struct afb_req req) + { + struct board *board, *new_board; + const char *id; + + /* retrieves the context for the session */ + board = board_of_req(req); + INFO(afbitf, "method 'join' called for boardid %d", board->id); + + /* retrieves the argument */ + id = afb_req_value(req, "boardid"); + if (id == NULL) + goto bad_request; + ... + +The function **afb_req_value** search in the request *req* +for an argument whose name is given. When no argument of the +given name was passed, **afb_req_value** returns NULL. + +> The search is case sensitive. So the name *boardid* is not the +> same name than *BoardId*. But this must not be assumed so two +> expected names of argument should not differ only by case. + +### Basic functions for querying arguments + +The function **afb_req_value** is defined as below: + + /* + * Gets from the request 'req' the string value of the argument of 'name'. + * Returns NULL if when there is no argument of 'name'. + * Returns the value of the argument of 'name' otherwise. + * + * Shortcut for: afb_req_get(req, name).value + */ + static inline const char *afb_req_value(struct afb_req req, const char *name) + { + return afb_req_get(req, name).value; + } + +It is defined as a shortcut to call the function **afb_req_get**. +That function is defined as below: + + /* + * Gets from the request 'req' the argument of 'name'. + * Returns a PLAIN structure of type 'struct afb_arg'. + * When the argument of 'name' is not found, all fields of result are set to NULL. + * When the argument of 'name' is found, the fields are filled, + * in particular, the field 'result.name' is set to 'name'. + * + * There is a special name value: the empty string. + * The argument of name "" is defined only if the request was made using + * an HTTP POST of Content-Type "application/json". In that case, the + * argument of name "" receives the value of the body of the HTTP request. + */ + struct afb_arg afb_req_get(struct afb_req req, const char *name); + +That function takes 2 parameters: the request and the name +of the argument to retrieve. It returns a PLAIN structure of +type **struct afb_arg**. + +There is a special name that is defined when the request is +of type HTTP/POST with a Content-Type being application/json. +This name is **""** (the empty string). In that case, the value +of this argument of empty name is the string received as a body +of the post and is supposed to be a JSON string. + +The definition of **struct afb_arg** is: + + /* + * Describes an argument (or parameter) of a request + */ + struct afb_arg { + const char *name; /* name of the argument or NULL if invalid */ + const char *value; /* string representation of the value of the argument */ + /* original filename of the argument if path != NULL */ + const char *path; /* if not NULL, path of the received file for the argument */ + /* when the request is finalized this file is removed */ + }; + +The structure returns the data arguments that are known for the +request. This data include a field named **path**. This **path** +can be accessed using the function **afb_req_path** defined as +below: + + /* + * Gets from the request 'req' the path for file attached to the argument of 'name'. + * Returns NULL if when there is no argument of 'name' or when there is no file. + * Returns the path of the argument of 'name' otherwise. + * + * Shortcut for: afb_req_get(req, name).path + */ + static inline const char *afb_req_path(struct afb_req req, const char *name) + { + return afb_req_get(req, name).path; + } + +The path is only defined for HTTP/POST requests that send file. + +### Arguments for received files + +As it is explained just above, clients can send files using +HTTP/POST requests. + +Received files are attached to a arguments. For example, the +following HTTP fragment (from test/sample-post.html) +will send an HTTP/POST request to the method +**post/upload-image** with 2 arguments named *file* and +*hidden*. + +

Sample Post File

+
+ + +
+ +
+ +In that case, the argument named **file** has its value and its +path defined and not NULL. + +The value is the name of the file as it was +set by the HTTP client and is generally the filename on the +client side. + +The path is the path of the file saved on the temporary local storage +area of the application. This is a randomly generated and unic filename +not linked in any way with the original filename on the client. + +The plugin can use the file at the given path the way that it wants: +read, write, remove, copy, rename... +But when the reply is sent and the query is terminated, the file at +this path is destroyed if it still exist. + +### Arguments as a JSON object + +Plugins can get all the arguments as one single object. +This feature is provided by the function **afb_req_json** +that is defined as below: + + /* + * Gets from the request 'req' the json object hashing the arguments. + * The returned object must not be released using 'json_object_put'. + */ + struct json_object *afb_req_json(struct afb_req req); + +It returns a json object. This object depends on how the request was +made: + +- For HTTP requests, this is an object whose keys are the names of the +arguments and whose values are either a string for common arguments or +an object like { "file": "...", "path": "..." } + +- For WebSockets requests, the returned object is the object +given by the client transparently transported. + +> In fact, for Websockets requests, the function **afb_req_value** +> can be seen as a shortcut to +> ***json_object_get_string(json_object_object_get(afb_req_json(req), name))*** + +Initialisation of the plugin and declaration of verbs +----------------------------------------------------- + +To be active, the verbs of the plugin should be declared to +afb-daemon. And even more, the plugin itself must be recorded. + +The mechanism for doing this is very simple: when afb-need starts, +it loads the plugins that are listed in its argument or configuration. + +Loading a plugin follows the following steps: + +1. It loads the plugin using *dlopen*. + +2. It searchs for the symbol named **pluginAfbV1Register** using *dlsym*. +This symbol is assumed to be the exported initialisation function of the plugin. + +3. It build an interface object for the plugin. + +4. It calls the found function **pluginAfbV1Register** and pass it the pointer +to its interface. + +5. The function **pluginAfbV1Register** setup the plugin, initialize it. + +6. The function **pluginAfbV1Register** returns the pointer to a structure +that describes the plugin: its version, its name (prefix or API name), and the +list of its verbs. + +7. Afb-daemon checks that the returned version and name can be managed. +If it can manage it, the plugin and its verbs are recorded and can be used +when afb-daemon finishes it initialisation. + +Here is the listing of the function **pluginAfbV1Register** of the plugin +*tic-tac-toe*: + + /* + * activation function for registering the plugin called by afb-daemon + */ + const struct AFB_plugin *pluginAfbV1Register(const struct AFB_interface *itf) + { + afbitf = itf; // records the interface for accessing afb-daemon + return &plugin_description; // returns the description of the plugin + } + +This is a very small function because the *tic-tac-toe* plugin doesn't have initialisation step. +It merely record the daemon's interface and returns its descritption. + +The variable **afbitf** is a variable global to the plugin. It records the +interface to afb-daemon and is used for logging and pushing events. +Here is its declaration: + + /* + * the interface to afb-daemon + */ + const struct AFB_interface *afbitf; + +The description of the plugin is defined as below. + + /* + * array of the verbs exported to afb-daemon + */ + static const struct AFB_verb_desc_v1 plugin_verbs[] = { + /* VERB'S NAME SESSION MANAGEMENT FUNCTION TO CALL SHORT DESCRIPTION */ + { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" }, + { .name= "play", .session= AFB_SESSION_NONE, .callback= play, .info= "Tells the server to play" }, + { .name= "move", .session= AFB_SESSION_NONE, .callback= move, .info= "Tells the client move" }, + { .name= "board", .session= AFB_SESSION_NONE, .callback= board, .info= "Get the current board" }, + { .name= "level", .session= AFB_SESSION_NONE, .callback= level, .info= "Set the server level" }, + { .name= "join", .session= AFB_SESSION_CHECK,.callback= join, .info= "Join a board" }, + { .name= "undo", .session= AFB_SESSION_NONE, .callback= undo, .info= "Undo the last move" }, + { .name= "wait", .session= AFB_SESSION_NONE, .callback= wait, .info= "Wait for a change" }, + { .name= NULL } /* marker for end of the array */ + }; + + /* + * description of the plugin for afb-daemon + */ + static const struct AFB_plugin plugin_description = + { + /* description conforms to VERSION 1 */ + .type= AFB_PLUGIN_VERSION_1, + .v1= { /* fills the v1 field of the union when AFB_PLUGIN_VERSION_1 */ + .prefix= "tictactoe", /* the API name (or plugin name or prefix) */ + .info= "Sample tac-tac-toe game", /* short description of of the plugin */ + .verbs = plugin_verbs /* the array describing the verbs of the API */ + } + }; + +The structure **plugin_description** describes the plugin. +It declares the type and version of the plugin, its name, a description +and a list of its verbs. + +The list of verbs is an array of structures describing the verbs and terminated by a marker: +a verb whose name is NULL. + +The description of the verbs for this version is made of 4 fields: + +- the name of the verbs, + +- the session management flags, + +- the implementation function to be call for the verb, + +- a short description. + +The structure describing verbs is defined as follows: + + /* + * Description of one verb of the API provided by the plugin + * This enumeration is valid for plugins of type 1 + */ + struct AFB_verb_desc_v1 + { + const char *name; /* name of the verb */ + enum AFB_session_v1 session; /* authorisation and session requirements of the verb */ + void (*callback)(struct afb_req req); /* callback function implementing the verb */ + const char *info; /* textual description of the verb */ + }; + +For technical reasons, the enumeration **enum AFB_session_v1** is not exactly an +enumeration but the wrapper of constant definitions that can be mixed using bitwise or +(the C operator |). + +The constants that can bit mixed are: + +Constant name | Meaning +-------------------------|------------------------------------------------------------- +**AFB_SESSION_CREATE** | Equals to AFB_SESSION_LOA_EQ_0|AFB_SESSION_RENEW +**AFB_SESSION_CLOSE** | Closes the session after the reply and set the LOA to 0 +**AFB_SESSION_RENEW** | Refreshes the token of authentification +**AFB_SESSION_CHECK** | Just requires the token authentification +**AFB_SESSION_LOA_LE_0** | Requires the current LOA to be lesser then or equal to 0 +**AFB_SESSION_LOA_LE_1** | Requires the current LOA to be lesser then or equal to 1 +**AFB_SESSION_LOA_LE_2** | Requires the current LOA to be lesser then or equal to 2 +**AFB_SESSION_LOA_LE_3** | Requires the current LOA to be lesser then or equal to 3 +**AFB_SESSION_LOA_GE_0** | Requires the current LOA to be greater then or equal to 0 +**AFB_SESSION_LOA_GE_1** | Requires the current LOA to be greater then or equal to 1 +**AFB_SESSION_LOA_GE_2** | Requires the current LOA to be greater then or equal to 2 +**AFB_SESSION_LOA_GE_3** | Requires the current LOA to be greater then or equal to 3 +**AFB_SESSION_LOA_EQ_0** | Requires the current LOA to be equal to 0 +**AFB_SESSION_LOA_EQ_1** | Requires the current LOA to be equal to 1 +**AFB_SESSION_LOA_EQ_2** | Requires the current LOA to be equal to 2 +**AFB_SESSION_LOA_EQ_3** | Requires the current LOA to be equal to 3 + +If any of this flags is set, afb-daemon requires the token authentification +as if the flag **AFB_SESSION_CHECK** had been set. + +The special value **AFB_SESSION_NONE** is zero and can be used to avoid any check. + +> Note that **AFB_SESSION_CREATE** and **AFB_SESSION_CLOSE** might be removed in later versions. + +Sending messages to the log system +---------------------------------- + +Afb-daemon provides 4 levels of verbosity and 5 verbs for logging messages. + +The verbosity is managed. Options allow the change the verbosity of afb-daemon +and the verbosity of the plugins can be set plugin by plugin. + +The verbs for logging messages are defined as macros that test the +verbosity level and that call the real logging function only if the +message must be output. This avoid evaluation of arguments of the +formatting messages if the message must not be output. + +### Verbs for logging messages + +The 5 logging verbs are: + +Macro | Verbosity | Meaning | syslog level +--------|:---------:|-----------------------------------|:-----------: +ERROR | 0 | Error conditions | 3 +WARNING | 1 | Warning conditions | 4 +NOTICE | 1 | Normal but significant condition | 5 +INFO | 2 | Informational | 6 +DEBUG | 3 | Debug-level messages | 7 + +You can note that the 2 verbs **WARNING** and **INFO** have the same level +of verbosity. But they don't have the same *syslog level*. It means that +they are output with a different level on the logging system. + +All of these verbs have the same signature: + + void ERROR(const struct AFB_interface *afbitf, const char *message, ...); + +The first argument **afbitf** is the interface to afb daemon that the +plugin received at its initialisation when **pluginAfbV1Register** was called. + +The second argument **message** is a formatting string compatible with printf/sprintf. + +The remaining arguments are arguments of the formating message like for printf. + +### Managing verbosity + +Depending on the level of verbosity, the messages are output or not. +The following table explains what messages will be output depending +ont the verbosity level. + +Level of verbosity | Outputed macro +:-----------------:|-------------------------- + 0 | ERROR + 1 | ERROR + WARNING + NOTICE + 2 | ERROR + WARNING + NOTICE + INFO + 3 | ERROR + WARNING + NOTICE + INFO + DEBUG + +### Output format and destination + +The syslog level is used for forging a prefix to the message. +The prefixes are: + +syslog level | prefix +:-----------:|--------------- + 0 | <0> EMERGENCY + 1 | <1> ALERT + 2 | <2> CRITICAL + 3 | <3> ERROR + 4 | <4> WARNING + 5 | <5> NOTICE + 6 | <6> INFO + 7 | <7> DEBUG + + +The message is issued to the standard error. +The final destination of the message depends on how the systemd service +was configured through the variable **StandardError**: It can be +journal, syslog or kmsg. (See man sd-daemon). + +Sending events +-------------- + + +Writing an asynchronous verb implementation +------------------------------------------- + + +How to build a plugin +--------------------- + +Afb-daemon provides a *pkg-config* configuration file that can be +queried by the name **afb-daemon**. +This configuration file provides data that should be used +for compiling plugins. Examples: + + $ pkg-config --cflags afb-daemon + $ pkg-config --libs afb-daemon + +### Example for cmake meta build system + +This example is the extract for building the plugin *afm-main* using *CMAKE*. + + pkg_check_modules(afb afb-daemon) + if(afb_FOUND) + message(STATUS "Creation afm-main-plugin for AFB-DAEMON") + add_library(afm-main-plugin MODULE afm-main-plugin.c) + target_compile_options(afm-main-plugin PRIVATE ${afb_CFLAGS}) + target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS}) + target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES}) + set_target_properties(afm-main-plugin PROPERTIES + PREFIX "" + LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map" + ) + install(TARGETS afm-main-plugin LIBRARY DESTINATION ${plugin_dir}) + else() + message(STATUS "Not creating the plugin for AFB-DAEMON") + endif() + +Let now describe some of these lines. + + pkg_check_modules(afb afb-daemon) + +This first lines searches to the *pkg-config* configuration file for +**afb-daemon**. Resulting data are stored in the following variables: + +Variable | Meaning +------------------|------------------------------------------------ +afb_FOUND | Set to 1 if afb-daemon plugin development files exist +afb_LIBRARIES | Only the libraries (w/o the '-l') for compiling afb-daemon plugins +afb_LIBRARY_DIRS | The paths of the libraries (w/o the '-L') for compiling afb-daemon plugins +afb_LDFLAGS | All required linker flags for compiling afb-daemon plugins +afb_INCLUDE_DIRS | The '-I' preprocessor flags (w/o the '-I') for compiling afb-daemon plugins +afb_CFLAGS | All required cflags for compiling afb-daemon plugins + +If development files are found, the plugin can be added to the set of +target to build. + + add_library(afm-main-plugin MODULE afm-main-plugin.c) + +This line asks to create a shared library having only the +source file afm-main-plugin.c (that is compiled). +The default name of the created shared object is +**libafm-main-plugin.so**. + + set_target_properties(afm-main-plugin PROPERTIES + PREFIX "" + LINK_FLAGS "-Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/afm-main-plugin.export-map" + ) + +This lines are doing two things: + +1. It renames the built library from **libafm-main-plugin.so** to **afm-main-plugin.so** +by removing the implicitely added prefix *lib*. This step is not mandatory +at all because afb-daemon doesn't check names of files when loading it. +The only convention that use afb-daemon is that extension is **.so** +but this convention is used only when afb-daemon discovers plugin +from a directory hierarchy. + +2. It applies a version script at link to only export the conventional name +of the entry point: **pluginAfbV1Register**. See below. By default, the linker +that creates the shared object exports all the public symbols (C functions that +are not **static**). + +Next line are: + + target_include_directories(afm-main-plugin PRIVATE ${afb_INCLUDE_DIRS}) + target_link_libraries(afm-main-plugin utils ${afb_LIBRARIES}) + +As you can see it uses the variables computed by ***pkg_check_modules(afb afb-daemon)*** +to configure the compiler and the linker. + +### Exporting the function pluginAfbV1Register + +The function **pluginAfbV1Register** must be exported. This can be achieved +using a version script when linking. Here is the version script that is +used for *tic-tac-toe* (plugins/samples/export.map). + + { global: pluginAfbV1Register; local: *; }; + +This sample [version script](https://sourceware.org/binutils/docs-2.26/ld/VERSION.html#VERSION) +exports as global the symbol *pluginAfbV1Register* and hides any +other symbols. + +This version script is added to the link options using the +option **--version-script=export.map** is given directly to the +linker or using th option **-Wl,--version-script=export.map** +when the option is given to the C compiler. + +### Building within yocto + +Adding a dependency to afb-daemon is enough. See below: + + DEPENDS += " afb-daemon " + diff --git a/doc/doc.css b/doc/doc.css index d100bd1c..27be9dc7 100644 --- a/doc/doc.css +++ b/doc/doc.css @@ -4,7 +4,7 @@ body { color: #000; } -h1, h2, h3 { +h1, h2, h3, h4 { color: #306; text-decoration: underline; } @@ -27,3 +27,13 @@ blockquote { font: bolder; padding: 0.7em 1.5em; } + +table { + margin-left: 2em; + background-color: #dff; + outline: 0.25em solid #a6f; +/* padding: 0.25em;*/ +} +thead {background-color: #a6f;} +tr:nth-child(even) {background-color: #aee;} +td { padding: 0.1em 0.5em; } diff --git a/doc/writing-afb-plugins.html b/doc/writing-afb-plugins.html deleted file mode 100644 index 712d30ee..00000000 --- a/doc/writing-afb-plugins.html +++ /dev/null @@ -1,783 +0,0 @@ - - - - - - -

HOWTO WRITE a PLUGIN for AFB-DAEMON

- -
version: 1
-Date:    25 May 2016
-Author:  José Bollo
-
- -

- -

Summary

- -

The binder afb-daemon serves files through -the HTTP protocol and offers access to API’s through -HTTP or WebSocket protocol.

- -

The plugins are used to add API’s to afb-daemon. -This part describes how to write a plugin for afb-daemon. -Excepting this summary, this part is intended to be read -by developpers.

- -

Before going into details, through a tiny example, -a short overview plugins basis is needed.

- -

Nature of a plugin

- -

A plugin is a separate piece of code made of a shared library. -The plugin is loaded and activated by afb-daemon when afb-daemon -starts.

- -

Technically, a plugin is not linked to any library of afb-daemon.

- -

Kinds of plugins

- -

There is two kinds of plugins: application plugins and service -plugins.

- -

Application plugins

- -

Application plugins are intended to be instanciated for each -application: when an application using that plugin is started, -its binder starts a new instance of the plugin.

- -

It means that the application plugins mainly have only one -context to manage for one client.

- -

Service plugins

- -

Service plugins are intended to be instanciated only one time -only and connected to many clients.

- -

So either it does not manage context at all or otherwise, -if it manages context, it should be able to manage one context -per client.

- -

In details, it may be useful to have service plugins at a user -level.

- -

Live cycle of a plugin within afb-daemon

- -

The plugins are loaded and activated when afb-daemon starts.

- -

At start, the plugin initialise itself. -If it fails to initialise then afb-daemon stops.

- -

Conversely, if it success to initialize, it must declare -a name, that must be unique, and a list of API’s verbs.

- -

When initialized, the functions implementing the API’s verbs -of the plugin are activated on call.

- -

At the end, nothing special is done by afb-daemon. -Consequently, developpers of plugins should use ‘atexit’ -or ‘on_exit’ during initialisation if they need to -perform specific actions when stopping.

- -

Content of a plugin

- -

For afb-daemon, a plugin contains 2 different -things: names and functions.

- -

There is two kind of names: - - the name of the plugin, - - the names of the verbs.

- -

There is two kind of functions: - - the initialisation function - - functions implementing verbs

- -

Afb-daemon translates the name of the method that is -invoked to a pair of API and verb names. For example, -the method named foo/bar translated to the API -name foo and the verb name bar. -To serve it, afb-daemon search the plugin that record -the name foo and if it also recorded the verb bar, -it calls the implementation function declared for this verb.

- -

Afb-daemon make no distinction between lower case -and upper case when searching for a method. -Thus, The names TicTacToe/Board and tictactoe/borad -are equals.

- -

The name of the plugin

- -

The name of the plugin is also known as the name -of the API that defines the plugin.

- -

This name is also known as the prefix.

- -

The name of a plugin MUST be unique within afb-daemon.

- -

For example, when a client of afb-daemon -calls a method named foo/bar. Afb-daemon -extracts the prefix foo and the suffix bar. -foo is the API name and must match a plugin name, -the plugin that implements the verb bar.

- -

Names of verbs

- -

Each plugin exposes a set of verbs that can be called -by client of afb-daemon.

- -

The name of a verb MUST be unique within a plugin.

- -

Plugins link verbs to functions that are called -when clients emit requests for that verb.

- -

For example, when a client of afb-daemon -calls a method named foo/bar.

- -

The initialisation function

- -

The initialisation function serves several purposes.

- -
    -

  1. It allows afb-daemon to check the version -of the plugin using the name of the initialisation -functions that it found. Currently, the initialisation -function is named pluginAfbV1Register. It identifies -the first version of plugins.

    2. -

  2. It allows the plugin to initialise itself.

    3. -

  3. It serves to the plugin to declare names, descriptions, -requirements and implmentations of the verbs that it exposes.

    4. -
- - -

Functions implementing verbs

- -

When a method is called, afb-daemon constructs a request -object and pass it to the implementation function for verb -within the plugin of the API.

- -

An implementation function receives a request object that -is used to get arguments of the request, to send -answer, to store session data.

- -

A plugin MUST send an answer to the request.

- -

But it is not mandatory to send the answer -before to return from the implementing function. -This behaviour is important for implementing -asynchronous actions.

- -

Implementation functions that always reply to the request -before returning are named synchronous implementations. -Those that don’t always reply to the request before -returning are named asynchronous implementations.

- -

Asynchronous implementations typically initiate an -asynchronous action and record to send the reply -on completion of this action.

- -

The Tic-Tac-Toe example

- -

This part explains how to write an afb-plugin. -For the sake of being practical we will use many -examples from the tic-tac-toe example. -This plugin example is in plugins/samples/tic-tac-toe.c.

- -

This plugin is named tictactoe.

- -

Choosing names

- -

The designer of a plugin must defines names for its plugin -(or its API) and for the verbs of its API. He also -must defines names for arguments given by name.

- -

While forging names, the designer should take into account -the rules for making valid names and some rules that make -the names easy to use across plaforms.

- -

The names and strings used ALL are UTF-8 encoded.

- -

Names for API (plugin)

- -

The names of the API are checked. -All characters are authorised except:

- -
    -
  • the control characters (\u0000 .. \u001f)
    • -
  • the characters of the set { ‘ ’, ‘“’, ‘#’, ‘%’, ‘&’, -‘’‘, ’/‘, ’?‘, ’`‘, ’\x7f' }
    • -
- - -

In other words the set of forbidden characters is -{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027, - \u002f, \u003f, \u0060, \u007f }.

- -

Afb-daemon make no distinction between lower case -and upper case when searching for an API by its name.

- -

Names for verbs

- -

The names of the verbs are not checked.

- -

However, the validity rules for verb’s names are the -same as for API’s names except that the dot (.) character -is forbidden.

- -

Afb-daemon make no distinction between lower case -and upper case when searching for an API by its name.

- -

Names for arguments

- -

The names for arguments are not restricted and can be -anything.

- -

The arguments are searched with the case sensitive -string comparison. Thus the names “index” and “Index” -are not the same.

- -

Forging names widely available

- -

The key names of javascript object can be almost -anything using the arrayed notation:

- -
object[key] = value
-
- -

That is not the case with the dot notation:

- -
object.key = value
-
- -

Using the dot notation, the key must be a valid javascript -identifier.

- -

For this reason, the chosen names should better be -valid javascript identifier.

- -

It is also a good practice, even for arguments, to not -rely on the case sensitivity and to avoid the use of -names different only by the case.

- -

Options to set when compiling plugins

- -

Afb-daemon provides a configuration file for pkg-config. -Typing the command

- -
pkg-config --cflags afb-daemon
-
- -

will print the flags to use for compiling, like this:

- -
$ pkg-config --cflags afb-daemon
--I/opt/local/include -I/usr/include/json-c 
-
- -

For linking, you should use

- -
$ pkg-config --libs afb-daemon
--ljson-c
-
- -

As you see, afb-daemon automatically includes dependency to json-c. -This is done through the Requires keyword of pkg-config.

- -

If this behaviour is a problem, let us know.

- -

Header files to include

- -

The plugin tictactoe has the following lines for its includes:

- -
#define _GNU_SOURCE
-#include <stdio.h>
-#include <string.h>
-#include <json-c/json.h>
-#include <afb/afb-plugin.h>
-
- -

The header afb/afb-plugin.h includes all the features that a plugin -needs except two foreign header that must be included by the plugin -if it needs it:

- -
    -
  • json-c/json.h: this header must be include to handle json objects;
    • -
  • systemd/sd-event.h: this must be include to access the main loop;
    • -
  • systemd/sd-bus.h: this may be include to use dbus connections.
    • -
- - -

The tictactoe plugin does not use systemd features so it is not included.

- -

When including afb/afb-plugin.h, the macro _GNU_SOURCE must be -defined.

- -

Writing a synchronous verb implementation

- -

The verb tictactoe/board is a synchronous implementation. -Here is its listing:

- -
/*
- * get the board
- */
-static void board(struct afb_req req)
-{
-        struct board *board;
-        struct json_object *description;
-
-        /* retrieves the context for the session */
-        board = board_of_req(req);
-        INFO(afbitf, "method 'board' called for boardid %d", board->id);
-
-        /* describe the board */
-        description = describe(board);
-
-        /* send the board's description */
-        afb_req_success(req, description, NULL);
-}
-
- -

This examples show many aspects of writing a synchronous -verb implementation. Let summarize it:

- -
    -

  1. The function board_of_req retrieves the context stored -for the plugin: the board.

    2. -

  2. The macro INFO sends a message of kind INFO -to the logging system. The global variable named afbitf -used represents the interface to afb-daemon.

    3. -

  3. The function describe creates a json_object representing -the board.

    4. -

  4. The function afb_req_success sends the reply, attaching to -it the object description.

    5. -
- - -

The incoming request

- -

For any implementation, the request is received by a structure of type -struct afb_req.

- -

Note that this is a PLAIN structure, not a pointer to a structure.

- -

The definition of struct afb_req is:

- -
/*
- * Describes the request by plugins from afb-daemon
- */
-struct afb_req {
-        const struct afb_req_itf *itf;  /* the interfacing functions */
-        void *closure;          /* the closure for functions */
-};
-
- -

It contains two pointers: one, itf, points to the functions needed -to handle the internal request represented by the second pointer, closure.

- -

The structure must never be used directly. -Insted, use the intended functions provided -by afb-daemon and described here.

- -

req is used to get arguments of the request, to send -answer, to store session data.

- -

This object and its interface is defined and documented -in the file names afb/afb-req-itf.h

- -

The above example uses 2 times the request object req.

- -

The first time, it is used for retrieving the board attached to -the session of the request.

- -

The second time, it is used to send the reply: an object that -describes the current board.

- -

Associating a context to the session

- -

When the plugin tic-tac-toe receives a request, it musts regain -the board that describes the game associated to the session.

- -

For a plugin, having data associated to a session is a common case. -This data is called the context of the plugin for the session. -For the plugin tic-tac-toe, the context is the board.

- -

The requests afb_req offer four functions for -storing and retrieving the context associated to the session.

- -

These functions are:

- -
    -

  • afb_req_context_get: -retrieves the context data stored for the plugin.

    • -

  • afb_req_context_set: -store the context data of the plugin.

    • -

  • afb_req_context: -retrieves the context data of the plugin, -if needed, creates the context and store it.

    • -

  • afb_req_context_clear: -reset the stored data.

    • -
- - -

The plugin tictactoe use a convenient function to retrieve -its context: the board. This function is board_of_req:

- -
/*
- * retrieves the board of the request
- */
-static inline struct board *board_of_req(struct afb_req req)
-{
-        return afb_req_context(req, (void*)get_new_board, (void*)release_board);
-}
-
- -

The function afb_req_context ensure an existing context -for the session of the request. -Its two last arguments are functions. Here, the casts are required -to avoid a warning when compiling.

- -

Here is the definition of the function afb_req_context

- -
/*
- * Gets the pointer stored by the plugin for the session of 'req'.
- * If the stored pointer is NULL, indicating that no pointer was
- * already stored, afb_req_context creates a new context by calling
- * the function 'create_context' and stores it with the freeing function
- * 'free_context'.
- */
-static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
-{
-        void *result = afb_req_context_get(req);
-        if (result == NULL) {
-                result = create_context();
-                afb_req_context_set(req, result, free_context);
-        }
-        return result;
-}
-
- -

The second argument if the function that creates the context. -For the plugin tic-tac-toe it is the function get_new_board. -The function get_new_board creates a new board and set its -count of use to 1. The boards are counting their count of use -to free there ressources when no more used.

- -

The third argument if the function that frees the context. -For the plugin tic-tac-toe it is the function release_board. -The function release_board decrease the the count of use of -the board given as argument. If the use count decrease to zero, -the board data are freed.

- -

The definition of the other functions for dealing with contexts are:

- -
/*
- * Gets the pointer stored by the plugin for the session of 'req'.
- * When the plugin has not yet recorded a pointer, NULL is returned.
- */
-void *afb_req_context_get(struct afb_req req);
-
-/*
- * Stores for the plugin the pointer 'context' to the session of 'req'.
- * The function 'free_context' will be called when the session is closed
- * or if plugin stores an other pointer.
- */
-void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
-
-/*
- * Frees the pointer stored by the plugin for the session of 'req'
- * and sets it to NULL.
- *
- * Shortcut for: afb_req_context_set(req, NULL, NULL)
- */
-static inline void afb_req_context_clear(struct afb_req req)
-{
-        afb_req_context_set(req, NULL, NULL);
-}
-
- -

Sending the reply to a request

- -

Two kinds of replies can be made: successful replies and -failure replies.

- -

Sending a reply to a request must be done at most one time.

- -

The two functions to send a reply of kind “success” are -afb_req_success and afb_req_success_f.

- -
/*
- * Sends a reply of kind success to the request 'req'.
- * The status of the reply is automatically set to "success".
- * Its send the object 'obj' (can be NULL) with an
- * informationnal comment 'info (can also be NULL).
- */
-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, ...);
-
- -

The two functions to send a reply of kind “failure” are -afb_req_fail and afb_req_fail_f.

- -
/*
- * Sends a reply of kind failure to the request 'req'.
- * The status of the reply is set to 'status' and an
- * informationnal comment 'info' (can also be NULL) can be added.
- *
- * Note that calling afb_req_fail("success", info) is equivalent
- * to call afb_req_success(NULL, info). Thus even if possible it
- * is strongly recommanded to NEVER use "success" for status.
- */
-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, ...);
-
- -

Getting argument of invocation

- -

Many verbs expect arguments. Afb-daemon let plugins -retrieve their arguments by name not by position.

- -

Arguments are given by the requests either through HTTP -or through WebSockets.

- -

For example, the verb join of the plugin tic-tac-toe -expects one argument: the boardid to join. Here is an extract:

- -
/*
- * Join a board
- */
-static void join(struct afb_req req)
-{
-        struct board *board, *new_board;
-        const char *id;
-
-        /* retrieves the context for the session */
-        board = board_of_req(req);
-        INFO(afbitf, "method 'join' called for boardid %d", board->id);
-
-        /* retrieves the argument */
-        id = afb_req_value(req, "boardid");
-        if (id == NULL)
-                goto bad_request;
-        ...
-
- -

The function afb_req_value search in the request req -for an argument whose name is given. When no argument of the -given name was passed, afb_req_value returns NULL.

- -

The search is case sensitive. So the name boardid is not the -same name than BoardId. But this must not be assumed so two -expected names of argument should not differ only by case.

- -

Basic functions for querying arguments

- -

The function afb_req_value is defined as below:

- -
/*
- * Gets from the request 'req' the string value of the argument of 'name'.
- * Returns NULL if when there is no argument of 'name'.
- * Returns the value of the argument of 'name' otherwise.
- *
- * Shortcut for: afb_req_get(req, name).value
- */
-static inline const char *afb_req_value(struct afb_req req, const char *name)
-{
-        return afb_req_get(req, name).value;
-}
-
- -

It is defined as a shortcut to call the function afb_req_get. -That function is defined as below:

- -
/*
- * Gets from the request 'req' the argument of 'name'.
- * Returns a PLAIN structure of type 'struct afb_arg'.
- * When the argument of 'name' is not found, all fields of result are set to NULL.
- * When the argument of 'name' is found, the fields are filled,
- * in particular, the field 'result.name' is set to 'name'.
- *
- * There is a special name value: the empty string.
- * The argument of name "" is defined only if the request was made using
- * an HTTP POST of Content-Type "application/json". In that case, the
- * argument of name "" receives the value of the body of the HTTP request.
- */
-struct afb_arg afb_req_get(struct afb_req req, const char *name);
-
- -

That function takes 2 parameters: the request and the name -of the argument to retrieve. It returns a PLAIN structure of -type struct afb_arg.

- -

There is a special name that is defined when the request is -of type HTTP/POST with a Content-Type being application/json. -This name is “” (the empty string). In that case, the value -of this argument of empty name is the string received as a body -of the post and is supposed to be a JSON string.

- -

The definition of struct afb_arg is:

- -
/*
- * Describes an argument (or parameter) of a request
- */
-struct afb_arg {
-        const char *name;   /* name of the argument or NULL if invalid */
-        const char *value;  /* string representation of the value of the argument */
-                                /* original filename of the argument if path != NULL */
-        const char *path;   /* if not NULL, path of the received file for the argument */
-                                /* when the request is finalized this file is removed */
-};
-
- -

The structure returns the data arguments that are known for the -request. This data include a field named path. This path -can be accessed using the function afb_req_path defined as -below:

- -
/*
- * Gets from the request 'req' the path for file attached to the argument of 'name'.
- * Returns NULL if when there is no argument of 'name' or when there is no file.
- * Returns the path of the argument of 'name' otherwise.
- *
- * Shortcut for: afb_req_get(req, name).path
- */
-static inline const char *afb_req_path(struct afb_req req, const char *name)
-{
-        return afb_req_get(req, name).path;
-}
-
- -

The path is only defined for HTTP/POST requests that send file.

- -

Arguments for received files

- -

As it is explained just above, clients can send files using -HTTP/POST requests.

- -

Received files are attached to a arguments. For example, the -following HTTP fragment (from test/sample-post.html) -will send an HTTP/POST request to the method -post/upload-image with 2 arguments named file and -hidden.

- -
<h2>Sample Post File</h2>
-<form enctype="multipart/form-data">
-    <input type="file" name="file" />
-    <input type="hidden" name="hidden" value="bollobollo" />
-    <br>
-    <button formmethod="POST" formaction="api/post/upload-image">Post File</button>
-</form>
-
- -

In that case, the argument named file has its value and its -path defined and not NULL.

- -

The value is the name of the file as it was -set by the HTTP client and is generally the filename on the -client side.

- -

The path is the path of the file saved on the temporary local storage -area of the application. This is a randomly generated and unic filename -not linked in any way with the original filename on the client.

- -

The plugin can use the file at the given path the way that it wants: -read, write, remove, copy, rename… -But when the reply is sent and the query is terminated, the file at -this path is destroyed if it still exist.

- -

Arguments as a JSON object

- -

Plugins can get all the arguments as one single object. -This feature is provided by the function afb_req_json -that is defined as below:

- -
/*
- * Gets from the request 'req' the json object hashing the arguments.
- * The returned object must not be released using 'json_object_put'.
- */
-struct json_object *afb_req_json(struct afb_req req);
-
- -

It returns a json object. This object depends on how the request was -made:

- -
    -

  • For HTTP requests, this is an object whose keys are the names of the -arguments and whose values are either a string for common arguments or -an object like { “file”: “…”, “path”: “…” }

    • -

  • For WebSockets requests, the returned object is the object -given by the client transparently transported.

    • -
- - -

In fact, for Websockets requests, the function afb_req_value -can be seen as a shortcut to -json_object_get_string(json_object_object_get(afb_req_json(req), name))

- -

Sending messages to the log system

- -

How to build a plugin

- -

Afb-daemon provides a pkg-config configuration file.

- - diff --git a/doc/writing-afb-plugins.md b/doc/writing-afb-plugins.md deleted file mode 100644 index 7611600f..00000000 --- a/doc/writing-afb-plugins.md +++ /dev/null @@ -1,703 +0,0 @@ -HOWTO WRITE a PLUGIN for AFB-DAEMON -=================================== - version: 1 - Date: 25 May 2016 - Author: José Bollo - -TABLE-OF-CONTENT-HERE - -Summary -------- - -The binder afb-daemon serves files through -the HTTP protocol and offers access to API's through -HTTP or WebSocket protocol. - -The plugins are used to add API's to afb-daemon. -This part describes how to write a plugin for afb-daemon. -Excepting this summary, this part is intended to be read -by developpers. - -Before going into details, through a tiny example, -a short overview plugins basis is needed. - -### Nature of a plugin - -A plugin is a separate piece of code made of a shared library. -The plugin is loaded and activated by afb-daemon when afb-daemon -starts. - -Technically, a plugin is not linked to any library of afb-daemon. - -### Kinds of plugins - -There is two kinds of plugins: application plugins and service -plugins. - -#### Application plugins - -Application plugins are intended to be instanciated for each -application: when an application using that plugin is started, -its binder starts a new instance of the plugin. - -It means that the application plugins mainly have only one -context to manage for one client. - -#### Service plugins - -Service plugins are intended to be instanciated only one time -only and connected to many clients. - -So either it does not manage context at all or otherwise, -if it manages context, it should be able to manage one context -per client. - -In details, it may be useful to have service plugins at a user -level. - -### Live cycle of a plugin within afb-daemon - -The plugins are loaded and activated when afb-daemon starts. - -At start, the plugin initialise itself. -If it fails to initialise then afb-daemon stops. - -Conversely, if it success to initialize, it must declare -a name, that must be unique, and a list of API's verbs. - -When initialized, the functions implementing the API's verbs -of the plugin are activated on call. - -At the end, nothing special is done by afb-daemon. -Consequently, developpers of plugins should use 'atexit' -or 'on_exit' during initialisation if they need to -perform specific actions when stopping. - -### Content of a plugin - -For afb-daemon, a plugin contains 2 different -things: names and functions. - -There is two kind of names: - - the name of the plugin, - - the names of the verbs. - -There is two kind of functions: - - the initialisation function - - functions implementing verbs - -Afb-daemon translates the name of the method that is -invoked to a pair of API and verb names. For example, -the method named **foo/bar** translated to the API -name **foo** and the verb name **bar**. -To serve it, afb-daemon search the plugin that record -the name **foo** and if it also recorded the verb **bar**, -it calls the implementation function declared for this verb. - -Afb-daemon make no distinction between lower case -and upper case when searching for a method. -Thus, The names **TicTacToe/Board** and **tictactoe/borad** -are equals. - -#### The name of the plugin - -The name of the plugin is also known as the name -of the API that defines the plugin. - -This name is also known as the prefix. - -The name of a plugin MUST be unique within afb-daemon. - -For example, when a client of afb-daemon -calls a method named **foo/bar**. Afb-daemon -extracts the prefix **foo** and the suffix **bar**. -**foo** is the API name and must match a plugin name, -the plugin that implements the verb **bar**. - -#### Names of verbs - -Each plugin exposes a set of verbs that can be called -by client of afb-daemon. - -The name of a verb MUST be unique within a plugin. - -Plugins link verbs to functions that are called -when clients emit requests for that verb. - -For example, when a client of afb-daemon -calls a method named **foo/bar**. - -#### The initialisation function - -The initialisation function serves several purposes. - -1. It allows afb-daemon to check the version -of the plugin using the name of the initialisation -functions that it found. Currently, the initialisation -function is named **pluginAfbV1Register**. It identifies -the first version of plugins. - -2. It allows the plugin to initialise itself. - -3. It serves to the plugin to declare names, descriptions, -requirements and implmentations of the verbs that it exposes. - -#### Functions implementing verbs - -When a method is called, afb-daemon constructs a request -object and pass it to the implementation function for verb -within the plugin of the API. - -An implementation function receives a request object that -is used to get arguments of the request, to send -answer, to store session data. - -A plugin MUST send an answer to the request. - -But it is not mandatory to send the answer -before to return from the implementing function. -This behaviour is important for implementing -asynchronous actions. - -Implementation functions that always reply to the request -before returning are named *synchronous implementations*. -Those that don't always reply to the request before -returning are named *asynchronous implementations*. - -Asynchronous implementations typically initiate an -asynchronous action and record to send the reply -on completion of this action. - -The Tic-Tac-Toe example ------------------------ - -This part explains how to write an afb-plugin. -For the sake of being practical we will use many -examples from the tic-tac-toe example. -This plugin example is in *plugins/samples/tic-tac-toe.c*. - -This plugin is named ***tictactoe***. - -Choosing names --------------- - -The designer of a plugin must defines names for its plugin -(or its API) and for the verbs of its API. He also -must defines names for arguments given by name. - -While forging names, the designer should take into account -the rules for making valid names and some rules that make -the names easy to use across plaforms. - -The names and strings used ALL are UTF-8 encoded. - -### Names for API (plugin) - -The names of the API are checked. -All characters are authorised except: - -- the control characters (\u0000 .. \u001f) -- the characters of the set { ' ', '"', '#', '%', '&', - '\'', '/', '?', '`', '\x7f' } - -In other words the set of forbidden characters is -{ \u0000..\u0020, \u0022, \u0023, \u0025..\u0027, - \u002f, \u003f, \u0060, \u007f }. - -Afb-daemon make no distinction between lower case -and upper case when searching for an API by its name. - -### Names for verbs - -The names of the verbs are not checked. - -However, the validity rules for verb's names are the -same as for API's names except that the dot (.) character -is forbidden. - -Afb-daemon make no distinction between lower case -and upper case when searching for an API by its name. - -### Names for arguments - -The names for arguments are not restricted and can be -anything. - -The arguments are searched with the case sensitive -string comparison. Thus the names "index" and "Index" -are not the same. - -### Forging names widely available - -The key names of javascript object can be almost -anything using the arrayed notation: - - object[key] = value - -That is not the case with the dot notation: - - object.key = value - -Using the dot notation, the key must be a valid javascript -identifier. - -For this reason, the chosen names should better be -valid javascript identifier. - -It is also a good practice, even for arguments, to not -rely on the case sensitivity and to avoid the use of -names different only by the case. - -Options to set when compiling plugins -------------------------------------- - -Afb-daemon provides a configuration file for *pkg-config*. -Typing the command - - pkg-config --cflags afb-daemon - -will print the flags to use for compiling, like this: - - $ pkg-config --cflags afb-daemon - -I/opt/local/include -I/usr/include/json-c - -For linking, you should use - - $ pkg-config --libs afb-daemon - -ljson-c - -As you see, afb-daemon automatically includes dependency to json-c. -This is done through the **Requires** keyword of pkg-config. - -If this behaviour is a problem, let us know. - -Header files to include ------------------------ - -The plugin *tictactoe* has the following lines for its includes: - - #define _GNU_SOURCE - #include - #include - #include - #include - -The header *afb/afb-plugin.h* includes all the features that a plugin -needs except two foreign header that must be included by the plugin -if it needs it: - -- *json-c/json.h*: this header must be include to handle json objects; -- *systemd/sd-event.h*: this must be include to access the main loop; -- *systemd/sd-bus.h*: this may be include to use dbus connections. - -The *tictactoe* plugin does not use systemd features so it is not included. - -When including *afb/afb-plugin.h*, the macro **_GNU_SOURCE** must be -defined. - -Writing a synchronous verb implementation ------------------------------------------ - -The verb **tictactoe/board** is a synchronous implementation. -Here is its listing: - - /* - * get the board - */ - static void board(struct afb_req req) - { - struct board *board; - struct json_object *description; - - /* retrieves the context for the session */ - board = board_of_req(req); - INFO(afbitf, "method 'board' called for boardid %d", board->id); - - /* describe the board */ - description = describe(board); - - /* send the board's description */ - afb_req_success(req, description, NULL); - } - -This examples show many aspects of writing a synchronous -verb implementation. Let summarize it: - -1. The function **board_of_req** retrieves the context stored -for the plugin: the board. - -2. The macro **INFO** sends a message of kind *INFO* -to the logging system. The global variable named **afbitf** -used represents the interface to afb-daemon. - -3. The function **describe** creates a json_object representing -the board. - -4. The function **afb_req_success** sends the reply, attaching to -it the object *description*. - -### The incoming request - -For any implementation, the request is received by a structure of type -**struct afb_req**. - -> Note that this is a PLAIN structure, not a pointer to a structure. - -The definition of **struct afb_req** is: - - /* - * Describes the request by plugins from afb-daemon - */ - struct afb_req { - const struct afb_req_itf *itf; /* the interfacing functions */ - void *closure; /* the closure for functions */ - }; - -It contains two pointers: one, *itf*, points to the functions needed -to handle the internal request represented by the second pointer, *closure*. - -> The structure must never be used directly. -> Insted, use the intended functions provided -> by afb-daemon and described here. - -*req* is used to get arguments of the request, to send -answer, to store session data. - -This object and its interface is defined and documented -in the file names *afb/afb-req-itf.h* - -The above example uses 2 times the request object *req*. - -The first time, it is used for retrieving the board attached to -the session of the request. - -The second time, it is used to send the reply: an object that -describes the current board. - -### Associating a context to the session - -When the plugin *tic-tac-toe* receives a request, it musts regain -the board that describes the game associated to the session. - -For a plugin, having data associated to a session is a common case. -This data is called the context of the plugin for the session. -For the plugin *tic-tac-toe*, the context is the board. - -The requests *afb_req* offer four functions for -storing and retrieving the context associated to the session. - -These functions are: - -- **afb_req_context_get**: - retrieves the context data stored for the plugin. - -- **afb_req_context_set**: - store the context data of the plugin. - -- **afb_req_context**: - retrieves the context data of the plugin, - if needed, creates the context and store it. - -- **afb_req_context_clear**: - reset the stored data. - -The plugin *tictactoe* use a convenient function to retrieve -its context: the board. This function is *board_of_req*: - - /* - * retrieves the board of the request - */ - static inline struct board *board_of_req(struct afb_req req) - { - return afb_req_context(req, (void*)get_new_board, (void*)release_board); - } - -The function **afb_req_context** ensure an existing context -for the session of the request. -Its two last arguments are functions. Here, the casts are required -to avoid a warning when compiling. - -Here is the definition of the function **afb_req_context** - - /* - * Gets the pointer stored by the plugin for the session of 'req'. - * If the stored pointer is NULL, indicating that no pointer was - * already stored, afb_req_context creates a new context by calling - * the function 'create_context' and stores it with the freeing function - * 'free_context'. - */ - static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*)) - { - void *result = afb_req_context_get(req); - if (result == NULL) { - result = create_context(); - afb_req_context_set(req, result, free_context); - } - return result; - } - -The second argument if the function that creates the context. -For the plugin *tic-tac-toe* it is the function **get_new_board**. -The function **get_new_board** creates a new board and set its -count of use to 1. The boards are counting their count of use -to free there ressources when no more used. - -The third argument if the function that frees the context. -For the plugin *tic-tac-toe* it is the function **release_board**. -The function **release_board** decrease the the count of use of -the board given as argument. If the use count decrease to zero, -the board data are freed. - -The definition of the other functions for dealing with contexts are: - - /* - * Gets the pointer stored by the plugin for the session of 'req'. - * When the plugin has not yet recorded a pointer, NULL is returned. - */ - void *afb_req_context_get(struct afb_req req); - - /* - * Stores for the plugin the pointer 'context' to the session of 'req'. - * The function 'free_context' will be called when the session is closed - * or if plugin stores an other pointer. - */ - void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*)); - - /* - * Frees the pointer stored by the plugin for the session of 'req' - * and sets it to NULL. - * - * Shortcut for: afb_req_context_set(req, NULL, NULL) - */ - static inline void afb_req_context_clear(struct afb_req req) - { - afb_req_context_set(req, NULL, NULL); - } - -### Sending the reply to a request - -Two kinds of replies can be made: successful replies and -failure replies. - -> Sending a reply to a request must be done at most one time. - -The two functions to send a reply of kind "success" are -**afb_req_success** and **afb_req_success_f**. - - /* - * Sends a reply of kind success to the request 'req'. - * The status of the reply is automatically set to "success". - * Its send the object 'obj' (can be NULL) with an - * informationnal comment 'info (can also be NULL). - */ - 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, ...); - -The two functions to send a reply of kind "failure" are -**afb_req_fail** and **afb_req_fail_f**. - - /* - * Sends a reply of kind failure to the request 'req'. - * The status of the reply is set to 'status' and an - * informationnal comment 'info' (can also be NULL) can be added. - * - * Note that calling afb_req_fail("success", info) is equivalent - * to call afb_req_success(NULL, info). Thus even if possible it - * is strongly recommanded to NEVER use "success" for status. - */ - 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, ...); - -Getting argument of invocation ------------------------------- - -Many verbs expect arguments. Afb-daemon let plugins -retrieve their arguments by name not by position. - -Arguments are given by the requests either through HTTP -or through WebSockets. - -For example, the verb **join** of the plugin **tic-tac-toe** -expects one argument: the *boardid* to join. Here is an extract: - - /* - * Join a board - */ - static void join(struct afb_req req) - { - struct board *board, *new_board; - const char *id; - - /* retrieves the context for the session */ - board = board_of_req(req); - INFO(afbitf, "method 'join' called for boardid %d", board->id); - - /* retrieves the argument */ - id = afb_req_value(req, "boardid"); - if (id == NULL) - goto bad_request; - ... - -The function **afb_req_value** search in the request *req* -for an argument whose name is given. When no argument of the -given name was passed, **afb_req_value** returns NULL. - -> The search is case sensitive. So the name *boardid* is not the -> same name than *BoardId*. But this must not be assumed so two -> expected names of argument should not differ only by case. - -### Basic functions for querying arguments - -The function **afb_req_value** is defined as below: - - /* - * Gets from the request 'req' the string value of the argument of 'name'. - * Returns NULL if when there is no argument of 'name'. - * Returns the value of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).value - */ - static inline const char *afb_req_value(struct afb_req req, const char *name) - { - return afb_req_get(req, name).value; - } - -It is defined as a shortcut to call the function **afb_req_get**. -That function is defined as below: - - /* - * Gets from the request 'req' the argument of 'name'. - * Returns a PLAIN structure of type 'struct afb_arg'. - * When the argument of 'name' is not found, all fields of result are set to NULL. - * When the argument of 'name' is found, the fields are filled, - * in particular, the field 'result.name' is set to 'name'. - * - * There is a special name value: the empty string. - * The argument of name "" is defined only if the request was made using - * an HTTP POST of Content-Type "application/json". In that case, the - * argument of name "" receives the value of the body of the HTTP request. - */ - struct afb_arg afb_req_get(struct afb_req req, const char *name); - -That function takes 2 parameters: the request and the name -of the argument to retrieve. It returns a PLAIN structure of -type **struct afb_arg**. - -There is a special name that is defined when the request is -of type HTTP/POST with a Content-Type being application/json. -This name is **""** (the empty string). In that case, the value -of this argument of empty name is the string received as a body -of the post and is supposed to be a JSON string. - -The definition of **struct afb_arg** is: - - /* - * Describes an argument (or parameter) of a request - */ - struct afb_arg { - const char *name; /* name of the argument or NULL if invalid */ - const char *value; /* string representation of the value of the argument */ - /* original filename of the argument if path != NULL */ - const char *path; /* if not NULL, path of the received file for the argument */ - /* when the request is finalized this file is removed */ - }; - -The structure returns the data arguments that are known for the -request. This data include a field named **path**. This **path** -can be accessed using the function **afb_req_path** defined as -below: - - /* - * Gets from the request 'req' the path for file attached to the argument of 'name'. - * Returns NULL if when there is no argument of 'name' or when there is no file. - * Returns the path of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).path - */ - static inline const char *afb_req_path(struct afb_req req, const char *name) - { - return afb_req_get(req, name).path; - } - -The path is only defined for HTTP/POST requests that send file. - -### Arguments for received files - -As it is explained just above, clients can send files using -HTTP/POST requests. - -Received files are attached to a arguments. For example, the -following HTTP fragment (from test/sample-post.html) -will send an HTTP/POST request to the method -**post/upload-image** with 2 arguments named *file* and -*hidden*. - -

Sample Post File

-
- - -
- -
- -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 ----------------------------------- - -How to build a plugin ---------------------- - -Afb-daemon provides a *pkg-config* configuration file. - - -- cgit 1.2.3-korg