include/afb/afb-req.h

   1 /*
   2  * Copyright (C) 2016, 2017 "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 #include "afb-request-itf.h"
  21
  22 #include "afb-event.h"
  23
  24 /*
  25  * Describes the request by bindings from afb-daemon
  26  */
  27 struct afb_req
  28 {
  29         const struct afb_request_itf *itf;      /* the interface to use */
  30         struct afb_request *closure;            /* the closure argument for functions of 'itf' */
  31 };
  32
  33 /*
  34  * Checks whether the request 'req' is valid or not.
  35  *
  36  * Returns 0 if not valid or 1 if valid.
  37  */
  38 static inline int afb_req_is_valid(struct afb_req req)
  39 {
  40         return !!req.itf;
  41 }
  42
  43 /*
  44  * Gets from the request 'req' the argument of 'name'.
  45  * Returns a PLAIN structure of type 'struct afb_arg'.
  46  * When the argument of 'name' is not found, all fields of result are set to NULL.
  47  * When the argument of 'name' is found, the fields are filled,
  48  * in particular, the field 'result.name' is set to 'name'.
  49  *
  50  * There is a special name value: the empty string.
  51  * The argument of name "" is defined only if the request was made using
  52  * an HTTP POST of Content-Type "application/json". In that case, the
  53  * argument of name "" receives the value of the body of the HTTP request.
  54  */
  55 static inline struct afb_arg afb_req_get(struct afb_req req, const char *name)
  56 {
  57         return req.itf->get(req.closure, name);
  58 }
  59
  60 /*
  61  * Gets from the request 'req' the string value of the argument of 'name'.
  62  * Returns NULL if when there is no argument of 'name'.
  63  * Returns the value of the argument of 'name' otherwise.
  64  *
  65  * Shortcut for: afb_req_get(req, name).value
  66  */
  67 static inline const char *afb_req_value(struct afb_req req, const char *name)
  68 {
  69         return afb_req_get(req, name).value;
  70 }
  71
  72 /*
  73  * Gets from the request 'req' the path for file attached to the argument of 'name'.
  74  * Returns NULL if when there is no argument of 'name' or when there is no file.
  75  * Returns the path of the argument of 'name' otherwise.
  76  *
  77  * Shortcut for: afb_req_get(req, name).path
  78  */
  79 static inline const char *afb_req_path(struct afb_req req, const char *name)
  80 {
  81         return afb_req_get(req, name).path;
  82 }
  83
  84 /*
  85  * Gets from the request 'req' the json object hashing the arguments.
  86  * The returned object must not be released using 'json_object_put'.
  87  */
  88 static inline struct json_object *afb_req_json(struct afb_req req)
  89 {
  90         return req.itf->json(req.closure);
  91 }
  92
  93 /*
  94  * Sends a reply of kind success to the request 'req'.
  95  * The status of the reply is automatically set to "success".
  96  * Its send the object 'obj' (can be NULL) with an
  97  * informationnal comment 'info (can also be NULL).
  98  *
  99  * For convenience, the function calls 'json_object_put' for 'obj'.
 100  * Thus, in the case where 'obj' should remain available after
 101  * the function returns, the function 'json_object_get' shall be used.
 102  */
 103 static inline void afb_req_success(struct afb_req req, struct json_object *obj, const char *info)
 104 {
 105         req.itf->success(req.closure, obj, info);
 106 }
 107
 108 /*
 109  * Same as 'afb_req_success' but the 'info' is a formatting
 110  * string followed by arguments.
 111  *
 112  * For convenience, the function calls 'json_object_put' for 'obj'.
 113  * Thus, in the case where 'obj' should remain available after
 114  * the function returns, the function 'json_object_get' shall be used.
 115  */
 116 static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...) __attribute__((format(printf, 3, 4)));
 117 static inline void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...)
 118 {
 119         va_list args;
 120         va_start(args, info);
 121         req.itf->vsuccess(req.closure, obj, info, args);
 122         va_end(args);
 123 }
 124
 125 /*
 126  * Same as 'afb_req_success_f' but the arguments to the format 'info'
 127  * are given as a variable argument list instance.
 128  *
 129  * For convenience, the function calls 'json_object_put' for 'obj'.
 130  * Thus, in the case where 'obj' should remain available after
 131  * the function returns, the function 'json_object_get' shall be used.
 132  */
 133 static inline void afb_req_success_v(struct afb_req req, struct json_object *obj, const char *info, va_list args)
 134 {
 135         req.itf->vsuccess(req.closure, obj, info, args);
 136 }
 137
 138 /*
 139  * Sends a reply of kind failure to the request 'req'.
 140  * The status of the reply is set to 'status' and an
 141  * informationnal comment 'info' (can also be NULL) can be added.
 142  *
 143  * Note that calling afb_req_fail("success", info) is equivalent
 144  * to call afb_req_success(NULL, info). Thus even if possible it
 145  * is strongly recommanded to NEVER use "success" for status.
 146  */
 147 static inline void afb_req_fail(struct afb_req req, const char *status, const char *info)
 148 {
 149         req.itf->fail(req.closure, status, info);
 150 }
 151
 152 /*
 153  * Same as 'afb_req_fail' but the 'info' is a formatting
 154  * string followed by arguments.
 155  */
 156 static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...) __attribute__((format(printf, 3, 4)));
 157 static inline void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...)
 158 {
 159         va_list args;
 160         va_start(args, info);
 161         req.itf->vfail(req.closure, status, info, args);
 162         va_end(args);
 163 }
 164
 165 /*
 166  * Same as 'afb_req_fail_f' but the arguments to the format 'info'
 167  * are given as a variable argument list instance.
 168  */
 169 static inline void afb_req_fail_v(struct afb_req req, const char *status, const char *info, va_list args)
 170 {
 171         req.itf->vfail(req.closure, status, info, args);
 172 }
 173
 174 /*
 175  * Gets the pointer stored by the binding for the session of 'req'.
 176  * When the binding has not yet recorded a pointer, NULL is returned.
 177  */
 178 static inline void *afb_req_context_get(struct afb_req req)
 179 {
 180         return req.itf->context_get(req.closure);
 181 }
 182
 183 /*
 184  * Stores for the binding the pointer 'context' to the session of 'req'.
 185  * The function 'free_context' will be called when the session is closed
 186  * or if binding stores an other pointer.
 187  */
 188 static inline void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*))
 189 {
 190         req.itf->context_set(req.closure, context, free_context);
 191 }
 192
 193 /*
 194  * Gets the pointer stored by the binding for the session of 'req'.
 195  * If the stored pointer is NULL, indicating that no pointer was
 196  * already stored, afb_req_context creates a new context by calling
 197  * the function 'create_context' and stores it with the freeing function
 198  * 'free_context'.
 199  */
 200 static inline void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*))
 201 {
 202         return req.itf->context_make(req.closure, 0, (void *(*)(void*))(void*)create_context, free_context, 0);
 203 }
 204
 205 /*
 206  * Gets the pointer stored by the binding for the session of 'request'.
 207  * If no previous pointer is stored or if 'replace' is not zero, a new value
 208  * is generated using the function 'create_context' called with the 'closure'.
 209  * If 'create_context' is NULL the generated value is 'closure'.
 210  * When a value is created, the function 'free_context' is recorded and will
 211  * be called (with the created value as argument) to free the created value when
 212  * it is not more used.
 213  * This function is atomic: it ensures that 2 threads will not race together.
 214  */
 215 static inline void *afb_req_context_make(struct afb_req req, int replace, void *(*create_context)(void *closure), void (*free_context)(void*), void *closure)
 216 {
 217         return req.itf->context_make(req.closure, replace, create_context, free_context, closure);
 218 }
 219
 220 /*
 221  * Frees the pointer stored by the binding for the session of 'req'
 222  * and sets it to NULL.
 223  *
 224  * Shortcut for: afb_req_context_set(req, NULL, NULL)
 225  */
 226 static inline void afb_req_context_clear(struct afb_req req)
 227 {
 228         afb_req_context_set(req, 0, 0);
 229 }
 230
 231 /*
 232  * Adds one to the count of references of 'req'.
 233  * This function MUST be called by asynchronous implementations
 234  * of verbs if no reply was sent before returning.
 235  */
 236 static inline void afb_req_addref(struct afb_req req)
 237 {
 238         req.itf->addref(req.closure);
 239 }
 240
 241 /*
 242  * Substracts one to the count of references of 'req'.
 243  * This function MUST be called by asynchronous implementations
 244  * of verbs after sending the asynchronous reply.
 245  */
 246 static inline void afb_req_unref(struct afb_req req)
 247 {
 248         req.itf->unref(req.closure);
 249 }
 250
 251 /*
 252  * Closes the session associated with 'req'
 253  * and delete all associated contexts.
 254  */
 255 static inline void afb_req_session_close(struct afb_req req)
 256 {
 257         req.itf->session_close(req.closure);
 258 }
 259
 260 /*
 261  * Sets the level of assurance of the session of 'req'
 262  * to 'level'. The effect of this function is subject of
 263  * security policies.
 264  * Returns 1 on success or 0 if failed.
 265  */
 266 static inline int afb_req_session_set_LOA(struct afb_req req, unsigned level)
 267 {
 268         return req.itf->session_set_LOA(req.closure, level);
 269 }
 270
 271 /*
 272  * Establishes for the client link identified by 'req' a subscription
 273  * to the 'event'.
 274  * Returns 0 in case of successful subscription or -1 in case of error.
 275  */
 276 static inline int afb_req_subscribe(struct afb_req req, struct afb_event event)
 277 {
 278         return req.itf->subscribe(req.closure, event);
 279 }
 280
 281 /*
 282  * Revokes the subscription established to the 'event' for the client
 283  * link identified by 'req'.
 284  * Returns 0 in case of successful subscription or -1 in case of error.
 285  */
 286 static inline int afb_req_unsubscribe(struct afb_req req, struct afb_event event)
 287 {
 288         return req.itf->unsubscribe(req.closure, event);
 289 }
 290
 291 /*
 292  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 293  * This call is made in the context of the request 'req'.
 294  * On completion, the function 'callback' is invoked with the
 295  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 296  * 'status' is 0 on success or negative when on an error reply.
 297  * 'result' is the json object of the reply, you must not call json_object_put
 298  * on the result.
 299  *
 300  * For convenience, the function calls 'json_object_put' for 'args'.
 301  * Thus, in the case where 'args' should remain available after
 302  * the function returns, the function 'json_object_get' shall be used.
 303  *
 304  * See also:
 305  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 306  *  - 'afb_req_subcall_sync' the synchronous version
 307  */
 308 static inline void afb_req_subcall(struct afb_req req, const char *api, const char *verb, struct json_object *args, void (*callback)(void *closure, int iserror, struct json_object *result), void *closure)
 309 {
 310         req.itf->subcall(req.closure, api, verb, args, callback, closure);
 311 }
 312
 313 /*
 314  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 315  * This call is made in the context of the request 'req'.
 316  * On completion, the function 'callback' is invoked with the
 317  * original request 'req', the 'closure' given at call and two
 318  * other parameters: 'iserror' and 'result'.
 319  * 'status' is 0 on success or negative when on an error reply.
 320  * 'result' is the json object of the reply, you must not call json_object_put
 321  * on the result.
 322  *
 323  * For convenience, the function calls 'json_object_put' for 'args'.
 324  * Thus, in the case where 'args' should remain available after
 325  * the function returns, the function 'json_object_get' shall be used.
 326  *
 327  * See also:
 328  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 329  *  - 'afb_req_subcall_sync' the synchronous version
 330  */
 331 static inline void afb_req_subcall_req(struct afb_req req, const char *api, const char *verb, struct json_object *args, void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req req), void *closure)
 332 {
 333         req.itf->subcall_req(req.closure, api, verb, args, callback, closure);
 334 }
 335
 336 /*
 337  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 338  * This call is made in the context of the request 'req'.
 339  * This call is synchronous, it waits untill completion of the request.
 340  * It returns 0 on success or a negative value on error answer.
 341  * The object pointed by 'result' is filled and must be released by the caller
 342  * after its use by calling 'json_object_put'.
 343  *
 344  * For convenience, the function calls 'json_object_put' for 'args'.
 345  * Thus, in the case where 'args' should remain available after
 346  * the function returns, the function 'json_object_get' shall be used.
 347  *
 348  * See also:
 349  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 350  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 351  */
 352 static inline int afb_req_subcall_sync(struct afb_req req, const char *api, const char *verb, struct json_object *args, struct json_object **result)
 353 {
 354         return req.itf->subcallsync(req.closure, api, verb, args, result);
 355 }
 356
 357 /*
 358  * Send associated to 'req' a message described by 'fmt' and following parameters
 359  * to the journal for the verbosity 'level'.
 360  *
 361  * 'file', 'line' and 'func' are indicators of position of the code in source files
 362  * (see macros __FILE__, __LINE__ and __func__).
 363  *
 364  * 'level' is defined by syslog standard:
 365  *      EMERGENCY         0        System is unusable
 366  *      ALERT             1        Action must be taken immediately
 367  *      CRITICAL          2        Critical conditions
 368  *      ERROR             3        Error conditions
 369  *      WARNING           4        Warning conditions
 370  *      NOTICE            5        Normal but significant condition
 371  *      INFO              6        Informational
 372  *      DEBUG             7        Debug-level messages
 373  */
 374 static inline void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...) __attribute__((format(printf, 6, 7)));
 375 static inline void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...)
 376 {
 377         va_list args;
 378         va_start(args, fmt);
 379         req.itf->vverbose(req.closure, level, file, line, func, fmt, args);
 380         va_end(args);
 381 }
 382
 383 /* macro for setting file, line and function automatically */
 384 # if !defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS)
 385 #define AFB_REQ_VERBOSE(req,level,...) afb_req_verbose(req,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
 386 #else
 387 #define AFB_REQ_VERBOSE(req,level,...) afb_req_verbose(req,level,NULL,0,NULL,__VA_ARGS__)
 388 #endif
 389
 390 /*
 391  * Check whether the 'permission' is granted or not to the client
 392  * identified by 'req'.
 393  *
 394  * Returns 1 if the permission is granted or 0 otherwise.
 395  */
 396 static inline int afb_req_has_permission(struct afb_req req, const char *permission)
 397 {
 398         return req.itf->has_permission(req.closure, permission);
 399 }
 400
 401 /*
 402  * Get the application identifier of the client application for the
 403  * request 'req'.
 404  *
 405  * Returns the application identifier or NULL when the application
 406  * can not be identified.
 407  *
 408  * The returned value if not NULL must be freed by the caller
 409  */
 410 static inline char *afb_req_get_application_id(struct afb_req req)
 411 {
 412         return req.itf->get_application_id(req.closure);
 413 }
 414