docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/4_Functions_of_class_afb_req.md

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