+<p>The third argument if the function that frees the context.
+For the plugin <em>tic-tac-toe</em> it is the function <strong>release_board</strong>.
+The function <strong>release_board</strong> decrease the the count of use of
+the board given as argument. If the use count decrease to zero,
+the board data are freed.</p>
+
+<p>The definition of the other functions for dealing with contexts are:</p>
+
+<pre><code>/*
+ * 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);
+}
+</code></pre>
+
+<h3 id="Sending.the.reply.to.a.request">Sending the reply to a request</h3>
+
+<p>Two kinds of replies can be made: successful replies and
+failure replies.</p>
+
+<blockquote><p>Sending a reply to a request must be done at most one time.</p></blockquote>
+
+<p>The two functions to send a reply of kind “success” are
+<strong>afb_req_success</strong> and <strong>afb_req_success_f</strong>.</p>
+
+<pre><code>/*
+ * 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, ...);
+</code></pre>
+
+<p>The two functions to send a reply of kind “failure” are
+<strong>afb_req_fail</strong> and <strong>afb_req_fail_f</strong>.</p>
+
+<pre><code>/*
+ * 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, ...);
+</code></pre>
+
+<h2 id="Getting.argument.of.invocation">Getting argument of invocation</h2>
+
+<p>Many verbs expect arguments. Afb-daemon let plugins
+retrieve their arguments by name not by position.</p>
+
+<p>Arguments are given by the requests either through HTTP
+or through WebSockets.</p>
+
+<p>For example, the verb <strong>join</strong> of the plugin <strong>tic-tac-toe</strong>
+expects one argument: the <em>boardid</em> to join. Here is an extract:</p>
+
+<pre><code>/*
+ * 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;
+ ...
+</code></pre>
+
+<p>The function <strong>afb_req_value</strong> search in the request <em>req</em>
+for an argument whose name is given. When no argument of the
+given name was passed, <strong>afb_req_value</strong> returns NULL.</p>
+
+<blockquote><p>The search is case sensitive. So the name <em>boardid</em> is not the
+same name than <em>BoardId</em>. But this must not be assumed so two
+expected names of argument should not differ only by case.</p></blockquote>
+
+<h3 id="Basic.functions.for.querying.arguments">Basic functions for querying arguments</h3>
+
+<p>The function <strong>afb_req_value</strong> is defined as below:</p>
+
+<pre><code>/*
+ * 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;
+}
+</code></pre>
+
+<p>It is defined as a shortcut to call the function <strong>afb_req_get</strong>.
+That function is defined as below:</p>
+
+<pre><code>/*
+ * 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);
+</code></pre>
+
+<p>That function takes 2 parameters: the request and the name
+of the argument to retrieve. It returns a PLAIN structure of
+type <strong>struct afb_arg</strong>.</p>
+
+<p>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 <strong>“”</strong> (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.</p>
+
+<p>The definition of <strong>struct afb_arg</strong> is:</p>
+
+<pre><code>/*
+ * 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 */
+};
+</code></pre>
+
+<p>The structure returns the data arguments that are known for the
+request. This data include a field named <strong>path</strong>. This <strong>path</strong>
+can be accessed using the function <strong>afb_req_path</strong> defined as
+below:</p>
+
+<pre><code>/*
+ * 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;
+}
+</code></pre>
+
+<p>The path is only defined for HTTP/POST requests that send file.</p>
+
+<h3 id="Arguments.for.received.files">Arguments for received files</h3>
+
+<p>As it is explained just above, clients can send files using
+HTTP/POST requests.</p>
+
+<p>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
+<strong>post/upload-image</strong> with 2 arguments named <em>file</em> and
+<em>hidden</em>.</p>
+
+<pre><code><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>
+</code></pre>
+
+<p>In that case, the argument named <strong>file</strong> has its value and its
+path defined and not NULL.</p>
+
+<p>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.</p>
+
+<p>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.</p>
+
+<p>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.</p>
+
+<h3 id="Arguments.as.a.JSON.object">Arguments as a JSON object</h3>
+
+<p>Plugins can get all the arguments as one single object.
+This feature is provided by the function <strong>afb_req_json</strong>
+that is defined as below:</p>
+
+<pre><code>/*
+ * 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);
+</code></pre>
+
+<p>It returns a json object. This object depends on how the request was
+made:</p>
+
+<ul>
+<li><p>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”: “…” }</p></li>
+<li><p>For WebSockets requests, the returned object is the object
+given by the client transparently transported.</p></li>
+</ul>
+
Code Review / src / app-framework-binder.git / commitdiff