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