include/afb/afb-req-x2.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-x2-itf.h"
  21 #include "afb-api-x3.h"
  22
  23 /** @defgroup AFB_REQ
  24  *  @{ */
  25
  26 /**
  27  * Checks whether the request 'req' is valid or not.
  28  *
  29  * @param req the request to check
  30  *
  31  * @return 0 if not valid or 1 if valid.
  32  */
  33 static inline
  34 int afb_req_x2_is_valid(
  35                         struct afb_req_x2 *req)
  36 {
  37         return !!req;
  38 }
  39
  40 /**
  41  * Retrieves the api that serves the request
  42  *
  43  * @param req the request whose serving api is queried
  44  *
  45  * @return the api serving the request
  46  */
  47 static inline
  48 struct afb_api_x3 *afb_req_x2_get_api(
  49                         struct afb_req_x2 *req)
  50 {
  51         return req->api;
  52 }
  53
  54 /**
  55  * Retrieves the callback data of the verb. This callback data is set
  56  * when the verb is created.
  57  *
  58  * @param req whose verb vcbdata is queried
  59  *
  60  * @return the callback data attached to the verb description
  61  */
  62 static inline
  63 void *afb_req_x2_get_vcbdata(
  64                         struct afb_req_x2 *req)
  65 {
  66         return req->vcbdata;
  67 }
  68
  69 /**
  70  * Retrieve the name of the called api.
  71  *
  72  * @param req the request
  73  *
  74  * @return the name of the called api
  75  *
  76  * @see afb_api_x3_add_alias
  77  */
  78 static inline
  79 const char *afb_req_x2_get_called_api(
  80                         struct afb_req_x2 *req)
  81 {
  82         return req->called_api;
  83 }
  84
  85 /**
  86  * Retrieve the name of the called verb
  87  *
  88  * @param req the request
  89  *
  90  * @return the name of the called verb
  91  */
  92 static inline
  93 const char *afb_req_x2_get_called_verb(
  94                         struct afb_req_x2 *req)
  95 {
  96         return req->called_verb;
  97 }
  98
  99 /**
 100  * Is the log message of 'level (as defined for syslog) required for the
 101  * request 'req'?
 102  *
 103  * @param req the request
 104  * @param level the level to check as defined for syslog:
 105  *
 106  *      EMERGENCY         0        System is unusable
 107  *      ALERT             1        Action must be taken immediately
 108  *      CRITICAL          2        Critical conditions
 109  *      ERROR             3        Error conditions
 110  *      WARNING           4        Warning conditions
 111  *      NOTICE            5        Normal but significant condition
 112  *      INFO              6        Informational
 113  *      DEBUG             7        Debug-level messages
 114  *
 115  * @return 0 if not required or a value not null if required
 116  *
 117  * @see syslog
 118  */
 119 static inline
 120 int afb_req_x2_wants_log_level(
 121                         struct afb_req_x2 *req,
 122                         int level)
 123 {
 124         return afb_api_x3_wants_log_level(afb_req_x2_get_api(req), level);
 125 }
 126
 127 /**
 128  * Gets from the request 'req' the argument of 'name'.
 129  *
 130  * Returns a PLAIN structure of type 'struct afb_arg'.
 131  *
 132  * When the argument of 'name' is not found, all fields of result are set to NULL.
 133  *
 134  * When the argument of 'name' is found, the fields are filled,
 135  * in particular, the field 'result.name' is set to 'name'.
 136  *
 137  * There is a special name value: the empty string.
 138  * The argument of name "" is defined only if the request was made using
 139  * an HTTP POST of Content-Type "application/json". In that case, the
 140  * argument of name "" receives the value of the body of the HTTP request.
 141  *
 142  * @param req the request
 143  * @param name the name of the argument to get
 144  *
 145  * @return a structure describing the retrieved argument for the request
 146  *
 147  * @see afb_req_x2_value
 148  * @see afb_req_x2_path
 149  */
 150 static inline
 151 struct afb_arg afb_req_x2_get(
 152                         struct afb_req_x2 *req,
 153                         const char *name)
 154 {
 155         return req->itf->get(req, name);
 156 }
 157
 158 /**
 159  * Gets from the request 'req' the string value of the argument of 'name'.
 160  * Returns NULL if when there is no argument of 'name'.
 161  * Returns the value of the argument of 'name' otherwise.
 162  *
 163  * Shortcut for: afb_req_x2_get(req, name).value
 164  *
 165  * @param req the request
 166  * @param name the name of the argument's value to get
 167  *
 168  * @return the value as a string or NULL
 169  *
 170  * @see afb_req_x2_get
 171  * @see afb_req_x2_path
 172  */
 173 static inline
 174 const char *afb_req_x2_value(
 175                         struct afb_req_x2 *req,
 176                         const char *name)
 177 {
 178         return afb_req_x2_get(req, name).value;
 179 }
 180
 181 /**
 182  * Gets from the request 'req' the path for file attached to the argument of 'name'.
 183  * Returns NULL if when there is no argument of 'name' or when there is no file.
 184  * Returns the path of the argument of 'name' otherwise.
 185  *
 186  * Shortcut for: afb_req_x2_get(req, name).path
 187  *
 188  * @param req the request
 189  * @param name the name of the argument's path to get
 190  *
 191  * @return the path if any or NULL
 192  *
 193  * @see afb_req_x2_get
 194  * @see afb_req_x2_value
 195  */
 196 static inline
 197 const char *afb_req_x2_path(
 198                         struct afb_req_x2 *req,
 199                         const char *name)
 200 {
 201         return afb_req_x2_get(req, name).path;
 202 }
 203
 204 /**
 205  * Gets from the request 'req' the json object hashing the arguments.
 206  *
 207  * The returned object must not be released using 'json_object_put'.
 208  *
 209  * @param req the request
 210  *
 211  * @return the JSON object of the query
 212  *
 213  * @see afb_req_x2_get
 214  * @see afb_req_x2_value
 215  * @see afb_req_x2_path
 216  */
 217 static inline
 218 struct json_object *afb_req_x2_json(
 219                         struct afb_req_x2 *req)
 220 {
 221         return req->itf->json(req);
 222 }
 223
 224 /**
 225  * Sends a reply to the request 'req'.
 226  *
 227  * The status of the reply is set to 'error' (that must be NULL on success).
 228  * Its send the object 'obj' (can be NULL) with an
 229  * informational comment 'info (can also be NULL).
 230  *
 231  * For convenience, the function calls 'json_object_put' for 'obj'.
 232  * Thus, in the case where 'obj' should remain available after
 233  * the function returns, the function 'json_object_get' shall be used.
 234  *
 235  * @param req the request
 236  * @param obj the replied object or NULL
 237  * @param error the error message if it is a reply error or NULL
 238  * @param info an informative text or NULL
 239  *
 240  * @see afb_req_x2_reply_v
 241  * @see afb_req_x2_reply_f
 242  */
 243 static inline
 244 void afb_req_x2_reply(
 245                         struct afb_req_x2 *req,
 246                         struct json_object *obj,
 247                         const char *error,
 248                         const char *info)
 249 {
 250         req->itf->reply(req, obj, error, info);
 251 }
 252
 253 /**
 254  * Same as 'afb_req_x2_reply_f' but the arguments to the format 'info'
 255  * are given as a variable argument list instance.
 256  *
 257  * For convenience, the function calls 'json_object_put' for 'obj'.
 258  * Thus, in the case where 'obj' should remain available after
 259  * the function returns, the function 'json_object_get' shall be used.
 260  *
 261  * @param req the request
 262  * @param obj the replied object or NULL
 263  * @param error the error message if it is a reply error or NULL
 264  * @param info an informative text containing a format as for vprintf
 265  * @param args the va_list of arguments to the format as for vprintf
 266  *
 267  * @see afb_req_x2_reply
 268  * @see afb_req_x2_reply_f
 269  * @see vprintf
 270  */
 271 static inline
 272 void afb_req_x2_reply_v(
 273                         struct afb_req_x2 *req,
 274                         struct json_object *obj,
 275                         const char *error,
 276                         const char *info,
 277                         va_list args)
 278 {
 279         req->itf->vreply(req, obj, error, info, args);
 280 }
 281
 282 /**
 283  * Same as 'afb_req_x2_reply' but the 'info' is a formatting
 284  * string followed by arguments.
 285  *
 286  * For convenience, the function calls 'json_object_put' for 'obj'.
 287  * Thus, in the case where 'obj' should remain available after
 288  * the function returns, the function 'json_object_get' shall be used.
 289  *
 290  * @param req the request
 291  * @param obj the replied object or NULL
 292  * @param error the error message if it is a reply error or NULL
 293  * @param info an informative text containing a format as for printf
 294  * @param ... the arguments to the format as for printf
 295  *
 296  * @see afb_req_x2_reply
 297  * @see afb_req_x2_reply_v
 298  * @see printf
 299  */
 300 __attribute__((format(printf, 4, 5)))
 301 static inline
 302 void afb_req_x2_reply_f(
 303                         struct afb_req_x2 *req,
 304                         struct json_object *obj,
 305                         const char *error,
 306                         const char *info,
 307                         ...)
 308 {
 309         va_list args;
 310         va_start(args, info);
 311         afb_req_x2_reply_v(req, obj, error, info, args);
 312         va_end(args);
 313 }
 314
 315 /**
 316  * Manage the pointer stored by the binding for the client session of 'req'.
 317  *
 318  * If no previous pointer is stored or if 'replace' is not zero, a new value
 319  * is generated using the function 'create_context' called with the 'closure'.
 320  * If 'create_context' is NULL the generated value is 'closure'.
 321  *
 322  * When a value is created, the function 'free_context' is recorded and will
 323  * be called (with the created value as argument) to free the created value when
 324  * it is not more used.
 325  *
 326  * This function is atomic: it ensures that 2 threads will not race together.
 327  *
 328  * @param req the request
 329  * @param replace if not zero an existing value is replaced
 330  * @param create_context the creation function or NULL
 331  * @param free_context the destroying function or NULL
 332  * @param closure the closure to the creation function
 333  *
 334  * @return the stored value
 335  */
 336 static inline
 337 void *afb_req_x2_context(
 338                         struct afb_req_x2 *req,
 339                         int replace,
 340                         void *(*create_context)(void *closure),
 341                         void (*free_context)(void*),
 342                         void *closure)
 343 {
 344         return req->itf->context_make(req, replace, create_context, free_context, closure);
 345 }
 346
 347 /**
 348  * Gets the pointer stored by the binding for the session of 'req'.
 349  * When the binding has not yet recorded a pointer, NULL is returned.
 350  *
 351  * Shortcut for: afb_req_x2_context(req, 0, NULL, NULL, NULL)
 352  *
 353  * @param req the request
 354  *
 355  * @return the previously stored value
 356  */
 357 static inline
 358 void *afb_req_x2_context_get(
 359                         struct afb_req_x2 *req)
 360 {
 361         return afb_req_x2_context(req, 0, 0, 0, 0);
 362 }
 363
 364 /**
 365  * Stores for the binding the pointer 'context' to the session of 'req'.
 366  * The function 'free_context' will be called when the session is closed
 367  * or if binding stores an other pointer.
 368  *
 369  * Shortcut for: afb_req_x2_context(req, 1, NULL, free_context, context)
 370  *
 371  *
 372  * @param req the request
 373  * @param context the context value to store
 374  * @param free_context the cleaning function for the stored context (can be NULL)
 375  */
 376 static inline
 377 void afb_req_x2_context_set(
 378                         struct afb_req_x2 *req,
 379                         void *context,
 380                         void (*free_context)(void*))
 381 {
 382         afb_req_x2_context(req, 1, 0, free_context, context);
 383 }
 384
 385 /**
 386  * Frees the pointer stored by the binding for the session of 'req'
 387  * and sets it to NULL.
 388  *
 389  * Shortcut for: afb_req_x2_context_set(req, NULL, NULL)
 390  *
 391  * @param req the request
 392  */
 393 static inline
 394 void afb_req_x2_context_clear(
 395                         struct afb_req_x2 *req)
 396 {
 397         afb_req_x2_context(req, 1, 0, 0, 0);
 398 }
 399
 400 /**
 401  * Increments the count of references of 'req'.
 402  *
 403  * @param req the request
 404  *
 405  * @return returns the request req
 406  */
 407 static inline
 408 struct afb_req_x2 *afb_req_x2_addref(
 409                         struct afb_req_x2 *req)
 410 {
 411         return req->itf->addref(req);
 412 }
 413
 414 /**
 415  * Decrement the count of references of 'req'.
 416  *
 417  * @param req the request
 418  */
 419 static inline
 420 void afb_req_x2_unref(
 421                         struct afb_req_x2 *req)
 422 {
 423         req->itf->unref(req);
 424 }
 425
 426 /**
 427  * Closes the session associated with 'req'
 428  * and delete all associated contexts.
 429  *
 430  * @param req the request
 431  */
 432 static inline
 433 void afb_req_x2_session_close(
 434                         struct afb_req_x2 *req)
 435 {
 436         req->itf->session_close(req);
 437 }
 438
 439 /**
 440  * Sets the level of assurance of the session of 'req'
 441  * to 'level'. The effect of this function is subject of
 442  * security policies.
 443  *
 444  * @param req the request
 445  * @param level of assurance from 0 to 7
 446  *
 447  * @return 0 on success or -1 if failed.
 448  */
 449 static inline
 450 int afb_req_x2_session_set_LOA(
 451                         struct afb_req_x2 *req,
 452                         unsigned level)
 453 {
 454         return req->itf->session_set_LOA(req, level);
 455 }
 456
 457 /**
 458  * Establishes for the client link identified by 'req' a subscription
 459  * to the 'event'.
 460  *
 461  * Establishing subscription MUST be called BEFORE replying to the request.
 462  *
 463  * @param req the request
 464  * @param event the event to subscribe
 465  *
 466  * @return 0 in case of successful subscription or -1 in case of error.
 467  */
 468 static inline
 469 int afb_req_x2_subscribe(
 470                         struct afb_req_x2 *req,
 471                         struct afb_event_x2 *event)
 472 {
 473         return req->itf->subscribe_event_x2(req, event);
 474 }
 475
 476 /**
 477  * Revokes the subscription established to the 'event' for the client
 478  * link identified by 'req'.
 479  * Returns 0 in case of successful subscription or -1 in case of error.
 480  *
 481  * Revoking subscription MUST be called BEFORE replying to the request.
 482  *
 483  * @param req the request
 484  * @param event the event to revoke
 485  *
 486  * @return 0 in case of successful subscription or -1 in case of error.
 487  */
 488 static inline
 489 int afb_req_x2_unsubscribe(
 490                         struct afb_req_x2 *req,
 491                         struct afb_event_x2 *event)
 492 {
 493         return req->itf->unsubscribe_event_x2(req, event);
 494 }
 495
 496 /**
 497  * @deprecated use @ref afb_req_x2_subcall
 498  *
 499  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 500  * This call is made in the context of the request 'req'.
 501  * On completion, the function 'callback' is invoked with the
 502  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 503  * 'status' is 0 on success or negative when on an error reply.
 504  * 'result' is the json object of the reply, you must not call json_object_put
 505  * on the result.
 506  *
 507  * For convenience, the function calls 'json_object_put' for 'args'.
 508  * Thus, in the case where 'args' should remain available after
 509  * the function returns, the function 'json_object_get' shall be used.
 510  *
 511  * @param req the request
 512  * @param api the name of the api to call
 513  * @param verb the name of the verb to call
 514  * @param args the arguments of the call as a JSON object
 515  * @param callback the call back that will receive the reply
 516  * @param closure the closure passed back to the callback
 517  *
 518  * @see afb_req_x2_subcall
 519  * @see afb_req_x2_subcall_sync
 520  */
 521 static inline
 522 void afb_req_x2_subcall_legacy(
 523                         struct afb_req_x2 *req,
 524                         const char *api,
 525                         const char *verb,
 526                         struct json_object *args,
 527                         void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req_x2 *req),
 528                         void *closure)
 529 {
 530         req->itf->legacy_subcall_request(req, api, verb, args, callback, closure);
 531 }
 532
 533 /**
 534  * @deprecated use @ref afb_req_x2_subcall_sync
 535  *
 536  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 537  * This call is made in the context of the request 'req'.
 538  * This call is synchronous, it waits untill completion of the request.
 539  * It returns 0 on success or a negative value on error answer.
 540  * The object pointed by 'result' is filled and must be released by the caller
 541  * after its use by calling 'json_object_put'.
 542  *
 543  * For convenience, the function calls 'json_object_put' for 'args'.
 544  * Thus, in the case where 'args' should remain available after
 545  * the function returns, the function 'json_object_get' shall be used.
 546  *
 547  * @param req the request
 548  * @param api the name of the api to call
 549  * @param verb the name of the verb to call
 550  * @param args the arguments of the call as a JSON object
 551  * @param result the pointer to the JSON object pointer that will receive the result
 552  *
 553  * @return 0 on success or a negative value on error answer.
 554  *
 555  * @see afb_req_x2_subcall
 556  * @see afb_req_x2_subcall_sync
 557  */
 558 static inline
 559 int afb_req_x2_subcall_sync_legacy(
 560                         struct afb_req_x2 *req,
 561                         const char *api,
 562                         const char *verb,
 563                         struct json_object *args,
 564                         struct json_object **result)
 565 {
 566         return req->itf->legacy_subcallsync(req, api, verb, args, result);
 567 }
 568
 569 /**
 570  * Send associated to 'req' a message described by 'fmt' and its 'args'
 571  * to the journal for the verbosity 'level'.
 572  *
 573  * 'file', 'line' and 'func' are indicators of position of the code in source files
 574  * (see macros __FILE__, __LINE__ and __func__).
 575  *
 576  * 'level' is defined by syslog standard:
 577  *      EMERGENCY         0        System is unusable
 578  *      ALERT             1        Action must be taken immediately
 579  *      CRITICAL          2        Critical conditions
 580  *      ERROR             3        Error conditions
 581  *      WARNING           4        Warning conditions
 582  *      NOTICE            5        Normal but significant condition
 583  *      INFO              6        Informational
 584  *      DEBUG             7        Debug-level messages
 585  *
 586  * @param req the request
 587  * @param level the level of the message
 588  * @param file the source filename that emits the message or NULL
 589  * @param line the line number in the source filename that emits the message
 590  * @param func the name of the function that emits the message or NULL
 591  * @param fmt the message format as for printf
 592  * @param args the arguments to the format 'fmt'
 593  *
 594  * @see printf
 595  * @see afb_req_x2_verbose
 596  */
 597 static inline
 598 void afb_req_x2_vverbose(
 599                         struct afb_req_x2 *req,
 600                         int level, const char *file,
 601                         int line,
 602                         const char * func,
 603                         const char *fmt,
 604                         va_list args)
 605 {
 606         req->itf->vverbose(req, level, file, line, func, fmt, args);
 607 }
 608
 609 /**
 610  * Send associated to 'req' a message described by 'fmt' and following parameters
 611  * to the journal for the verbosity 'level'.
 612  *
 613  * 'file', 'line' and 'func' are indicators of position of the code in source files
 614  * (see macros __FILE__, __LINE__ and __func__).
 615  *
 616  * 'level' is defined by syslog standard:
 617  *      EMERGENCY         0        System is unusable
 618  *      ALERT             1        Action must be taken immediately
 619  *      CRITICAL          2        Critical conditions
 620  *      ERROR             3        Error conditions
 621  *      WARNING           4        Warning conditions
 622  *      NOTICE            5        Normal but significant condition
 623  *      INFO              6        Informational
 624  *      DEBUG             7        Debug-level messages
 625  *
 626  * @param req the request
 627  * @param level the level of the message
 628  * @param file the source filename that emits the message or NULL
 629  * @param line the line number in the source filename that emits the message
 630  * @param func the name of the function that emits the message or NULL
 631  * @param fmt the message format as for printf
 632  * @param ... the arguments of the format 'fmt'
 633  *
 634  * @see printf
 635  * @see afb_req_x2_vverbose
 636  */
 637 __attribute__((format(printf, 6, 7)))
 638 static inline
 639 void afb_req_x2_verbose(
 640                         struct afb_req_x2 *req,
 641                         int level, const char *file,
 642                         int line,
 643                         const char * func,
 644                         const char *fmt,
 645                         ...)
 646 {
 647         va_list args;
 648         va_start(args, fmt);
 649         afb_req_x2_vverbose(req, level, file, line, func, fmt, args);
 650         va_end(args);
 651 }
 652
 653 /**
 654  * Check whether the 'permission' is granted or not to the client
 655  * identified by 'req'.
 656  *
 657  * @param req the request
 658  * @param permission string to check
 659  *
 660  * @return 1 if the permission is granted or 0 otherwise.
 661  */
 662 static inline
 663 int afb_req_x2_has_permission(
 664                         struct afb_req_x2 *req,
 665                         const char *permission)
 666 {
 667         return req->itf->has_permission(req, permission);
 668 }
 669
 670 /**
 671  * Get the application identifier of the client application for the
 672  * request 'req'.
 673  *
 674  * Returns the application identifier or NULL when the application
 675  * can not be identified.
 676  *
 677  * The returned value if not NULL must be freed by the caller
 678  *
 679  * @param req the request
 680  *
 681  * @return the string for the application id of the client MUST BE FREED
 682  */
 683 static inline
 684 char *afb_req_x2_get_application_id(
 685                         struct afb_req_x2 *req)
 686 {
 687         return req->itf->get_application_id(req);
 688 }
 689
 690 /**
 691  * Get the user identifier (UID) of the client for the
 692  * request 'req'.
 693  *
 694  * @param req the request
 695  *
 696  * @return -1 when the application can not be identified or the unix uid.
 697  *
 698  */
 699 static inline
 700 int afb_req_x2_get_uid(
 701                         struct afb_req_x2 *req)
 702 {
 703         return req->itf->get_uid(req);
 704 }
 705
 706 /**
 707  * Get informations about the client of the
 708  * request 'req'.
 709  *
 710  * Returns an object with client informations:
 711  *  {
 712  *    "pid": int, "uid": int, "gid": int,
 713  *    "label": string, "id": string, "user": string,
 714  *    "uuid": string, "LOA": int
 715  *  }
 716  *
 717  * If some of this information can't be computed, the field of the return
 718  * object will not be set at all.
 719  *
 720  * @param req the request
 721  *
 722  * @return a JSON object that must be freed using @ref json_object_put
 723  */
 724 static inline
 725 struct json_object *afb_req_x2_get_client_info(
 726                         struct afb_req_x2 *req)
 727 {
 728         return req->itf->get_client_info(req);
 729 }
 730
 731 /**
 732  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 733  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 734  *
 735  * For convenience, the function calls 'json_object_put' for 'args'.
 736  * Thus, in the case where 'args' should remain available after
 737  * the function returns, the function 'json_object_get' shall be used.
 738  *
 739  * The 'callback' receives 5 arguments:
 740  *  1. 'closure' the user defined closure pointer 'closure',
 741  *  2. 'object'  a JSON object returned (can be NULL)
 742  *  3. 'error'   a string not NULL in case of error
 743  *  4. 'info'    a string handling some info (can be NULL)
 744  *  5. 'req'     the req
 745  *
 746  * NOTE: For convenience, *json_object_put* is called on 'object' after the
 747  * callback returns. So, it is wrong to call *json_object_put* in the callback.
 748  *
 749  * @param req      The request
 750  * @param api      The api name of the method to call
 751  * @param verb     The verb name of the method to call
 752  * @param args     The arguments to pass to the method
 753  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_x2_subcall_flags
 754  * @param callback The to call on completion
 755  * @param closure  The closure to pass to the callback
 756  *
 757  * @see also 'afb_req_subcall_sync'
 758  */
 759 static inline
 760 void afb_req_x2_subcall(
 761                         struct afb_req_x2 *req,
 762                         const char *api,
 763                         const char *verb,
 764                         struct json_object *args,
 765                         int flags,
 766                         void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_req_x2 *req),
 767                         void *closure)
 768 {
 769         req->itf->subcall(req, api, verb, args, flags, callback, closure);
 770 }
 771
 772 /**
 773  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 774  * This call is made in the context of the request 'req'.
 775  * This call is synchronous, it waits untill completion of the request.
 776  * It returns 0 on success or a negative value on error answer.
 777  *
 778  * For convenience, the function calls 'json_object_put' for 'args'.
 779  * Thus, in the case where 'args' should remain available after
 780  * the function returns, the function 'json_object_get' shall be used.
 781  *
 782  * See also:
 783  *  - 'afb_req_x2_subcall_req' that is convenient to keep request alive automatically.
 784  *  - 'afb_req_x2_subcall' that doesn't keep request alive automatically.
 785  *
 786  * @param req      The request
 787  * @param api      The api name of the method to call
 788  * @param verb     The verb name of the method to call
 789  * @param args     The arguments to pass to the method
 790  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_x2_subcall_flags
 791  * @param object   a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL)
 792  * @param error    a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL)
 793  * @param info     a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL)
 794  *
 795  * @return 0 in case of success or -1 in case of error
 796  */
 797 static inline
 798 int afb_req_x2_subcall_sync(
 799                         struct afb_req_x2 *req,
 800                         const char *api,
 801                         const char *verb,
 802                         struct json_object *args,
 803                         int flags,
 804                         struct json_object **object,
 805                         char **error,
 806                         char **info)
 807 {
 808         return req->itf->subcallsync(req, api, verb, args, flags, object, error, info);
 809 }
 810
 811
 812 /** @} */