diff options
Diffstat (limited to 'doc/writing-afb-plugins.md')
| -rw-r--r-- | doc/writing-afb-plugins.md | 288 |
1 files changed, 251 insertions, 37 deletions
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*. + + <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 ---------------------------------- |