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  * @param req      The request
 440  * @param api      The api name of the method to call
 441  * @param verb     The verb name of the method to call
 442  * @param args     The arguments to pass to the method
 443  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags_t
 444  * @param callback The to call on completion
 445  * @param closure  The closure to pass to the callback
 446  *
 447  * The flags are any combination of the following values:
 448  *
 449  *    - afb_req_x2_subcall_catch_events = 1
 450  *
 451  *        the calling API wants to receive the events from subscription
 452  *
 453  *    - afb_req_x2_subcall_pass_events = 2
 454  *
 455  *        the original request will receive the events from subscription
 456  *
 457  *    - afb_req_x2_subcall_on_behalf = 4
 458  *
 459  *        the calling API wants to use the credentials of the original request
 460  *
 461  *    - afb_req_x2_subcall_api_session = 8
 462  *
 463  *        the calling API wants to use its session instead of the one of the
 464  *        original request
 465  *
 466  * @see also 'afb_req_subcall_sync'
 467  */
 468 void afb_req_subcall(
 469                         afb_req_t*req,
 470                         const char *api,
 471                         const char *verb,
 472                         struct json_object *args,
 473                         int flags,
 474                         void (*callback)(
 475                                         void *closure,
 476                                         struct json_object *object,
 477                                         const char *error,
 478                                         const char * info,
 479                                         afb_req_t*req),
 480                         void *closure);
 481 ```
 482
 483 ### afb_req_subcall_sync
 484
 485 ```C
 486 /**
 487  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 488  * This call is made in the context of the request 'req'.
 489  * This call is synchronous, it waits untill completion of the request.
 490  * It returns 0 on success or a negative value on error answer.
 491  *
 492  * For convenience, the function calls 'json_object_put' for 'args'.
 493  * Thus, in the case where 'args' should remain available after
 494  * the function returns, the function 'json_object_get' shall be used.
 495  *
 496  * See also:
 497  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 498  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 499  *
 500  * @param req      The request
 501  * @param api      The api name of the method to call
 502  * @param verb     The verb name of the method to call
 503  * @param args     The arguments to pass to the method
 504  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags
 505  * @param object   a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL)
 506  * @param error    a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL)
 507  * @param info     a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL)
 508  *
 509  * @return 0 in case of success or -1 in case of error
 510  */
 511 int afb_req_subcall_sync(
 512                         afb_req_t*req,
 513                         const char *api,
 514                         const char *verb,
 515                         struct json_object *args,
 516                         int flags,
 517                         struct json_object **object,
 518                         char **error,
 519                         char **info);
 520 ```
 521
 522 ## Event functions
 523
 524 ### afb_req_subscribe
 525
 526 ```C
 527 /**
 528  * Establishes for the client link identified by 'req' a subscription
 529  * to the 'event'.
 530  *
 531  * @param req the request
 532  * @param event the event to subscribe
 533  *
 534  * @return 0 in case of successful subscription or -1 in case of error.
 535  */
 536 int afb_req_subscribe(
 537                         afb_req_t*req,
 538                         afb_event_t event);
 539 ```
 540
 541 ### afb_req_unsubscribe
 542
 543 ```C
 544 /**
 545  * Revokes the subscription established to the 'event' for the client
 546  * link identified by 'req'.
 547  * Returns 0 in case of successful subscription or -1 in case of error.
 548  *
 549  * @param req the request
 550  * @param event the event to revoke
 551  *
 552  * @return 0 in case of successful subscription or -1 in case of error.
 553  */
 554 int afb_req_unsubscribe(
 555                         afb_req_t*req,
 556                         afb_event_t event);
 557 ```
 558
 559 ## Session functions
 560
 561 ### afb_req_context
 562
 563 ```C
 564 /**
 565  * Manage the pointer stored by the binding for the client session of 'req'.
 566  *
 567  * If no previous pointer is stored or if 'replace' is not zero, a new value
 568  * is generated using the function 'create_context' called with the 'closure'.
 569  * If 'create_context' is NULL the generated value is 'closure'.
 570  *
 571  * When a value is created, the function 'free_context' is recorded and will
 572  * be called (with the created value as argument) to free the created value when
 573  * it is not more used.
 574  *
 575  * This function is atomic: it ensures that 2 threads will not race together.
 576  *
 577  * @param req the request
 578  * @param replace if not zero an existing value is replaced
 579  * @param create_context the creation function or NULL
 580  * @param free_context the destroying function or NULL
 581  * @param closure the closure to the creation function
 582  *
 583  * @return the stored value
 584  */
 585 void *afb_req_context(
 586                         afb_req_t*req,
 587                         int replace,
 588                         void *(*create_context)(void *closure),
 589                         void (*free_context)(void*),
 590                         void *closure);
 591 ```
 592
 593 ### afb_req_context_get
 594
 595 ```C
 596 /**
 597  * Gets the pointer stored by the binding for the session of 'req'.
 598  * When the binding has not yet recorded a pointer, NULL is returned.
 599  *
 600  * Shortcut for: afb_req_context(req, 0, NULL, NULL, NULL)
 601  *
 602  * @param req the request
 603  *
 604  * @return the previously stored value
 605  */
 606 void *afb_req_context_get(
 607                         afb_req_t*req);
 608 ```
 609
 610 ### afb_req_context_set
 611
 612 ```C
 613 /**
 614  * Stores for the binding the pointer 'context' to the session of 'req'.
 615  * The function 'free_context' will be called when the session is closed
 616  * or if binding stores an other pointer.
 617  *
 618  * Shortcut for: afb_req_context(req, 1, NULL, free_context, context)
 619  *
 620  *
 621  * @param req the request
 622  * @param context the context value to store
 623  * @param free_context the cleaning function for the stored context (can be NULL)
 624  */
 625 void afb_req_context_set(
 626                         afb_req_t*req,
 627                         void *context,
 628                         void (*free_context)(void*));
 629 ```
 630
 631 ### afb_req_context_clear
 632
 633 ```C
 634 /**
 635  * Frees the pointer stored by the binding for the session of 'req'
 636  * and sets it to NULL.
 637  *
 638  * Shortcut for: afb_req_context_set(req, NULL, NULL)
 639  *
 640  * @param req the request
 641  */
 642 void afb_req_context_clear(
 643                         afb_req_t*req);
 644 ```
 645
 646 ### afb_req_session_close
 647
 648 ```C
 649 /**
 650  * Closes the session associated with 'req'
 651  * and delete all associated contexts.
 652  *
 653  * @param req the request
 654  */
 655 void afb_req_session_close(
 656                         afb_req_t*req);
 657 ```
 658
 659 ### afb_req_session_set_LOA
 660
 661 ```C
 662 /**
 663  * Sets the level of assurance of the session of 'req'
 664  * to 'level'. The effect of this function is subject of
 665  * security policies.
 666  *
 667  * @param req the request
 668  * @param level of assurance from 0 to 7
 669  *
 670  * @return 0 on success or -1 if failed.
 671  */
 672 int afb_req_session_set_LOA(
 673                         afb_req_t*req,
 674                         unsigned level);
 675 ```
 676
 677 ## Credential/client functions
 678
 679 ### afb_req_has_permission
 680
 681 ```C
 682 /**
 683  * Check whether the 'permission' is granted or not to the client
 684  * identified by 'req'.
 685  *
 686  * @param req the request
 687  * @param permission string to check
 688  *
 689  * @return 1 if the permission is granted or 0 otherwise.
 690  */
 691 int afb_req_has_permission(
 692                         afb_req_t*req,
 693                         const char *permission);
 694 ```
 695
 696 ### afb_req_get_application_id
 697
 698 ```C
 699 /**
 700  * Get the application identifier of the client application for the
 701  * request 'req'.
 702  *
 703  * Returns the application identifier or NULL when the application
 704  * can not be identified.
 705  *
 706  * The returned value if not NULL must be freed by the caller
 707  *
 708  * @param req the request
 709  *
 710  * @return the string for the application id of the client MUST BE FREED
 711  */
 712 char *afb_req_get_application_id(
 713                         afb_req_t*req);
 714 ```
 715
 716 ### afb_req_get_uid
 717
 718 ```C
 719 /**
 720  * Get the user identifier (UID) of the client for the
 721  * request 'req'.
 722  *
 723  * @param req the request
 724  *
 725  * @return -1 when the application can not be identified or the unix uid.
 726  *
 727  */
 728 int afb_req_get_uid(
 729                         afb_req_t*req);
 730 ```
 731
 732 ### afb_req_get_client_info
 733
 734 ```C
 735 /**
 736  * Get informations about the client of the
 737  * request 'req'.
 738  *
 739  * Returns an object with client informations:
 740  *  {
 741  *    "pid": int, "uid": int, "gid": int,
 742  *    "label": string, "id": string, "user": string,
 743  *    "uuid": string, "LOA": int
 744  *  }
 745  *
 746  * If some of this information can't be computed, the field of the return
 747  * object will not be set at all.
 748  *
 749  * @param req the request
 750  *
 751  * @return a JSON object that must be freed using @ref json_object_put
 752  */
 753 struct json_object *afb_req_get_client_info(
 754                         afb_req_t*req);
 755 ```
 756
 757 ## Legacy functions
 758
 759 ### afb_req_subcall_legacy
 760
 761 ```C
 762 /**
 763  * @deprecated use @ref afb_req_subcall
 764  *
 765  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 766  * This call is made in the context of the request 'req'.
 767  * On completion, the function 'callback' is invoked with the
 768  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 769  * 'status' is 0 on success or negative when on an error reply.
 770  * 'result' is the json object of the reply, you must not call json_object_put
 771  * on the result.
 772  *
 773  * For convenience, the function calls 'json_object_put' for 'args'.
 774  * Thus, in the case where 'args' should remain available after
 775  * the function returns, the function 'json_object_get' shall be used.
 776  *
 777  * @param req the request
 778  * @param api the name of the api to call
 779  * @param verb the name of the verb to call
 780  * @param args the arguments of the call as a JSON object
 781  * @param callback the call back that will receive the reply
 782  * @param closure the closure passed back to the callback
 783  *
 784  * @see afb_req_subcall
 785  * @see afb_req_subcall_sync
 786  */
 787 void afb_req_subcall_legacy(
 788                         afb_req_t*req,
 789                         const char *api,
 790                         const char *verb,
 791                         struct json_object *args,
 792                         void (*callback)(
 793                                         void *closure,
 794                                         int iserror,
 795                                         struct json_object *result,
 796                                         afb_req_t*req),
 797                         void *closure);
 798 ```
 799
 800 ### afb_req_subcall_sync_legacy
 801
 802 ```C
 803 /**
 804  * @deprecated use @ref afb_req_subcall_sync
 805  *
 806  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 807  * This call is made in the context of the request 'req'.
 808  * This call is synchronous, it waits until completion of the request.
 809  * It returns 0 on success or a negative value on error answer.
 810  * The object pointed by 'result' is filled and must be released by the caller
 811  * after its use by calling 'json_object_put'.
 812  *
 813  * For convenience, the function calls 'json_object_put' for 'args'.
 814  * Thus, in the case where 'args' should remain available after
 815  * the function returns, the function 'json_object_get' shall be used.
 816  *
 817  * @param req the request
 818  * @param api the name of the api to call
 819  * @param verb the name of the verb to call
 820  * @param args the arguments of the call as a JSON object
 821  * @param result the pointer to the JSON object pointer that will receive the result
 822  *
 823  * @return 0 on success or a negative value on error answer.
 824  *
 825  * @see afb_req_subcall
 826  * @see afb_req_subcall_sync
 827  */
 828 int afb_req_subcall_sync_legacy(
 829                         afb_req_t*req,
 830                         const char *api,
 831                         const char *verb,
 832                         struct json_object *args,
 833                         struct json_object **result);
 834 ```
 835