docs/legacy/afb-binding-v2-references.md

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