From: José Bollo Date: Fri, 27 May 2016 15:31:30 +0000 (+0200) Subject: improves documentation X-Git-Tag: blowfish_2.0.1~66^2~3 X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=commitdiff_plain;h=b81bab801d1a39cce7254b0c056d991412ec4331;p=src%2Fapp-framework-binder.git improves documentation Change-Id: I5abae06cd5b5127fca97ba12aa8f18d037a95d79 Signed-off-by: José Bollo --- 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/writing-afb-plugins.html b/doc/afb-plugin-writing.html similarity index 55% rename from doc/writing-afb-plugins.html rename to doc/afb-plugin-writing.html index 712d30ee..9a98ffe9 100644 --- a/doc/writing-afb-plugins.html +++ b/doc/afb-plugin-writing.html @@ -4,10 +4,11 @@ -

HOWTO WRITE a PLUGIN for AFB-DAEMON

+ +

HOWTO WRITE a PLUGIN for AFB-DAEMON

version: 1
-Date:    25 May 2016
+Date:    27 mai 2016
 Author:  José Bollo
@@ -60,13 +61,29 @@ Author: José Bollo
  • Arguments as a JSON object
    • -
  • Sending messages to the log system
    • -
  • How to build a plugin
    • +
  • Initialisation of the plugin and declaration of verbs
    • +
  • Sending messages to the log system + +
    • +
  • Sending events
    • +
  • Writing an asynchronous verb implementation
    • +
  • How to build a plugin + +

    • -

    Summary

    + +

    Summary

    The binder afb-daemon serves files through the HTTP protocol and offers access to API’s through @@ -80,7 +97,8 @@ by developpers.

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

    -

    Nature of a plugin

    + +

    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 @@ -88,12 +106,14 @@ starts.

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

    -

    Kinds of plugins

    + +

    Kinds of plugins

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

    -

    Application plugins

    + +

    Application plugins

    Application plugins are intended to be instanciated for each application: when an application using that plugin is started, @@ -102,7 +122,8 @@ 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

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

    @@ -114,7 +135,8 @@ per client.

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

    -

    Live cycle of a plugin within afb-daemon

    + +

    Live cycle of a plugin within afb-daemon

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

    @@ -132,7 +154,8 @@ 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

    + +

    Content of a plugin

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

    @@ -158,7 +181,8 @@ 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

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

    @@ -173,7 +197,8 @@ 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

    + +

    Names of verbs

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

    @@ -186,7 +211,8 @@ 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

    The initialisation function serves several purposes.

    @@ -202,7 +228,8 @@ requirements and implmentations of the verbs that it exposes.

    -

    Functions implementing verbs

    + +

    Functions implementing verbs

    When a method is called, afb-daemon constructs a request object and pass it to the implementation function for verb @@ -228,7 +255,8 @@ returning are named asynchronous implementations.

    asynchronous action and record to send the reply on completion of this action.

    -

    The Tic-Tac-Toe example

    + +

    The Tic-Tac-Toe example

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

    This plugin is named tictactoe.

    -

    Choosing names

    + +

    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 @@ -249,7 +278,8 @@ the names easy to use across plaforms.

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

    -

    Names for API (plugin)

    + +

    Names for API (plugin)

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

    @@ -268,7 +298,8 @@ All characters are authorised except:

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

    -

    Names for verbs

    + +

    Names for verbs

    The names of the verbs are not checked.

    @@ -279,7 +310,8 @@ is forbidden.

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

    -

    Names for arguments

    + +

    Names for arguments

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

    @@ -288,7 +320,8 @@ anything.

    string comparison. Thus the names “index” and “Index” are not the same.

    -

    Forging names widely available

    + +

    Forging names widely available

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

    @@ -311,7 +344,8 @@ valid javascript identifier.

    rely on the case sensitivity and to avoid the use of names different only by the case.

    -

    Options to set when compiling plugins

    + +

    Options to set when compiling plugins

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

    @@ -336,7 +370,8 @@ This is done through the Requires keyword of pkg-config.

    If this behaviour is a problem, let us know.

    -

    Header files to include

    + +

    Header files to include

    The plugin tictactoe has the following lines for its includes:

    @@ -363,7 +398,8 @@ if it needs it:

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

    -

    Writing a synchronous verb implementation

    + +

    Writing a synchronous verb implementation

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

    @@ -404,7 +440,8 @@ it the object description.

    -

    The incoming request

    + +

    The incoming request

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

    @@ -443,7 +480,8 @@ 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

    + +

    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.

    @@ -546,7 +584,8 @@ static inline void afb_req_context_clear(struct afb_req req) } -

    Sending the reply to a request

    + +

    Sending the reply to a request

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

    @@ -592,7 +631,8 @@ void afb_req_fail(struct afb_req req, const char *status, const char *info); void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...); -

    Getting argument of invocation

    + +

    Getting argument of invocation

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

    @@ -630,7 +670,8 @@ given name was passed, afb_req_value returns NULL.

    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

    + +

    Basic functions for querying arguments

    The function afb_req_value is defined as below:

    @@ -709,7 +750,8 @@ static inline const char *afb_req_path(struct afb_req req, const char *name)

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

    -

    Arguments for received files

    + +

    Arguments for received files

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

    @@ -745,7 +787,8 @@ 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

    + +

    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 @@ -772,12 +815,535 @@ 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))

    +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)
+
    -

    Sending messages to the log system

    +

    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:

    -

    How to build a plugin

    +
      +

    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})
+
    -

    Afb-daemon provides a pkg-config configuration file.

    +

    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/writing-afb-plugins.md b/doc/afb-plugin-writing.md similarity index 61% rename from doc/writing-afb-plugins.md rename to doc/afb-plugin-writing.md index 7611600f..734b15a5 100644 --- a/doc/writing-afb-plugins.md +++ b/doc/afb-plugin-writing.md @@ -1,7 +1,7 @@ HOWTO WRITE a PLUGIN for AFB-DAEMON =================================== version: 1 - Date: 25 May 2016 + Date: 27 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE @@ -690,14 +690,345 @@ 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))* +> ***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. +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; }