docs/reference-v3/func-req.md

   1 Functions of class **afb_req**
   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  * Establishing subscription MUST be called BEFORE replying to the request.
 535  *
 536  * @param req the request
 537  * @param event the event to subscribe
 538  *
 539  * @return 0 in case of successful subscription or -1 in case of error.
 540  */
 541 int afb_req_subscribe(
 542                         afb_req_t req,
 543                         afb_event_t event);
 544 ```
 545
 546 ### afb_req_unsubscribe
 547
 548 ```C
 549 /**
 550  * Revokes the subscription established to the 'event' for the client
 551  * link identified by 'req'.
 552  * Returns 0 in case of successful subscription or -1 in case of error.
 553  *
 554  * Revoking subscription MUST be called BEFORE replying to the request.
 555  *
 556  * @param req the request
 557  * @param event the event to revoke
 558  *
 559  * @return 0 in case of successful subscription or -1 in case of error.
 560  */
 561 int afb_req_unsubscribe(
 562                         afb_req_t req,
 563                         afb_event_t event);
 564 ```
 565
 566 ## Session functions
 567
 568 ### afb_req_context
 569
 570 ```C
 571 /**
 572  * Manage the pointer stored by the binding for the client session of 'req'.
 573  *
 574  * If no previous pointer is stored or if 'replace' is not zero, a new value
 575  * is generated using the function 'create_context' called with the 'closure'.
 576  * If 'create_context' is NULL the generated value is 'closure'.
 577  *
 578  * When a value is created, the function 'free_context' is recorded and will
 579  * be called (with the created value as argument) to free the created value when
 580  * it is not more used.
 581  *
 582  * This function is atomic: it ensures that 2 threads will not race together.
 583  *
 584  * @param req the request
 585  * @param replace if not zero an existing value is replaced
 586  * @param create_context the creation function or NULL
 587  * @param free_context the destroying function or NULL
 588  * @param closure the closure to the creation function
 589  *
 590  * @return the stored value
 591  */
 592 void *afb_req_context(
 593                         afb_req_t req,
 594                         int replace,
 595                         void *(*create_context)(void *closure),
 596                         void (*free_context)(void*),
 597                         void *closure);
 598 ```
 599
 600 ### afb_req_context_get
 601
 602 ```C
 603 /**
 604  * Gets the pointer stored by the binding for the session of 'req'.
 605  * When the binding has not yet recorded a pointer, NULL is returned.
 606  *
 607  * Shortcut for: afb_req_context(req, 0, NULL, NULL, NULL)
 608  *
 609  * @param req the request
 610  *
 611  * @return the previously stored value
 612  */
 613 void *afb_req_context_get(
 614                         afb_req_t req);
 615 ```
 616
 617 ### afb_req_context_set
 618
 619 ```C
 620 /**
 621  * Stores for the binding the pointer 'context' to the session of 'req'.
 622  * The function 'free_context' will be called when the session is closed
 623  * or if binding stores an other pointer.
 624  *
 625  * Shortcut for: afb_req_context(req, 1, NULL, free_context, context)
 626  *
 627  *
 628  * @param req the request
 629  * @param context the context value to store
 630  * @param free_context the cleaning function for the stored context (can be NULL)
 631  */
 632 void afb_req_context_set(
 633                         afb_req_t req,
 634                         void *context,
 635                         void (*free_context)(void*));
 636 ```
 637
 638 ### afb_req_context_clear
 639
 640 ```C
 641 /**
 642  * Frees the pointer stored by the binding for the session of 'req'
 643  * and sets it to NULL.
 644  *
 645  * Shortcut for: afb_req_context_set(req, NULL, NULL)
 646  *
 647  * @param req the request
 648  */
 649 void afb_req_context_clear(
 650                         afb_req_t req);
 651 ```
 652
 653 ### afb_req_session_close
 654
 655 ```C
 656 /**
 657  * Closes the session associated with 'req'
 658  * and delete all associated contexts.
 659  *
 660  * @param req the request
 661  */
 662 void afb_req_session_close(
 663                         afb_req_t req);
 664 ```
 665
 666 ### afb_req_session_set_LOA
 667
 668 ```C
 669 /**
 670  * Sets the level of assurance of the session of 'req'
 671  * to 'level'. The effect of this function is subject of
 672  * security policies.
 673  *
 674  * @param req the request
 675  * @param level of assurance from 0 to 7
 676  *
 677  * @return 0 on success or -1 if failed.
 678  */
 679 int afb_req_session_set_LOA(
 680                         afb_req_t req,
 681                         unsigned level);
 682 ```
 683
 684 ## Credential/client functions
 685
 686 ### afb_req_has_permission
 687
 688 ```C
 689 /**
 690  * Check whether the 'permission' is granted or not to the client
 691  * identified by 'req'.
 692  *
 693  * @param req the request
 694  * @param permission string to check
 695  *
 696  * @return 1 if the permission is granted or 0 otherwise.
 697  */
 698 int afb_req_has_permission(
 699                         afb_req_t req,
 700                         const char *permission);
 701 ```
 702
 703 ### afb_req_get_application_id
 704
 705 ```C
 706 /**
 707  * Get the application identifier of the client application for the
 708  * request 'req'.
 709  *
 710  * Returns the application identifier or NULL when the application
 711  * can not be identified.
 712  *
 713  * The returned value if not NULL must be freed by the caller
 714  *
 715  * @param req the request
 716  *
 717  * @return the string for the application id of the client MUST BE FREED
 718  */
 719 char *afb_req_get_application_id(
 720                         afb_req_t req);
 721 ```
 722
 723 ### afb_req_get_uid
 724
 725 ```C
 726 /**
 727  * Get the user identifier (UID) of the client for the
 728  * request 'req'.
 729  *
 730  * @param req the request
 731  *
 732  * @return -1 when the application can not be identified or the unix uid.
 733  *
 734  */
 735 int afb_req_get_uid(
 736                         afb_req_t req);
 737 ```
 738
 739 ### afb_req_get_client_info
 740
 741 ```C
 742 /**
 743  * Get informations about the client of the
 744  * request 'req'.
 745  *
 746  * Returns an object with client informations:
 747  *  {
 748  *    "pid": int, "uid": int, "gid": int,
 749  *    "label": string, "id": string, "user": string,
 750  *    "uuid": string, "LOA": int
 751  *  }
 752  *
 753  * If some of this information can't be computed, the field of the return
 754  * object will not be set at all.
 755  *
 756  * @param req the request
 757  *
 758  * @return a JSON object that must be freed using @ref json_object_put
 759  */
 760 struct json_object *afb_req_get_client_info(
 761                         afb_req_t req);
 762 ```
 763
 764 ## Legacy functions
 765
 766 ### afb_req_subcall_legacy
 767
 768 ```C
 769 /**
 770  * @deprecated use @ref afb_req_subcall
 771  *
 772  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 773  * This call is made in the context of the request 'req'.
 774  * On completion, the function 'callback' is invoked with the
 775  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 776  * 'status' is 0 on success or negative when on an error reply.
 777  * 'result' is the json object of the reply, you must not call json_object_put
 778  * on the result.
 779  *
 780  * For convenience, the function calls 'json_object_put' for 'args'.
 781  * Thus, in the case where 'args' should remain available after
 782  * the function returns, the function 'json_object_get' shall be used.
 783  *
 784  * @param req the request
 785  * @param api the name of the api to call
 786  * @param verb the name of the verb to call
 787  * @param args the arguments of the call as a JSON object
 788  * @param callback the call back that will receive the reply
 789  * @param closure the closure passed back to the callback
 790  *
 791  * @see afb_req_subcall
 792  * @see afb_req_subcall_sync
 793  */
 794 void afb_req_subcall_legacy(
 795                         afb_req_t req,
 796                         const char *api,
 797                         const char *verb,
 798                         struct json_object *args,
 799                         void (*callback)(
 800                                         void *closure,
 801                                         int iserror,
 802                                         struct json_object *result,
 803                                         afb_req_t req),
 804                         void *closure);
 805 ```
 806
 807 ### afb_req_subcall_sync_legacy
 808
 809 ```C
 810 /**
 811  * @deprecated use @ref afb_req_subcall_sync
 812  *
 813  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 814  * This call is made in the context of the request 'req'.
 815  * This call is synchronous, it waits until completion of the request.
 816  * It returns 0 on success or a negative value on error answer.
 817  * The object pointed by 'result' is filled and must be released by the caller
 818  * after its use by calling 'json_object_put'.
 819  *
 820  * For convenience, the function calls 'json_object_put' for 'args'.
 821  * Thus, in the case where 'args' should remain available after
 822  * the function returns, the function 'json_object_get' shall be used.
 823  *
 824  * @param req the request
 825  * @param api the name of the api to call
 826  * @param verb the name of the verb to call
 827  * @param args the arguments of the call as a JSON object
 828  * @param result the pointer to the JSON object pointer that will receive the result
 829  *
 830  * @return 0 on success or a negative value on error answer.
 831  *
 832  * @see afb_req_subcall
 833  * @see afb_req_subcall_sync
 834  */
 835 int afb_req_subcall_sync_legacy(
 836                         afb_req_t req,
 837                         const char *api,
 838                         const char *verb,
 839                         struct json_object *args,
 840                         struct json_object **result);
 841 ```
 842