docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/7_LEGACY Binding V2 references.md

   1 ---
   2 edit_link: ''
   3 title: LEGACY Binding V2 references
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/app-framework-binder/plain/docs/legacy/afb-binding-v2-references.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 [LEGACY] Binding Reference
  11 ==========================
  12
  13 # Structure for declaring binding
  14 ---------------------------------
  15
  16 ### struct afb_binding_v2
  17
  18 The main structure, of type **afb_binding_v2**, for describing the binding
  19 must be exported under the name **afbBindingV2**.
  20
  21 This structure is defined as below.
  22
  23 ```C
  24 /*
  25  * Description of the bindings of type version 2
  26  */
  27 struct afb_binding_v2
  28 {
  29         const char *api;                        /* api name for the binding */
  30         const char *specification;              /* textual openAPIv3 specification of the binding */
  31         const char *info;                       /* some info about the api, can be NULL */
  32         const struct afb_verb_v2 *verbs;        /* array of descriptions of verbs terminated by a NULL name */
  33         int (*preinit)();                       /* callback at load of the binding */
  34         int (*init)();                          /* callback for starting the service */
  35         void (*onevent)(const char *event, struct json_object *object); /* callback for handling events */
  36         unsigned noconcurrency: 1;              /* avoids concurrent requests to verbs */
  37 };
  38 ```
  39
  40 ### struct afb_verb_v2
  41
  42 Each verb is described with a structure of type **afb_verb_v2**
  43 defined below:
  44
  45 ```C
  46 /*
  47  * Description of one verb of the API provided by the binding
  48  * This enumeration is valid for bindings of type version 2
  49  */
  50 struct afb_verb_v2
  51 {
  52         const char *verb;                       /* name of the verb */
  53         void (*callback)(struct afb_req req);   /* callback function implementing the verb */
  54         const struct afb_auth *auth;            /* required authorization */
  55         const char *info;                       /* some info about the verb, can be NULL */
  56         uint32_t session;                       /* authorization and session requirements of the verb */
  57 };
  58 ```
  59
  60 The **session** flags is one of the constant defined below:
  61
  62 - AFB_SESSION_NONE : no flag, synonym to 0
  63 - AFB_SESSION_LOA_0 : Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE
  64 - AFB_SESSION_LOA_1 : Requires the LOA to be 1 or more
  65 - AFB_SESSION_LOA_2 : Requires the LOA to be 2 or more
  66 - AFB_SESSION_LOA_3 : Requires the LOA to be 3 or more
  67 - AFB_SESSION_CHECK : Requires the token to be set and valid
  68 - AFB_SESSION_REFRESH : Implies a token refresh
  69 - AFB_SESSION_CLOSE : Implies cloing the session
  70
  71 The LOA (Level Of Assurance) is set, by binding, using the function **afb_req_session_set_LOA**.
  72
  73 ### struct afb_auth and enum afb_auth_type
  74
  75 The structure **afb_auth** is used within verb description to
  76 set security requirements.
  77 The interpretation of the structure depends on the value of the field **type**.
  78
  79 ```C
  80 struct afb_auth
  81 {
  82         const enum afb_auth_type type;
  83         union {
  84                 const char *text;
  85                 const unsigned loa;
  86                 const struct afb_auth *first;
  87         };
  88         const struct afb_auth *next;
  89 };
  90 ```
  91
  92 The possible values for **type** is defined here:
  93
  94 ```C
  95 /*
  96  * Enum for Session/Token/Assurance middleware.
  97  */
  98 enum afb_auth_type
  99 {
 100         afb_auth_No = 0,        /** never authorized, no data */
 101         afb_auth_Token,         /** authorized if token valid, no data */
 102         afb_auth_LOA,           /** authorized if LOA greater than data 'loa' */
 103         afb_auth_Permission,    /** authorized if permission 'text' is granted */
 104         afb_auth_Or,            /** authorized if 'first' or 'next' is authorized */
 105         afb_auth_And,           /** authorized if 'first' and 'next' are authorized */
 106         afb_auth_Not,           /** authorized if 'first' is not authorized */
 107         afb_auth_Yes            /** always authorized, no data */
 108 };
 109 ```
 110
 111 Example:
 112
 113 ```C
 114 static const struct afb_auth _afb_auths_v2_monitor[] = {
 115     { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:set" },
 116     { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:get" },
 117     { .type = afb_auth_Or, .first = &_afb_auths_v2_monitor[1], .next = &_afb_auths_v2_monitor[0] }
 118 };
 119 ```
 120
 121 ## Functions of class afb_daemon
 122
 123 The 3 following functions are linked to libsystemd.
 124 They allow use of **sd_event** features and access
 125 to **sd_bus** features.
 126
 127 ```C
 128 /*
 129  * Retrieves the common systemd's event loop of AFB
 130  */
 131 struct sd_event *afb_daemon_get_event_loop();
 132
 133 /*
 134  * Retrieves the common systemd's user/session d-bus of AFB
 135  */
 136 struct sd_bus *afb_daemon_get_user_bus();
 137
 138 /*
 139  * Retrieves the common systemd's system d-bus of AFB
 140  */
 141 struct sd_bus *afb_daemon_get_system_bus();
 142 ```
 143
 144 The 2 following functions are linked to event management.
 145 Broadcasting an event send it to any possible listener.
 146
 147 ```C
 148 /*
 149  * Broadcasts widely the event of 'name' with the data 'object'.
 150  * 'object' can be NULL.
 151  *
 152  * For convenience, the function calls 'json_object_put' for 'object'.
 153  * Thus, in the case where 'object' should remain available after
 154  * the function returns, the function 'json_object_get' shall be used.
 155  *
 156  * Calling this function is only forbidden during preinit.
 157  *
 158  * Returns the count of clients that received the event.
 159  */
 160 int afb_daemon_broadcast_event(const char *name, struct json_object *object);
 161
 162 /*
 163  * Creates an event of 'name' and returns it.
 164  *
 165  * Calling this function is only forbidden during preinit.
 166  *
 167  * See afb_event_is_valid to check if there is an error.
 168  */
 169 struct afb_event afb_daemon_make_event(const char *name);
 170 ```
 171
 172 The following function is used by logging macros and should normally
 173 not be used.
 174 Instead, you should use the macros:
 175
 176 - **AFB\_ERROR**
 177 - **AFB\_WARNING**
 178 - **AFB\_NOTICE**
 179 - **AFB\_INFO**
 180 - **AFB\_DEBUG**
 181
 182 ```C
 183 /*
 184  * Send a message described by 'fmt' and following parameters
 185  * to the journal for the verbosity 'level'.
 186  *
 187  * 'file', 'line' and 'func' are indicators of position of the code in source files
 188  * (see macros __FILE__, __LINE__ and __func__).
 189  *
 190  * 'level' is defined by syslog standard:
 191  *      EMERGENCY         0        System is unusable
 192  *      ALERT             1        Action must be taken immediately
 193  *      CRITICAL          2        Critical conditions
 194  *      ERROR             3        Error conditions
 195  *      WARNING           4        Warning conditions
 196  *      NOTICE            5        Normal but significant condition
 197  *      INFO              6        Informational
 198  *      DEBUG             7        Debug-level messages
 199  */
 200 void afb_daemon_verbose(int level, const char *file, int line, const char * func, const char *fmt, ...);
 201 ```
 202
 203 The 2 following functions MUST be used to access data of the bindings.
 204
 205 ```C
 206 /*
 207  * Get the root directory file descriptor. This file descriptor can
 208  * be used with functions 'openat', 'fstatat', ...
 209  */
 210 int afb_daemon_rootdir_get_fd();
 211
 212 /*
 213  * Opens 'filename' within the root directory with 'flags' (see function openat)
 214  * using the 'locale' definition (example: "jp,en-US") that can be NULL.
 215  * Returns the file descriptor or -1 in case of error.
 216  */
 217 int afb_daemon_rootdir_open_locale(const char *filename, int flags, const char *locale);
 218 ```
 219
 220 The following function is used to queue jobs.
 221
 222 ```C
 223 /*
 224  * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
 225  * in this thread (later) or in an other thread.
 226  * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group')
 227  * are executed in sequence in the order of there submission.
 228  * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
 229  * At first, the job is called with 0 as signum and the given argument.
 230  * The job is executed with the monitoring of its time and some signals like SIGSEGV and
 231  * SIGFPE. When a such signal is catched, the job is terminated and re-executed but with
 232  * signum being the signal number (SIGALRM when timeout expired).
 233  *
 234  * Returns 0 in case of success or -1 in case of error.
 235  */
 236 int afb_daemon_queue_job(void (*callback)(int signum, void *arg), void *argument, void *group, int timeout)
 237 ```
 238
 239 The following function must be used when a binding depends on other
 240 bindings at its initialization.
 241
 242 ```C
 243 /*
 244  * Tells that it requires the API of "name" to exist
 245  * and if 'initialized' is not null to be initialized.
 246  * Calling this function is only allowed within init.
 247  * Returns 0 in case of success or -1 in case of error.
 248  */
 249 int afb_daemon_require_api(const char *name, int initialized)
 250 ```
 251
 252 This function allows to give a different name to the binding.
 253 It can be called during pre-init.
 254
 255 ```C
 256 /*
 257  * Set the name of the API to 'name'.
 258  * Calling this function is only allowed within preinit.
 259  * Returns 0 in case of success or -1 in case of error.
 260  */
 261 int afb_daemon_rename_api(const char *name);
 262 ```
 263
 264 ## Functions of class afb_service
 265
 266 The following functions allow services to call verbs of other
 267 bindings for themselves.
 268
 269 ```C
 270 /**
 271  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 272  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 273  *
 274  * For convenience, the function calls 'json_object_put' for 'args'.
 275  * Thus, in the case where 'args' should remain available after
 276  * the function returns, the function 'json_object_get' shall be used.
 277  *
 278  * The 'callback' receives 3 arguments:
 279  *  1. 'closure' the user defined closure pointer 'callback_closure',
 280  *  2. 'status' a status being 0 on success or negative when an error occurred,
 281  *  2. 'result' the resulting data as a JSON object.
 282  *
 283  * @param api      The api name of the method to call
 284  * @param verb     The verb name of the method to call
 285  * @param args     The arguments to pass to the method
 286  * @param callback The to call on completion
 287  * @param callback_closure The closure to pass to the callback
 288  *
 289  * @see also 'afb_req_subcall'
 290  */
 291 void afb_service_call(
 292     const char *api,
 293     const char *verb,
 294     struct json_object *args,
 295     void (*callback)(void*closure, int status, struct json_object *result),
 296     void *callback_closure);
 297
 298 /**
 299  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 300  * 'result' will receive the response.
 301  *
 302  * For convenience, the function calls 'json_object_put' for 'args'.
 303  * Thus, in the case where 'args' should remain available after
 304  * the function returns, the function 'json_object_get' shall be used.
 305  *
 306  * @param api      The api name of the method to call
 307  * @param verb     The verb name of the method to call
 308  * @param args     The arguments to pass to the method
 309  * @param result   Where to store the result - should call json_object_put on it -
 310  *
 311  * @returns 0 in case of success or a negative value in case of error.
 312  *
 313  * @see also 'afb_req_subcall'
 314  */
 315 int afb_service_call_sync(
 316     const char *api,
 317     const char *verb,
 318     struct json_object *args,
 319     struct json_object **result);
 320 ```
 321
 322 ## Functions of class afb_event
 323
 324 This function checks whether the event is valid.
 325 It must be used when creating events.
 326
 327 ```C
 328 /*
 329  * Checks wether the 'event' is valid or not.
 330  *
 331  * Returns 0 if not valid or 1 if valid.
 332  */
 333 int afb_event_is_valid(struct afb_event event);
 334 ```
 335
 336 The two following functions are used to broadcast or push
 337 event with its data.
 338
 339 ```C
 340 /*
 341  * Broadcasts widely the 'event' with the data 'object'.
 342  * 'object' can be NULL.
 343  *
 344  * For convenience, the function calls 'json_object_put' for 'object'.
 345  * Thus, in the case where 'object' should remain available after
 346  * the function returns, the function 'json_object_get' shall be used.
 347  *
 348  * Returns the count of clients that received the event.
 349  */
 350 int afb_event_broadcast(struct afb_event event, struct json_object *object);
 351
 352 /*
 353  * Pushes the 'event' with the data 'object' to its observers.
 354  * 'object' can be NULL.
 355  *
 356  * For convenience, the function calls 'json_object_put' for 'object'.
 357  * Thus, in the case where 'object' should remain available after
 358  * the function returns, the function 'json_object_get' shall be used.
 359  *
 360  * Returns the count of clients that received the event.
 361  */
 362 int afb_event_push(struct afb_event event, struct json_object *object);
 363 ```
 364
 365 The following function destroys the event.
 366
 367 ```C
 368 /*
 369  * Drops the data associated to the 'event'
 370  * After calling this function, the event
 371  * MUST NOT BE USED ANYMORE.
 372  */
 373 void afb_event_drop(struct afb_event event);
 374 ```
 375
 376 This function allows to retrieve the exact name of the event.
 377
 378 ```C
 379 /*
 380  * Gets the name associated to the 'event'.
 381  */
 382 const char *afb_event_name(struct afb_event event);
 383 ```
 384
 385 ## Functions of class afb_req
 386
 387 This function checks the validity of the **req**.
 388
 389 ```C
 390 /*
 391  * Checks wether the request 'req' is valid or not.
 392  *
 393  * Returns 0 if not valid or 1 if valid.
 394  */
 395 int afb_req_is_valid(struct afb_req req);
 396 ```
 397
 398 The following functions retrieves parameters of the request.
 399
 400 ```C
 401 /*
 402  * Gets from the request 'req' the argument of 'name'.
 403  * Returns a PLAIN structure of type 'struct afb_arg'.
 404  * When the argument of 'name' is not found, all fields of result are set to NULL.
 405  * When the argument of 'name' is found, the fields are filled,
 406  * in particular, the field 'result.name' is set to 'name'.
 407  *
 408  * There is a special name value: the empty string.
 409  * The argument of name "" is defined only if the request was made using
 410  * an HTTP POST of Content-Type "application/json". In that case, the
 411  * argument of name "" receives the value of the body of the HTTP request.
 412  */
 413 struct afb_arg afb_req_get(struct afb_req req, const char *name);
 414
 415 /*
 416  * Gets from the request 'req' the string value of the argument of 'name'.
 417  * Returns NULL if when there is no argument of 'name'.
 418  * Returns the value of the argument of 'name' otherwise.
 419  *
 420  * Shortcut for: afb_req_get(req, name).value
 421  */
 422 const char *afb_req_value(struct afb_req req, const char *name);
 423
 424 /*
 425  * Gets from the request 'req' the path for file attached to the argument of 'name'.
 426  * Returns NULL if when there is no argument of 'name' or when there is no file.
 427  * Returns the path of the argument of 'name' otherwise.
 428  *
 429  * Shortcut for: afb_req_get(req, name).path
 430  */
 431 const char *afb_req_path(struct afb_req req, const char *name);
 432
 433 /*
 434  * Gets from the request 'req' the json object hashing the arguments.
 435  * The returned object must not be released using 'json_object_put'.
 436  */
 437 struct json_object *afb_req_json(struct afb_req req);
 438 ```
 439
 440 The following functions emit the reply to the request.
 441
 442 ```C
 443 /*
 444  * Sends a reply of kind success to the request 'req'.
 445  * The status of the reply is automatically set to "success".
 446  * Its send the object 'obj' (can be NULL) with an
 447  * informational comment 'info (can also be NULL).
 448  *
 449  * For convenience, the function calls 'json_object_put' for 'obj'.
 450  * Thus, in the case where 'obj' should remain available after
 451  * the function returns, the function 'json_object_get' shall be used.
 452  */
 453 void afb_req_success(struct afb_req req, struct json_object *obj, const char *info);
 454
 455 /*
 456  * Same as 'afb_req_success' but the 'info' is a formatting
 457  * string followed by arguments.
 458  *
 459  * For convenience, the function calls 'json_object_put' for 'obj'.
 460  * Thus, in the case where 'obj' should remain available after
 461  * the function returns, the function 'json_object_get' shall be used.
 462  */
 463 void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...);
 464
 465 /*
 466  * Same as 'afb_req_success_f' but the arguments to the format 'info'
 467  * are given as a variable argument list instance.
 468  *
 469  * For convenience, the function calls 'json_object_put' for 'obj'.
 470  * Thus, in the case where 'obj' should remain available after
 471  * the function returns, the function 'json_object_get' shall be used.
 472  */
 473 void afb_req_success_v(struct afb_req req, struct json_object *obj, const char *info, va_list args);
 474
 475 /*
 476  * Sends a reply of kind failure to the request 'req'.
 477  * The status of the reply is set to 'status' and an
 478  * informational comment 'info' (can also be NULL) can be added.
 479  *
 480  * Note that calling afb_req_fail("success", info) is equivalent
 481  * to call afb_req_success(NULL, info). Thus even if possible it
 482  * is strongly recommended to NEVER use "success" for status.
 483  */
 484 void afb_req_fail(struct afb_req req, const char *status, const char *info);
 485
 486 /*
 487  * Same as 'afb_req_fail' but the 'info' is a formatting
 488  * string followed by arguments.
 489  */
 490 void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...);
 491
 492 /*
 493  * Same as 'afb_req_fail_f' but the arguments to the format 'info'
 494  * are given as a variable argument list instance.
 495  */
 496 void afb_req_fail_v(struct afb_req req, const char *status, const char *info, va_list args);
 497 ```
 498
 499 The following functions handle the session data.
 500
 501 ```C
 502 /*
 503  * Gets the pointer stored by the binding for the session of 'req'.
 504  * When the binding has not yet recorded a pointer, NULL is returned.
 505  */
 506 void *afb_req_context_get(struct afb_req req);
 507
 508 /*
 509  * Stores for the binding the pointer 'context' to the session of 'req'.
 510  * The function 'free_context' will be called when the session is closed
 511  * or if binding stores an other pointer.
 512  */
 513 void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*));
 514
 515 /*
 516  * Gets the pointer stored by the binding for the session of 'req'.
 517  * If the stored pointer is NULL, indicating that no pointer was
 518  * already stored, afb_req_context creates a new context by calling
 519  * the function 'create_context' and stores it with the freeing function
 520  * 'free_context'.
 521  */
 522 void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*));
 523
 524 /*
 525  * Frees the pointer stored by the binding for the session of 'req'
 526  * and sets it to NULL.
 527  *
 528  * Shortcut for: afb_req_context_set(req, NULL, NULL)
 529  */
 530 void afb_req_context_clear(struct afb_req req);
 531
 532 /*
 533  * Closes the session associated with 'req'
 534  * and delete all associated contexts.
 535  */
 536 void afb_req_session_close(struct afb_req req);
 537
 538 /*
 539  * Sets the level of assurance of the session of 'req'
 540  * to 'level'. The effect of this function is subject of
 541  * security policies.
 542  * Returns 1 on success or 0 if failed.
 543  */
 544 int afb_req_session_set_LOA(struct afb_req req, unsigned level);
 545 ```
 546
 547 The 4 following functions must be used for asynchronous handling requests.
 548
 549 ```C
 550 /*
 551  * Adds one to the count of references of 'req'.
 552  * This function MUST be called by asynchronous implementations
 553  * of verbs if no reply was sent before returning.
 554  */
 555 void afb_req_addref(struct afb_req req);
 556
 557 /*
 558  * Substracts one to the count of references of 'req'.
 559  * This function MUST be called by asynchronous implementations
 560  * of verbs after sending the asynchronous reply.
 561  */
 562 void afb_req_unref(struct afb_req req);
 563
 564 /*
 565  * Stores 'req' on heap for asynchronous use.
 566  * Returns a handler to the stored 'req' or NULL on memory depletion.
 567  * The count of reference to 'req' is incremented on success
 568  * (see afb_req_addref).
 569  */
 570 struct afb_stored_req *afb_req_store(struct afb_req req);
 571
 572 /*
 573  * Retrieves the afb_req stored at 'sreq'.
 574  * Returns the stored request.
 575  * The count of reference is UNCHANGED, thus, the
 576  * function 'afb_req_unref' should be called on the result
 577  * after that the asynchronous reply if sent.
 578  */
 579 struct afb_req afb_req_unstore(struct afb_stored_req *sreq);
 580 ```
 581
 582 The two following functions are used to associate client with events
 583 (subscription).
 584
 585 ```C
 586 /*
 587  * Establishes for the client link identified by 'req' a subscription
 588  * to the 'event'.
 589  * Returns 0 in case of successful subscription or -1 in case of error.
 590  */
 591 int afb_req_subscribe(struct afb_req req, struct afb_event event);
 592
 593 /*
 594  * Revokes the subscription established to the 'event' for the client
 595  * link identified by 'req'.
 596  * Returns 0 in case of successful subscription or -1 in case of error.
 597  */
 598 int afb_req_unsubscribe(struct afb_req req, struct afb_event event);
 599 ```
 600
 601 The following functions must be used to make request in the name of the
 602 client (with its permissions).
 603
 604 ```C
 605 /*
 606  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 607  * This call is made in the context of the request 'req'.
 608  * On completion, the function 'callback' is invoked with the
 609  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
 610  * 'status' is 0 on success or negative when on an error reply.
 611  * 'result' is the json object of the reply, you must not call json_object_put
 612  * on the result.
 613  *
 614  * For convenience, the function calls 'json_object_put' for 'args'.
 615  * Thus, in the case where 'args' should remain available after
 616  * the function returns, the function 'json_object_get' shall be used.
 617  *
 618  * See also:
 619  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 620  *  - 'afb_req_subcall_sync' the synchronous version
 621  */
 622 void afb_req_subcall(
 623                 struct afb_req req,
 624                 const char *api,
 625                 const char *verb,
 626                 struct json_object *args,
 627                 void (*callback)(void *closure, int status, struct json_object *result),
 628                 void *closure);
 629
 630 /*
 631  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 632  * This call is made in the context of the request 'req'.
 633  * On completion, the function 'callback' is invoked with the
 634  * original request 'req', the 'closure' given at call and two
 635  * other parameters: 'iserror' and 'result'.
 636  * 'status' is 0 on success or negative when on an error reply.
 637  * 'result' is the json object of the reply, you must not call json_object_put
 638  * on the result.
 639  *
 640  * For convenience, the function calls 'json_object_put' for 'args'.
 641  * Thus, in the case where 'args' should remain available after
 642  * the function returns, the function 'json_object_get' shall be used.
 643  *
 644  * See also:
 645  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 646  *  - 'afb_req_subcall_sync' the synchronous version
 647  */
 648 static inline void afb_req_subcall_req(struct afb_req req, const char *api, const char *verb, struct json_object *args, void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req req), void *closure)
 649 {
 650         req.itf->subcall_req(req.closure, api, verb, args, callback, closure);
 651 }
 652
 653 /*
 654  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
 655  * This call is made in the context of the request 'req'.
 656  * This call is synchronous, it waits until completion of the request.
 657  * It returns 0 on success or a negative value on error answer.
 658  * The object pointed by 'result' is filled and must be released by the caller
 659  * after its use by calling 'json_object_put'.
 660  *
 661  * For convenience, the function calls 'json_object_put' for 'args'.
 662  * Thus, in the case where 'args' should remain available after
 663  * the function returns, the function 'json_object_get' shall be used.
 664  *
 665  * See also:
 666  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
 667  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
 668  */
 669 int afb_req_subcall_sync(
 670                 struct afb_req req,
 671                 const char *api,
 672                 const char *verb,
 673                 struct json_object *args,
 674                 struct json_object **result);
 675 ```
 676
 677 The following function is used by logging macros and should normally
 678 not be used.
 679 Instead, you should use the macros:
 680
 681 - **AFB_REQ_ERROR**
 682 - **AFB_REQ_WARNING**
 683 - **AFB_REQ_NOTICE**
 684 - **AFB_REQ_INFO**
 685 - **AFB_REQ_DEBUG**
 686
 687 ```C
 688 /*
 689  * Send associated to 'req' a message described by 'fmt' and following parameters
 690  * to the journal for the verbosity 'level'.
 691  *
 692  * 'file', 'line' and 'func' are indicators of position of the code in source files
 693  * (see macros __FILE__, __LINE__ and __func__).
 694  *
 695  * 'level' is defined by syslog standard:
 696  *      EMERGENCY         0        System is unusable
 697  *      ALERT             1        Action must be taken immediately
 698  *      CRITICAL          2        Critical conditions
 699  *      ERROR             3        Error conditions
 700  *      WARNING           4        Warning conditions
 701  *      NOTICE            5        Normal but significant condition
 702  *      INFO              6        Informational
 703  *      DEBUG             7        Debug-level messages
 704  */
 705 void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...);
 706 ```
 707
 708 The functions below allow a binding involved in the platform security
 709 to explicitly check a permission of a client or to get the calling
 710 application identity.
 711
 712 ```C
 713 /*
 714  * Check whether the 'permission' is granted or not to the client
 715  * identified by 'req'.
 716  *
 717  * Returns 1 if the permission is granted or 0 otherwise.
 718  */
 719 int afb_req_has_permission(struct afb_req req, const char *permission);
 720
 721 /*
 722  * Get the application identifier of the client application for the
 723  * request 'req'.
 724  *
 725  * Returns the application identifier or NULL when the application
 726  * can not be identified.
 727  *
 728  * The returned value if not NULL must be freed by the caller
 729  */
 730 char *afb_req_get_application_id(struct afb_req req);
 731
 732 /*
 733  * Get the user identifier (UID) of the client application for the
 734  * request 'req'.
 735  *
 736  * Returns -1 when the application can not be identified.
 737  */
 738 int afb_req_get_uid(struct afb_req req);
 739 ```
 740
 741 ## Logging macros
 742
 743 The following macros must be used for logging:
 744
 745 ```C
 746 AFB_ERROR(fmt,...)
 747 AFB_WARNING(fmt,...)
 748 AFB_NOTICE(fmt,...)
 749 AFB_INFO(fmt,...)
 750 AFB_DEBUG(fmt,...)
 751 ```
 752
 753 The following macros can be used for logging in the context
 754 of a request **req** of type **afb_req**:
 755
 756 ```C
 757 AFB_REQ_ERROR(req,fmt,...)
 758 AFB_REQ_WARNING(req,fmt,...)
 759 AFB_REQ_NOTICE(req,fmt,...)
 760 AFB_REQ_INFO(req,fmt,...)
 761 AFB_REQ_DEBUG(req,fmt,...)
 762 ```
 763
 764 By default, the logging macros add file, line and function
 765 indication.