include/afb/afb-req-x1.h

   1 /*
   2  * Copyright (C) 2015-2020 "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  * Establishing subscriptions MUST be called BEFORE replying to the request.
 278  * Returns 0 in case of successful subscription or -1 in case of error.
 279  */
 280 static inline int afb_req_x1_subscribe(struct afb_req_x1 req, struct afb_event_x1 event)
 281 {
 282         return req.itf->legacy_subscribe_event_x1(req.closure, event);
 283 }
 284
 285 /**
 286  * @deprecated use bindings version 3
 287  *
 288  * Revokes the subscription established to the 'event' for the client
 289  * link identified by 'req'.
 290  * Revoking subscription MUST be called BEFORE replying to the request.
 291  * Returns 0 in case of successful subscription or -1 in case of error.
 292  */
 293 static inline int afb_req_x1_unsubscribe(struct afb_req_x1 req, struct afb_event_x1 event)
 294 {
 295         return req.itf->legacy_unsubscribe_event_x1(req.closure, event);
 296 }
 297
 298 /**
 299  * @deprecated use bindings version 3
 300  *
 301  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 302  * This call is made in the context of the request 'req'.
 303  * On completion, the function 'callback' is invoked with the
 304  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 305  * 'status' is 0 on success or negative when on an error reply.
 306  * 'result' is the json object of the reply, you must not call json_object_put
 307  * on the result.
 308  *
 309  * For convenience, the function calls 'json_object_put' for 'args'.
 310  * Thus, in the case where 'args' should remain available after
 311  * the function returns, the function 'json_object_get' shall be used.
 312  *
 313  * See also:
 314  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 315  *  - 'afb_req_subcall_sync' the synchronous version
 316  */
 317 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)
 318 {
 319         req.itf->legacy_subcall(req.closure, api, verb, args, callback, closure);
 320 }
 321
 322 /**
 323  * @deprecated use bindings version 3
 324  *
 325  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 326  * This call is made in the context of the request 'req'.
 327  * On completion, the function 'callback' is invoked with the
 328  * original request 'req', the 'closure' given at call and two
 329  * other parameters: 'iserror' and 'result'.
 330  * 'status' is 0 on success or negative when on an error reply.
 331  * 'result' is the json object of the reply, you must not call json_object_put
 332  * on the result.
 333  *
 334  * For convenience, the function calls 'json_object_put' for 'args'.
 335  * Thus, in the case where 'args' should remain available after
 336  * the function returns, the function 'json_object_get' shall be used.
 337  *
 338  * See also:
 339  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 340  *  - 'afb_req_subcall_sync' the synchronous version
 341  */
 342 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)
 343 {
 344         req.itf->legacy_subcall_req(req.closure, api, verb, args, callback, closure);
 345 }
 346
 347 /**
 348  * @deprecated use bindings version 3
 349  *
 350  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 351  * This call is made in the context of the request 'req'.
 352  * This call is synchronous, it waits untill completion of the request.
 353  * It returns 0 on success or a negative value on error answer.
 354  * The object pointed by 'result' is filled and must be released by the caller
 355  * after its use by calling 'json_object_put'.
 356  *
 357  * For convenience, the function calls 'json_object_put' for 'args'.
 358  * Thus, in the case where 'args' should remain available after
 359  * the function returns, the function 'json_object_get' shall be used.
 360  *
 361  * See also:
 362  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 363  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 364  */
 365 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)
 366 {
 367         return req.itf->legacy_subcallsync(req.closure, api, verb, args, result);
 368 }
 369
 370 /**
 371  * @deprecated use bindings version 3
 372  *
 373  * Send associated to 'req' a message described by 'fmt' and following parameters
 374  * to the journal for the verbosity 'level'.
 375  *
 376  * 'file', 'line' and 'func' are indicators of position of the code in source files
 377  * (see macros __FILE__, __LINE__ and __func__).
 378  *
 379  * 'level' is defined by syslog standard:
 380  *      EMERGENCY         0        System is unusable
 381  *      ALERT             1        Action must be taken immediately
 382  *      CRITICAL          2        Critical conditions
 383  *      ERROR             3        Error conditions
 384  *      WARNING           4        Warning conditions
 385  *      NOTICE            5        Normal but significant condition
 386  *      INFO              6        Informational
 387  *      DEBUG             7        Debug-level messages
 388  */
 389 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)));
 390 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, ...)
 391 {
 392         va_list args;
 393         va_start(args, fmt);
 394         req.itf->vverbose(req.closure, level, file, line, func, fmt, args);
 395         va_end(args);
 396 }
 397
 398 /**
 399  * @deprecated use bindings version 3
 400  *
 401  * Check whether the 'permission' is granted or not to the client
 402  * identified by 'req'.
 403  *
 404  * Returns 1 if the permission is granted or 0 otherwise.
 405  */
 406 static inline int afb_req_x1_has_permission(struct afb_req_x1 req, const char *permission)
 407 {
 408         return req.itf->has_permission(req.closure, permission);
 409 }
 410
 411 /**
 412  * @deprecated use bindings version 3
 413  *
 414  * Get the application identifier of the client application for the
 415  * request 'req'.
 416  *
 417  * Returns the application identifier or NULL when the application
 418  * can not be identified.
 419  *
 420  * The returned value if not NULL must be freed by the caller
 421  */
 422 static inline char *afb_req_x1_get_application_id(struct afb_req_x1 req)
 423 {
 424         return req.itf->get_application_id(req.closure);
 425 }
 426
 427 /**
 428  * @deprecated use bindings version 3
 429  *
 430  * Get the user identifier (UID) of the client application for the
 431  * request 'req'.
 432  *
 433  * Returns -1 when the application can not be identified.
 434  */
 435 static inline int afb_req_x1_get_uid(struct afb_req_x1 req)
 436 {
 437         return req.itf->get_uid(req.closure);
 438 }
 439
 440 /**
 441  * @deprecated use bindings version 3
 442  *
 443  * Get informations about the client of the
 444  * request 'req'.
 445  *
 446  * Returns an object with client informations:
 447  *  {
 448  *    "pid": int, "uid": int, "gid": int,
 449  *    "smack": string, "appid": string,
 450  *    "uuid": string, "LOA": int
 451  *  }
 452  */
 453 static inline struct json_object *afb_req_x1_get_client_info(struct afb_req_x1 req)
 454 {
 455         return req.itf->get_client_info(req.closure);
 456 }
 457
 458
 459
 460 /** @} */