include/afb/afb-req-x2.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-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  * @param req the request
 462  * @param event the event to subscribe
 463  *
 464  * @return 0 in case of successful subscription or -1 in case of error.
 465  */
 466 static inline
 467 int afb_req_x2_subscribe(
 468                         struct afb_req_x2 *req,
 469                         struct afb_event_x2 *event)
 470 {
 471         return req->itf->subscribe_event_x2(req, event);
 472 }
 473
 474 /**
 475  * Revokes the subscription established to the 'event' for the client
 476  * link identified by 'req'.
 477  * Returns 0 in case of successful subscription or -1 in case of error.
 478  *
 479  * @param req the request
 480  * @param event the event to revoke
 481  *
 482  * @return 0 in case of successful subscription or -1 in case of error.
 483  */
 484 static inline
 485 int afb_req_x2_unsubscribe(
 486                         struct afb_req_x2 *req,
 487                         struct afb_event_x2 *event)
 488 {
 489         return req->itf->unsubscribe_event_x2(req, event);
 490 }
 491
 492 /**
 493  * @deprecated use @ref afb_req_x2_subcall
 494  *
 495  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 496  * This call is made in the context of the request 'req'.
 497  * On completion, the function 'callback' is invoked with the
 498  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 499  * 'status' is 0 on success or negative when on an error reply.
 500  * 'result' is the json object of the reply, you must not call json_object_put
 501  * on the result.
 502  *
 503  * For convenience, the function calls 'json_object_put' for 'args'.
 504  * Thus, in the case where 'args' should remain available after
 505  * the function returns, the function 'json_object_get' shall be used.
 506  *
 507  * @param req the request
 508  * @param api the name of the api to call
 509  * @param verb the name of the verb to call
 510  * @param args the arguments of the call as a JSON object
 511  * @param callback the call back that will receive the reply
 512  * @param closure the closure passed back to the callback
 513  *
 514  * @see afb_req_x2_subcall
 515  * @see afb_req_x2_subcall_sync
 516  */
 517 static inline
 518 void afb_req_x2_subcall_legacy(
 519                         struct afb_req_x2 *req,
 520                         const char *api,
 521                         const char *verb,
 522                         struct json_object *args,
 523                         void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req_x2 *req),
 524                         void *closure)
 525 {
 526         req->itf->legacy_subcall_request(req, api, verb, args, callback, closure);
 527 }
 528
 529 /**
 530  * @deprecated use @ref afb_req_x2_subcall_sync
 531  *
 532  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 533  * This call is made in the context of the request 'req'.
 534  * This call is synchronous, it waits untill completion of the request.
 535  * It returns 0 on success or a negative value on error answer.
 536  * The object pointed by 'result' is filled and must be released by the caller
 537  * after its use by calling 'json_object_put'.
 538  *
 539  * For convenience, the function calls 'json_object_put' for 'args'.
 540  * Thus, in the case where 'args' should remain available after
 541  * the function returns, the function 'json_object_get' shall be used.
 542  *
 543  * @param req the request
 544  * @param api the name of the api to call
 545  * @param verb the name of the verb to call
 546  * @param args the arguments of the call as a JSON object
 547  * @param result the pointer to the JSON object pointer that will receive the result
 548  *
 549  * @return 0 on success or a negative value on error answer.
 550  *
 551  * @see afb_req_x2_subcall
 552  * @see afb_req_x2_subcall_sync
 553  */
 554 static inline
 555 int afb_req_x2_subcall_sync_legacy(
 556                         struct afb_req_x2 *req,
 557                         const char *api,
 558                         const char *verb,
 559                         struct json_object *args,
 560                         struct json_object **result)
 561 {
 562         return req->itf->legacy_subcallsync(req, api, verb, args, result);
 563 }
 564
 565 /**
 566  * Send associated to 'req' a message described by 'fmt' and its 'args'
 567  * to the journal for the verbosity 'level'.
 568  *
 569  * 'file', 'line' and 'func' are indicators of position of the code in source files
 570  * (see macros __FILE__, __LINE__ and __func__).
 571  *
 572  * 'level' is defined by syslog standard:
 573  *      EMERGENCY         0        System is unusable
 574  *      ALERT             1        Action must be taken immediately
 575  *      CRITICAL          2        Critical conditions
 576  *      ERROR             3        Error conditions
 577  *      WARNING           4        Warning conditions
 578  *      NOTICE            5        Normal but significant condition
 579  *      INFO              6        Informational
 580  *      DEBUG             7        Debug-level messages
 581  *
 582  * @param req the request
 583  * @param level the level of the message
 584  * @param file the source filename that emits the message or NULL
 585  * @param line the line number in the source filename that emits the message
 586  * @param func the name of the function that emits the message or NULL
 587  * @param fmt the message format as for printf
 588  * @param args the arguments to the format 'fmt'
 589  *
 590  * @see printf
 591  * @see afb_req_x2_verbose
 592  */
 593 static inline
 594 void afb_req_x2_vverbose(
 595                         struct afb_req_x2 *req,
 596                         int level, const char *file,
 597                         int line,
 598                         const char * func,
 599                         const char *fmt,
 600                         va_list args)
 601 {
 602         req->itf->vverbose(req, level, file, line, func, fmt, args);
 603 }
 604
 605 /**
 606  * Send associated to 'req' a message described by 'fmt' and following parameters
 607  * to the journal for the verbosity 'level'.
 608  *
 609  * 'file', 'line' and 'func' are indicators of position of the code in source files
 610  * (see macros __FILE__, __LINE__ and __func__).
 611  *
 612  * 'level' is defined by syslog standard:
 613  *      EMERGENCY         0        System is unusable
 614  *      ALERT             1        Action must be taken immediately
 615  *      CRITICAL          2        Critical conditions
 616  *      ERROR             3        Error conditions
 617  *      WARNING           4        Warning conditions
 618  *      NOTICE            5        Normal but significant condition
 619  *      INFO              6        Informational
 620  *      DEBUG             7        Debug-level messages
 621  *
 622  * @param req the request
 623  * @param level the level of the message
 624  * @param file the source filename that emits the message or NULL
 625  * @param line the line number in the source filename that emits the message
 626  * @param func the name of the function that emits the message or NULL
 627  * @param fmt the message format as for printf
 628  * @param ... the arguments of the format 'fmt'
 629  *
 630  * @see printf
 631  * @see afb_req_x2_vverbose
 632  */
 633 __attribute__((format(printf, 6, 7)))
 634 static inline
 635 void afb_req_x2_verbose(
 636                         struct afb_req_x2 *req,
 637                         int level, const char *file,
 638                         int line,
 639                         const char * func,
 640                         const char *fmt,
 641                         ...)
 642 {
 643         va_list args;
 644         va_start(args, fmt);
 645         afb_req_x2_vverbose(req, level, file, line, func, fmt, args);
 646         va_end(args);
 647 }
 648
 649 /**
 650  * Check whether the 'permission' is granted or not to the client
 651  * identified by 'req'.
 652  *
 653  * @param req the request
 654  * @param permission string to check
 655  *
 656  * @return 1 if the permission is granted or 0 otherwise.
 657  */
 658 static inline
 659 int afb_req_x2_has_permission(
 660                         struct afb_req_x2 *req,
 661                         const char *permission)
 662 {
 663         return req->itf->has_permission(req, permission);
 664 }
 665
 666 /**
 667  * Get the application identifier of the client application for the
 668  * request 'req'.
 669  *
 670  * Returns the application identifier or NULL when the application
 671  * can not be identified.
 672  *
 673  * The returned value if not NULL must be freed by the caller
 674  *
 675  * @param req the request
 676  *
 677  * @return the string for the application id of the client MUST BE FREED
 678  */
 679 static inline
 680 char *afb_req_x2_get_application_id(
 681                         struct afb_req_x2 *req)
 682 {
 683         return req->itf->get_application_id(req);
 684 }
 685
 686 /**
 687  * Get the user identifier (UID) of the client for the
 688  * request 'req'.
 689  *
 690  * @param req the request
 691  *
 692  * @return -1 when the application can not be identified or the unix uid.
 693  *
 694  */
 695 static inline
 696 int afb_req_x2_get_uid(
 697                         struct afb_req_x2 *req)
 698 {
 699         return req->itf->get_uid(req);
 700 }
 701
 702 /**
 703  * Get informations about the client of the
 704  * request 'req'.
 705  *
 706  * Returns an object with client informations:
 707  *  {
 708  *    "pid": int, "uid": int, "gid": int,
 709  *    "label": string, "id": string, "user": string,
 710  *    "uuid": string, "LOA": int
 711  *  }
 712  *
 713  * If some of this information can't be computed, the field of the return
 714  * object will not be set at all.
 715  *
 716  * @param req the request
 717  *
 718  * @return a JSON object that must be freed using @ref json_object_put
 719  */
 720 static inline
 721 struct json_object *afb_req_x2_get_client_info(
 722                         struct afb_req_x2 *req)
 723 {
 724         return req->itf->get_client_info(req);
 725 }
 726
 727 /**
 728  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 729  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 730  *
 731  * For convenience, the function calls 'json_object_put' for 'args'.
 732  * Thus, in the case where 'args' should remain available after
 733  * the function returns, the function 'json_object_get' shall be used.
 734  *
 735  * The 'callback' receives 5 arguments:
 736  *  1. 'closure' the user defined closure pointer 'closure',
 737  *  2. 'object'  a JSON object returned (can be NULL)
 738  *  3. 'error'   a string not NULL in case of error
 739  *  4. 'info'    a string handling some info (can be NULL)
 740  *  5. 'req'     the req
 741  *
 742  * @param req      The request
 743  * @param api      The api name of the method to call
 744  * @param verb     The verb name of the method to call
 745  * @param args     The arguments to pass to the method
 746  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_x2_subcall_flags
 747  * @param callback The to call on completion
 748  * @param closure  The closure to pass to the callback
 749  *
 750  * @see also 'afb_req_subcall_sync'
 751  */
 752 static inline
 753 void afb_req_x2_subcall(
 754                         struct afb_req_x2 *req,
 755                         const char *api,
 756                         const char *verb,
 757                         struct json_object *args,
 758                         int flags,
 759                         void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_req_x2 *req),
 760                         void *closure)
 761 {
 762         req->itf->subcall(req, api, verb, args, flags, callback, closure);
 763 }
 764
 765 /**
 766  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 767  * This call is made in the context of the request 'req'.
 768  * This call is synchronous, it waits untill completion of the request.
 769  * It returns 0 on success or a negative value on error answer.
 770  *
 771  * For convenience, the function calls 'json_object_put' for 'args'.
 772  * Thus, in the case where 'args' should remain available after
 773  * the function returns, the function 'json_object_get' shall be used.
 774  *
 775  * See also:
 776  *  - 'afb_req_x2_subcall_req' that is convenient to keep request alive automatically.
 777  *  - 'afb_req_x2_subcall' that doesn't keep request alive automatically.
 778  *
 779  * @param req      The request
 780  * @param api      The api name of the method to call
 781  * @param verb     The verb name of the method to call
 782  * @param args     The arguments to pass to the method
 783  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_x2_subcall_flags
 784  * @param object   a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL)
 785  * @param error    a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL)
 786  * @param info     a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL)
 787  *
 788  * @return 0 in case of success or -1 in case of error
 789  */
 790 static inline
 791 int afb_req_x2_subcall_sync(
 792                         struct afb_req_x2 *req,
 793                         const char *api,
 794                         const char *verb,
 795                         struct json_object *args,
 796                         int flags,
 797                         struct json_object **object,
 798                         char **error,
 799                         char **info)
 800 {
 801         return req->itf->subcallsync(req, api, verb, args, flags, object, error, info);
 802 }
 803
 804
 805 /** @} */