docs/3_Developer_Guides/2_Application_Framework_Binder/Annexes/7_LEGACY_Binding_v2_references.md

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