docs/reference-v3/func-req.md

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