include/afb/afb-req-x1.h

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