X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=doc%2Fwriting-afb-plugins.md;h=7611600f530c214fa5446caa35edf3faf1837f59;hb=ebb9bd69a97516763d5d9203245ded592b825a86;hp=ba2e676ac1ea76bb1592bac70c5f879015300269;hpb=9eb125dae5663f521464d35292c646d9e76d2076;p=src%2Fapp-framework-binder.git
diff --git a/doc/writing-afb-plugins.md b/doc/writing-afb-plugins.md
index ba2e676a..7611600f 100644
--- a/doc/writing-afb-plugins.md
+++ b/doc/writing-afb-plugins.md
@@ -28,6 +28,32 @@ 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
@@ -312,12 +338,27 @@ it the object *description*.
### The incoming request
-For any implementation, the request is received by a structure of type
+For any implementation, the request is received by a structure of type
**struct afb_req**.
-***Important: note that this is a PLAIN structure, not a pointer to a structure.***
+> Note that this is a PLAIN structure, not a pointer to a structure.
+
+The definition of **struct afb_req** is:
+
+ /*
+ * Describes the request by plugins from afb-daemon
+ */
+ struct afb_req {
+ const struct afb_req_itf *itf; /* the interfacing functions */
+ void *closure; /* the closure for functions */
+ };
+
+It contains two pointers: one, *itf*, points to the functions needed
+to handle the internal request represented by the second pointer, *closure*.
-This structure, here named *req*, is used
+> The structure must never be used directly.
+> Insted, use the intended functions provided
+> by afb-daemon and described here.
*req* is used to get arguments of the request, to send
answer, to store session data.
@@ -333,7 +374,7 @@ the session of the request.
The second time, it is used to send the reply: an object that
describes the current board.
-### Associating an object to the session for the plugin
+### Associating a context to the session
When the plugin *tic-tac-toe* receives a request, it musts regain
the board that describes the game associated to the session.
@@ -407,14 +448,41 @@ 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.
-### Sending the reply to a request
+The definition of the other functions for dealing with contexts are:
+
+ /*
+ * Gets the pointer stored by the plugin for the session of 'req'.
+ * When the plugin has not yet recorded a pointer, NULL is returned.
+ */
+ void *afb_req_context_get(struct afb_req req);
-Sending a reply to a request must be done at most one time.
+ /*
+ * Stores for the plugin the pointer 'context' to the session of 'req'.
+ * The function 'free_context' will be called when the session is closed
+ * or if plugin stores an other pointer.
+ */
+ void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
+
+ /*
+ * Frees the pointer stored by the plugin for the session of 'req'
+ * and sets it to NULL.
+ *
+ * Shortcut for: afb_req_context_set(req, NULL, NULL)
+ */
+ static inline void afb_req_context_clear(struct afb_req req)
+ {
+ afb_req_context_set(req, NULL, NULL);
+ }
+
+### Sending the reply to a request
Two kinds of replies can be made: successful replies and
failure replies.
-The functions to send replies are defined as below:
+> Sending a reply to a request must be done at most one time.
+
+The two functions to send a reply of kind "success" are
+**afb_req_success** and **afb_req_success_f**.
/*
* Sends a reply of kind success to the request 'req'.
@@ -422,26 +490,16 @@ The functions to send replies are defined as below:
* Its send the object 'obj' (can be NULL) with an
* informationnal comment 'info (can also be NULL).
*/
- static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info)
- {
- req.itf->success(req.closure, obj, info);
- }
+ void afb_req_success(struct afb_req req, struct json_object *obj, const char *info);
/*
* Same as 'afb_req_success' but the 'info' is a formatting
* string followed by arguments.
*/
- static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...)
- {
- char *message;
- va_list args;
- va_start(args, info);
- if (info == NULL || vasprintf(&message, info, args) < 0)
- message = NULL;
- va_end(args);
- afb_req_success(req, obj, message);
- free(message);
- }
+ void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...);
+
+The two functions to send a reply of kind "failure" are
+**afb_req_fail** and **afb_req_fail_f**.
/*
* Sends a reply of kind failure to the request 'req'.
@@ -452,31 +510,187 @@ The functions to send replies are defined as below:
* to call afb_req_success(NULL, info). Thus even if possible it
* is strongly recommanded to NEVER use "success" for status.
*/
- static inline void afb_req_fail(struct afb_req req, const char *status, const char *info)
- {
- req.itf->fail(req.closure, status, info);
- }
+ void afb_req_fail(struct afb_req req, const char *status, const char *info);
/*
* Same as 'afb_req_fail' but the 'info' is a formatting
* string followed by arguments.
*/
- static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...)
+ void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...);
+
+Getting argument of invocation
+------------------------------
+
+Many verbs expect arguments. Afb-daemon let plugins
+retrieve their arguments by name not by position.
+
+Arguments are given by the requests either through HTTP
+or through WebSockets.
+
+For example, the verb **join** of the plugin **tic-tac-toe**
+expects one argument: the *boardid* to join. Here is an extract:
+
+ /*
+ * Join a board
+ */
+ static void join(struct afb_req req)
{
- char *message;
- va_list args;
- va_start(args, info);
- if (info == NULL || vasprintf(&message, info, args) < 0)
- message = NULL;
- va_end(args);
- afb_req_fail(req, status, message);
- free(message);
+ struct board *board, *new_board;
+ const char *id;
+
+ /* retrieves the context for the session */
+ board = board_of_req(req);
+ INFO(afbitf, "method 'join' called for boardid %d", board->id);
+
+ /* retrieves the argument */
+ id = afb_req_value(req, "boardid");
+ if (id == NULL)
+ goto bad_request;
+ ...
+
+The function **afb_req_value** search in the request *req*
+for an argument whose name is given. When no argument of the
+given name was passed, **afb_req_value** returns NULL.
+
+> The search is case sensitive. So the name *boardid* is not the
+> same name than *BoardId*. But this must not be assumed so two
+> expected names of argument should not differ only by case.
+
+### Basic functions for querying arguments
+
+The function **afb_req_value** is defined as below:
+
+ /*
+ * Gets from the request 'req' the string value of the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name'.
+ * Returns the value of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).value
+ */
+ static inline const char *afb_req_value(struct afb_req req, const char *name)
+ {
+ return afb_req_get(req, name).value;
}
+It is defined as a shortcut to call the function **afb_req_get**.
+That function is defined as below:
+ /*
+ * Gets from the request 'req' the argument of 'name'.
+ * Returns a PLAIN structure of type 'struct afb_arg'.
+ * When the argument of 'name' is not found, all fields of result are set to NULL.
+ * When the argument of 'name' is found, the fields are filled,
+ * in particular, the field 'result.name' is set to 'name'.
+ *
+ * There is a special name value: the empty string.
+ * The argument of name "" is defined only if the request was made using
+ * an HTTP POST of Content-Type "application/json". In that case, the
+ * argument of name "" receives the value of the body of the HTTP request.
+ */
+ struct afb_arg afb_req_get(struct afb_req req, const char *name);
-Getting argument of invocation
-------------------------------
+That function takes 2 parameters: the request and the name
+of the argument to retrieve. It returns a PLAIN structure of
+type **struct afb_arg**.
+
+There is a special name that is defined when the request is
+of type HTTP/POST with a Content-Type being application/json.
+This name is **""** (the empty string). In that case, the value
+of this argument of empty name is the string received as a body
+of the post and is supposed to be a JSON string.
+
+The definition of **struct afb_arg** is:
+
+ /*
+ * Describes an argument (or parameter) of a request
+ */
+ struct afb_arg {
+ const char *name; /* name of the argument or NULL if invalid */
+ const char *value; /* string representation of the value of the argument */
+ /* original filename of the argument if path != NULL */
+ const char *path; /* if not NULL, path of the received file for the argument */
+ /* when the request is finalized this file is removed */
+ };
+
+The structure returns the data arguments that are known for the
+request. This data include a field named **path**. This **path**
+can be accessed using the function **afb_req_path** defined as
+below:
+
+ /*
+ * Gets from the request 'req' the path for file attached to the argument of 'name'.
+ * Returns NULL if when there is no argument of 'name' or when there is no file.
+ * Returns the path of the argument of 'name' otherwise.
+ *
+ * Shortcut for: afb_req_get(req, name).path
+ */
+ static inline const char *afb_req_path(struct afb_req req, const char *name)
+ {
+ return afb_req_get(req, name).path;
+ }
+
+The path is only defined for HTTP/POST requests that send file.
+
+### Arguments for received files
+
+As it is explained just above, clients can send files using
+HTTP/POST requests.
+
+Received files are attached to a arguments. For example, the
+following HTTP fragment (from test/sample-post.html)
+will send an HTTP/POST request to the method
+**post/upload-image** with 2 arguments named *file* and
+*hidden*.
+
+ 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
----------------------------------