include/afb/afb-req-itf.h

   1 /*
   2  * Copyright (C) 2016 "IoT.bzh"
   3  * Author: José Bollo <jose.bollo@iot.bzh>
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *   http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #pragma once
  19
  20 #if !defined(_GNU_SOURCE)
  21 # error "_GNU_SOURCE must be defined for using vasprintf"
  22 #endif
  23
  24 #include <stdlib.h>
  25 #include <stdarg.h>
  26 #include <stdio.h>
  27
  28 /* avoid inclusion of <json-c/json.h> */
  29 struct json_object;
  30
  31 /*
  32  * Describes an argument (or parameter) of a request
  33  */
  34 struct afb_arg {
  35         const char *name;       /* name of the argument or NULL if invalid */
  36         const char *value;      /* string representation of the value of the argument */
  37                                 /* original filename of the argument if path != NULL */
  38         const char *path;       /* if not NULL, path of the received file for the argument */
  39                                 /* when the request is finalized this file is removed */
  40 };
  41
  42 /*
  43  * Interface for handling requests.
  44  * It records the functions to be called for the request.
  45  * Don't use this structure directly.
  46  * Use the helper functions documented below.
  47  */
  48 struct afb_req_itf {
  49         /* CAUTION: respect the order, add at the end */
  50
  51         struct json_object *(*json)(void *closure);
  52         struct afb_arg (*get)(void *closure, const char *name);
  53
  54         void (*success)(void *closure, struct json_object *obj, const char *info);
  55         void (*fail)(void *closure, const char *status, const char *info);
  56
  57         const char *(*raw)(void *closure, size_t *size);
  58         void (*send)(void *closure, const char *buffer, size_t size);
  59
  60         void *(*context_get)(void *closure);
  61         void (*context_set)(void *closure, void *value, void (*free_value)(void*));
  62
  63         void (*addref)(void *closure);
  64         void (*unref)(void *closure);
  65
  66         void (*session_close)(void *closure);
  67         int (*session_set_LOA)(void *closure, unsigned level);
  68 };
  69
  70 /*
  71  * Describes the request by plugins from afb-daemon
  72  */
  73 struct afb_req {
  74         const struct afb_req_itf *itf;  /* the interface to use */
  75         void *closure;                  /* the closure argument for functions of 'itf' */
  76 };
  77
  78 /*
  79  * Gets from the request 'req' the argument of 'name'.
  80  * Returns a PLAIN structure of type 'struct afb_arg'.
  81  * When the argument of 'name' is not found, all fields of result are set to NULL.
  82  * When the argument of 'name' is found, the fields are filled,
  83  * in particular, the field 'result.name' is set to 'name'.
  84  *
  85  * There is a special name value: the empty string.
  86  * The argument of name "" is defined only if the request was made using
  87  * an HTTP POST of Content-Type "application/json". In that case, the
  88  * argument of name "" receives the value of the body of the HTTP request.
  89  */
  90 static inline struct afb_arg afb_req_get(struct afb_req req, const char *name)
  91 {
  92         return req.itf->get(req.closure, name);
  93 }
  94
  95 /*
  96  * Gets from the request 'req' the string value of the argument of 'name'.
  97  * Returns NULL if when there is no argument of 'name'.
  98  * Returns the value of the argument of 'name' otherwise.
  99  *
 100  * Shortcut for: afb_req_get(req, name).value
 101  */
 102 static inline const char *afb_req_value(struct afb_req req, const char *name)
 103 {
 104         return afb_req_get(req, name).value;
 105 }
 106
 107 /*
 108  * Gets from the request 'req' the path for file attached to the argument of 'name'.
 109  * Returns NULL if when there is no argument of 'name' or when there is no file.
 110  * Returns the path of the argument of 'name' otherwise.
 111  *
 112  * Shortcut for: afb_req_get(req, name).path
 113  */
 114 static inline const char *afb_req_path(struct afb_req req, const char *name)
 115 {
 116         return afb_req_get(req, name).path;
 117 }
 118
 119 /*
 120  * Gets from the request 'req' the json object hashing the arguments.
 121  * The returned object must not be released using 'json_object_put'.
 122  */
 123 static inline struct json_object *afb_req_json(struct afb_req req)
 124 {
 125         return req.itf->json(req.closure);
 126 }
 127
 128 /*
 129  * Sends a reply of kind success to the request 'req'.
 130  * The status of the reply is automatically set to "success".
 131  * Its send the object 'obj' (can be NULL) with an
 132  * informationnal comment 'info (can also be NULL).
 133  *
 134  * For conveniency, the function calls 'json_object_put' for 'obj'.
 135  * Thus, in the case where 'obj' should remain available after
 136  * the function returns, the function 'json_object_get' shall be used.
 137  */
 138 static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info)
 139 {
 140         req.itf->success(req.closure, obj, info);
 141 }
 142
 143 /*
 144  * Same as 'afb_req_success' but the 'info' is a formatting
 145  * string followed by arguments.
 146  *
 147  * For conveniency, the function calls 'json_object_put' for 'obj'.
 148  * Thus, in the case where 'obj' should remain available after
 149  * the function returns, the function 'json_object_get' shall be used.
 150  */
 151 static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...)
 152 {
 153         char *message;
 154         va_list args;
 155         va_start(args, info);
 156         if (info == NULL || vasprintf(&message, info, args) < 0)
 157                 message = NULL;
 158         va_end(args);
 159         afb_req_success(req, obj, message);
 160         free(message);
 161 }
 162
 163 /*
 164  * Sends a reply of kind failure to the request 'req'.
 165  * The status of the reply is set to 'status' and an
 166  * informationnal comment 'info' (can also be NULL) can be added.
 167  *
 168  * Note that calling afb_req_fail("success", info) is equivalent
 169  * to call afb_req_success(NULL, info). Thus even if possible it
 170  * is strongly recommanded to NEVER use "success" for status.
 171  *
 172  * For conveniency, the function calls 'json_object_put' for 'obj'.
 173  * Thus, in the case where 'obj' should remain available after
 174  * the function returns, the function 'json_object_get' shall be used.
 175  */
 176 static inline void afb_req_fail(struct afb_req req, const char *status, const char *info)
 177 {
 178         req.itf->fail(req.closure, status, info);
 179 }
 180
 181 /*
 182  * Same as 'afb_req_fail' but the 'info' is a formatting
 183  * string followed by arguments.
 184  *
 185  * For conveniency, the function calls 'json_object_put' for 'obj'.
 186  * Thus, in the case where 'obj' should remain available after
 187  * the function returns, the function 'json_object_get' shall be used.
 188  */
 189 static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...)
 190 {
 191         char *message;
 192         va_list args;
 193         va_start(args, info);
 194         if (info == NULL || vasprintf(&message, info, args) < 0)
 195                 message = NULL;
 196         va_end(args);
 197         afb_req_fail(req, status, message);
 198         free(message);
 199 }
 200
 201 /*
 202  * Gets the pointer stored by the plugin for the session of 'req'.
 203  * When the plugin has not yet recorded a pointer, NULL is returned.
 204  */
 205 static inline void *afb_req_context_get(struct afb_req req)
 206 {
 207         return req.itf->context_get(req.closure);
 208 }
 209
 210 /*
 211  * Stores for the plugin the pointer 'context' to the session of 'req'.
 212  * The function 'free_context' will be called when the session is closed
 213  * or if plugin stores an other pointer.
 214  */
 215 static inline void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*))
 216 {
 217         req.itf->context_set(req.closure, context, free_context);
 218 }
 219
 220 /*
 221  * Gets the pointer stored by the plugin for the session of 'req'.
 222  * If the stored pointer is NULL, indicating that no pointer was
 223  * already stored, afb_req_context creates a new context by calling
 224  * the function 'create_context' and stores it with the freeing function
 225  * 'free_context'.
 226  */
 227 static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
 228 {
 229         void *result = afb_req_context_get(req);
 230         if (result == NULL) {
 231                 result = create_context();
 232                 afb_req_context_set(req, result, free_context);
 233         }
 234         return result;
 235 }
 236
 237 /*
 238  * Frees the pointer stored by the plugin for the session of 'req'
 239  * and sets it to NULL.
 240  *
 241  * Shortcut for: afb_req_context_set(req, NULL, NULL)
 242  */
 243 static inline void afb_req_context_clear(struct afb_req req)
 244 {
 245         afb_req_context_set(req, NULL, NULL);
 246 }
 247
 248 /*
 249  * Adds one to the count of references of 'req'.
 250  * This function MUST be called by asynchronous implementations
 251  * of verbs if no reply was sent before returning.
 252  */
 253 static inline void afb_req_addref(struct afb_req req)
 254 {
 255         req.itf->addref(req.closure);
 256 }
 257
 258 /*
 259  * Substracts one to the count of references of 'req'.
 260  * This function MUST be called by asynchronous implementations
 261  * of verbs after sending the asynchronous reply.
 262  */
 263 static inline void afb_req_unref(struct afb_req req)
 264 {
 265         req.itf->unref(req.closure);
 266 }
 267
 268 /*
 269  * Closes the session associated with 'req'
 270  * and delete all associated contexts.
 271  */
 272 static inline void afb_req_session_close(struct afb_req req)
 273 {
 274         req.itf->session_close(req.closure);
 275 }
 276
 277 /*
 278  * Sets the level of assurance of the session of 'req'
 279  * to 'level'. The effect of this function is subject of
 280  * security policies.
 281  * Returns 1 on success or 0 if failed.
 282  */
 283 static inline int afb_req_session_set_LOA(struct afb_req req, unsigned level)
 284 {
 285         return req.itf->session_set_LOA(req.closure, level);
 286 }
 287
 288 /*
 289  * Stores 'req' on heap for asynchrnous use.
 290  * Returns a pointer to the stored 'req' or NULL on memory depletion.
 291  * The count of reference to 'req' is incremented on success
 292  * (see afb_req_addref).
 293  */
 294 static inline struct afb_req *afb_req_store(struct afb_req req)
 295 {
 296         struct afb_req *result = malloc(sizeof *result);
 297         if (result != NULL) {
 298                 *result = req;
 299                 afb_req_addref(req);
 300         }
 301         return result;
 302 }
 303
 304 /*
 305  * Retrieves the afb_req stored at 'req' and frees the memory.
 306  * Returns the stored request.
 307  * The count of reference is UNCHANGED, thus, normally, the
 308  * function 'afb_req_unref' should be called on the result
 309  * after that the asynchronous reply if sent.
 310  */
 311 static inline struct afb_req afb_req_unstore(struct afb_req *req)
 312 {
 313         struct afb_req result = *req;
 314         free(req);
 315         return result;
 316 }
 317
 318 /* internal use */
 319 static inline const char *afb_req_raw(struct afb_req req, size_t *size)
 320 {
 321         return req.itf->raw(req.closure, size);
 322 }
 323
 324 /* internal use */
 325 static inline void afb_req_send(struct afb_req req, const char *buffer, size_t size)
 326 {
 327         req.itf->send(req.closure, buffer, size);
 328 }
 329