version: 1
-Date: 24 mai 2016
+Date: 25 May 2016
Author: José Bollo
The binder afb-daemon serves files through the HTTP protocol and offers access to API’s through @@ -69,8 +80,7 @@ by developpers.
Before going into details, through a tiny example, a short overview plugins basis is needed.
- -A plugin is a separate piece of code made of a shared library. The plugin is loaded and activated by afb-daemon when afb-daemon @@ -78,8 +88,33 @@ starts.
Technically, a plugin is not linked to any library of afb-daemon.
- -There is two kinds of plugins: application plugins and service +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 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.
+ +The plugins are loaded and activated when afb-daemon starts.
@@ -97,8 +132,7 @@ Consequently, developpers of plugins should use ‘atexit’ or ‘on_exit’ during initialisation if they need to perform specific actions when stopping. - -For afb-daemon, a plugin contains 2 different things: names and functions.
@@ -124,8 +158,7 @@ and upper case when searching for a method. Thus, The names TicTacToe/Board and tictactoe/borad are equals. - -The name of the plugin is also known as the name of the API that defines the plugin.
@@ -140,8 +173,7 @@ 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. - -Each plugin exposes a set of verbs that can be called by client of afb-daemon.
@@ -154,8 +186,7 @@ when clients emit requests for that verb.For example, when a client of afb-daemon calls a method named foo/bar.
- -The initialisation function serves several purposes.
@@ -171,8 +202,7 @@ requirements and implmentations of the verbs that it exposes.When a method is called, afb-daemon constructs a request object and pass it to the implementation function for verb @@ -198,8 +228,7 @@ returning are named asynchronous implementations.
asynchronous action and record to send the reply on completion of this action. - -This part explains how to write an afb-plugin. For the sake of being practical we will use many @@ -208,8 +237,7 @@ This plugin example is in plugins/samples/tic-tac-toe.c.
This plugin is named tictactoe.
- -The designer of a plugin must defines names for its plugin (or its API) and for the verbs of its API. He also @@ -221,8 +249,7 @@ the names easy to use across plaforms.
The names and strings used ALL are UTF-8 encoded.
- -The names of the API are checked. All characters are authorised except:
@@ -241,8 +268,7 @@ All characters are authorised except:Afb-daemon make no distinction between lower case and upper case when searching for an API by its name.
- -The names of the verbs are not checked.
@@ -253,8 +279,7 @@ is forbidden.Afb-daemon make no distinction between lower case and upper case when searching for an API by its name.
- -The names for arguments are not restricted and can be anything.
@@ -263,8 +288,7 @@ anything. string comparison. Thus the names “index” and “Index” are not the same. - -The key names of javascript object can be almost anything using the arrayed notation:
@@ -287,8 +311,7 @@ valid javascript identifier. rely on the case sensitivity and to avoid the use of names different only by the case. - -Afb-daemon provides a configuration file for pkg-config. Typing the command
@@ -313,8 +336,7 @@ This is done through the Requires keyword of pkg-config.If this behaviour is a problem, let us know.
- -The plugin tictactoe has the following lines for its includes:
@@ -341,8 +363,7 @@ if it needs it:When including afb/afb-plugin.h, the macro _GNU_SOURCE must be defined.
- -The verb tictactoe/board is a synchronous implementation. Here is its listing:
@@ -352,33 +373,61 @@ Here is its listing: */ static void board(struct afb_req req) { - struct board *board; - struct json_object *description; + struct board *board; + struct json_object *description; - /* retrieves the context for the session */ - board = board_of_req(req); - INFO(afbitf, "method 'board' called for boardid %d", board->id); + /* retrieves the context for the session */ + board = board_of_req(req); + INFO(afbitf, "method 'board' called for boardid %d", board->id); - /* describe the board */ - description = describe(board); + /* describe the board */ + description = describe(board); - /* send the board's description */ - afb_req_success(req, description, NULL); + /* send the board's description */ + afb_req_success(req, description, NULL); }This examples show many aspects of writing a synchronous -verb implementation.
+verb implementation. Let summarize it: - -The function board_of_req retrieves the context stored +for the plugin: the board.
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.
The function describe creates a json_object representing +the board.
The function afb_req_success sends the reply, attaching to +it the object description.
For any implementation, the request is received by a structure of type +
For any implementation, the request is received by a structure of type struct afb_req.
-Important: note that this is a PLAIN structure, not a pointer to a structure.
++ +Note that this is a PLAIN structure, not a pointer to a structure.
The definition of struct afb_req is:
+ +/*
+ * Describes the request by plugins from afb-daemon
+ */
+struct afb_req {
+ const struct afb_req_itf *itf; /* the interfacing functions */
+ void *closure; /* the closure for functions */
+};
+It contains two pointers: one, itf, points to the functions needed +to handle the internal request represented by the second pointer, closure.
-This structure, here named req, is used
+The structure must never be used directly. +Insted, use the intended functions provided +by afb-daemon and described here.
req is used to get arguments of the request, to send answer, to store session data.
@@ -394,8 +443,7 @@ the session of the request.The second time, it is used to send the reply: an object that describes the current board.
- -When the plugin tic-tac-toe receives a request, it musts regain the board that describes the game associated to the session.
@@ -430,14 +478,14 @@ its context: the board. This function is board_of_req: */ static inline struct board *board_of_req(struct afb_req req) { - return afb_req_context(req, (void*)get_new_board, (void*)release_board); + return afb_req_context(req, (void*)get_new_board, (void*)release_board); } -This function is very simple because it merely wraps -a call to the function afb_req_context, providing -all needed arguments. -The casts are required to avoid a warning when compiling.
+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
@@ -450,33 +498,286 @@ The casts are required to avoid a warning when compiling. */ static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*)) { - void *result = afb_req_context_get(req); - if (result == NULL) { - result = create_context(); - afb_req_context_set(req, result, free_context); - } - return result; + void *result = afb_req_context_get(req); + if (result == NULL) { + result = create_context(); + afb_req_context_set(req, result, free_context); + } + return result; } -This powerful function ensures that the context exists and is -stored for the session.
- -The function get_new_board creates a new board and set its +
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 function release_board
+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);
+}
+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, ...);
+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.
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.
+ +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.
+ +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))
Afb-daemon provides a The packaging of afb-daemon
+Afb-daemon provides a pkg-config configuration file.