docs/3_Developer_Guides/2_Application_Framework_Binder/3_Binder_References.md

   1 ---
   2 title: Binder References
   3 ---
   4
   5 i. TYPES AND GLOBALS
   6 ======================
   7
   8 ## The global afbBindingRoot
   9
  10 The global **afbBindingRoot** of type **afb_api_t** is always implicitly
  11 defined for bindings of version 3 or upper. It records the root api of
  12 the binding.
  13
  14 When the binding has a defined **afbBindingExport**,  the root api
  15 **afbBindingRoot** is the **afb_pi_t** relative to the api created for
  16 this static description.
  17
  18 When the binding has no defined **afbBindingExport**, the root api is
  19 a virtual api representing the shared object of the binding. In that case
  20 the name of the api is the path of the shared object. Its use is restricted
  21 but allows log messages.
  22
  23 ## The global afbBindingExport
  24
  25 The global **afbBindingExport** is not mandatory.
  26
  27 If **afbBindingExport** is defined and exported, it must be of the type
  28 **const afb_binding_t** and must describe the *root* api of the binding.
  29
  30 ## The type afb_api_t
  31
  32 Bindings now can declare more than one api. The counter part is that
  33 a new handle is needed to manage apis. These handles are of the type
  34 **afb_api_t**.
  35
  36 It is defined as below.
  37
  38 ```C
  39 typedef struct afb_api_x3 afb_api_t;
  40 ```
  41
  42 ## The type afb_binding_t
  43
  44 The main structure, of type **afb_binding_t**, for describing the binding
  45 must be exported under the name **afbBindingExport**.
  46
  47 This structure is defined as below.
  48
  49 ```C
  50 typedef struct afb_binding_v3 afb_binding_t;
  51 ```
  52
  53 Where:
  54
  55 ```C
  56 /**
  57  * Description of the bindings of type version 3
  58  */
  59 struct afb_binding_v3
  60 {
  61         /** api name for the binding, can't be NULL */
  62         const char *api;
  63
  64         /** textual specification of the binding, can be NULL */
  65         const char *specification;
  66
  67         /** some info about the api, can be NULL */
  68         const char *info;
  69
  70         /** array of descriptions of verbs terminated by a NULL name, can be NULL */
  71         const struct afb_verb_v3 *verbs;
  72
  73         /** callback at load of the binding */
  74         int (*preinit)(struct afb_api_x3 *api);
  75
  76         /** callback for starting the service */
  77         int (*init)(struct afb_api_x3 *api);
  78
  79         /** callback for handling events */
  80         void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
  81
  82         /** userdata for afb_api_x3 */
  83         void *userdata;
  84
  85         /** space separated list of provided class(es) */
  86         const char *provide_class;
  87
  88         /** space separated list of required class(es) */
  89         const char *require_class;
  90
  91         /** space separated list of required API(es) */
  92         const char *require_api;
  93
  94         /** avoids concurrent requests to verbs */
  95         unsigned noconcurrency: 1;
  96 };
  97 ```
  98
  99 ## The type afb_verb_t
 100
 101 Each verb is described with a structure of type **afb_verb_t**
 102 defined below:
 103
 104 ```C
 105 typedef struct afb_verb_v3 afb_verb_t;
 106 ```
 107
 108 ```C
 109 /**
 110  * Description of one verb as provided for binding API version 3
 111  */
 112 struct afb_verb_v3
 113 {
 114         /** name of the verb, NULL only at end of the array */
 115         const char *verb;
 116
 117         /** callback function implementing the verb */
 118         void (*callback)(afb_req_t_x2 *req);
 119
 120         /** required authorization, can be NULL */
 121         const struct afb_auth *auth;
 122
 123         /** some info about the verb, can be NULL */
 124         const char *info;
 125
 126         /**< data for the verb callback */
 127         void *vcbdata;
 128
 129         /** authorization and session requirements of the verb */
 130         uint16_t session;
 131
 132         /** is the verb glob name */
 133         uint16_t glob: 1;
 134 };
 135 ```
 136
 137 The **session** flags is one of the constant defined below:
 138
 139 | Name                   | Description
 140 |:----------------------:|------------------------------------------------------
 141 | AFB_SESSION_NONE       | no flag, synonym to 0
 142 | AFB_SESSION_LOA_0      | Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE
 143 | AFB_SESSION_LOA_1      | Requires the LOA to be 1 or more
 144 | AFB_SESSION_LOA_2      | Requires the LOA to be 2 or more
 145 | AFB_SESSION_LOA_3      | Requires the LOA to be 3 or more
 146 | AFB_SESSION_CHECK      | Requires the token to be set and valid
 147 | AFB_SESSION_REFRESH    | Implies a token refresh
 148 | AFB_SESSION_CLOSE      | Implies closing the session after request processed
 149
 150 The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**.
 151
 152 The session can be closed, by binding api, using the function **afb_req_session_close**.
 153
 154 ## The types afb_auth_t and afb_auth_type_t
 155
 156 The structure **afb_auth_t** is used within verb description to
 157 set security requirements.
 158 The interpretation of the structure depends on the value of the field **type**.
 159
 160 ```C
 161 typedef struct afb_auth afb_auth_t;
 162
 163 /**
 164  * Definition of an authorization entry
 165  */
 166 struct afb_auth
 167 {
 168         /** type of entry @see afb_auth_type */
 169         enum afb_auth_type type;
 170
 171         union {
 172                 /** text when @ref type == @ref afb_auth_Permission */
 173                 const char *text;
 174
 175                 /** level of assurancy when @ref type ==  @ref afb_auth_LOA */
 176                 unsigned loa;
 177
 178                 /** first child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And, @ref afb_auth_Not } */
 179                 const struct afb_auth *first;
 180         };
 181
 182         /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */
 183         const struct afb_auth *next;
 184 };
 185
 186 ```
 187
 188 The possible values for **type** is defined here:
 189
 190 ```C
 191 typedef enum afb_auth_type afb_auth_type_t;
 192
 193 /**
 194  * Enumeration  for authority (Session/Token/Assurance) definitions.
 195  *
 196  * @see afb_auth
 197  */
 198 enum afb_auth_type
 199 {
 200         /** never authorized, no data */
 201         afb_auth_No = 0,
 202
 203         /** authorized if token valid, no data */
 204         afb_auth_Token,
 205
 206         /** authorized if LOA greater than or equal to data 'loa' */
 207         afb_auth_LOA,
 208
 209         /** authorized if permission 'text' is granted */
 210         afb_auth_Permission,
 211
 212         /** authorized if 'first' or 'next' is authorized */
 213         afb_auth_Or,
 214
 215         /** authorized if 'first' and 'next' are authorized */
 216         afb_auth_And,
 217
 218         /** authorized if 'first' is not authorized */
 219         afb_auth_Not,
 220
 221         /** always authorized, no data */
 222         afb_auth_Yes
 223 };
 224 ```
 225
 226 Example:
 227
 228 ```C
 229 static const afb_auth_t myauth[] = {
 230     { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:set" },
 231     { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:get" },
 232     { .type = afb_auth_Or, .first = &myauth[1], .next = &myauth[0] }
 233 };
 234 ```
 235
 236
 237 ## The type afb_req_subcall_flags_t
 238
 239 This is an enumeration that defines bit's positions for setting behaviour
 240 of subcalls.
 241
 242 | flag                       | value | description
 243 |----------------------------|-------|--------------
 244 | afb_req_subcall_catch_events | 1 | the calling API wants to receive the events from subscription
 245 | afb_req_subcall_pass_events  | 2 | the original request will receive the events from subscription
 246 | afb_req_subcall_on_behalf    | 4 | the calling API wants to use the credentials of the original request
 247 | afb_req_subcall_api_session  | 8 | the calling API wants to use its session instead of the one of the original request
 248
 249 ii. MACROS FOR LOGGING
 250 =================
 251
 252 The final behaviour of macros can be tuned using 2 defines that must be defined
 253 before including **<afb/afb-binding.h>**.
 254
 255 | define                                | action
 256 |---------------------------------------|--------------------
 257 | AFB_BINDING_PRAGMA_NO_VERBOSE_DATA    | show file and line, remove function and text message
 258 | AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS | show text, remove function, line and file
 259
 260 ## Logging for an api
 261
 262 The following macros must be used for logging for an **api** of type
 263 **afb_api_t**.
 264
 265 ```C
 266 AFB_API_ERROR(api,fmt,...)
 267 AFB_API_WARNING(api,fmt,...)
 268 AFB_API_NOTICE(api,fmt,...)
 269 AFB_API_INFO(api,fmt,...)
 270 AFB_API_DEBUG(api,fmt,...)
 271 ```
 272
 273 ## Logging for a request
 274
 275
 276 The following macros can be used for logging in the context
 277 of a request **req** of type **afb_req_t**:
 278
 279 ```C
 280 AFB_REQ_ERROR(req,fmt,...)
 281 AFB_REQ_WARNING(req,fmt,...)
 282 AFB_REQ_NOTICE(req,fmt,...)
 283 AFB_REQ_INFO(req,fmt,...)
 284 AFB_REQ_DEBUG(req,fmt,...)
 285 ```
 286
 287 By default, the logging macros add file, line and function
 288 indication.
 289
 290 ## Logging legacy
 291
 292 The following macros are provided for legacy.
 293
 294 ```C
 295 AFB_ERROR(fmt,...)
 296 AFB_WARNING(fmt,...)
 297 AFB_NOTICE(fmt,...)
 298 AFB_INFO(fmt,...)
 299 AFB_DEBUG(fmt,...)
 300 ```
 301
 302 iii. FUNCTIONS OF CLASS **afb_api**
 303 ============================
 304
 305 ## General functions
 306
 307 ### afb_api_name
 308
 309 ```C
 310 /**
 311  * Get the name of the 'api'.
 312  *
 313  * @param api the api whose name is to be returned
 314  *
 315  * @return the name of the api.
 316  *
 317  * The returned value must not be changed nor freed.
 318  */
 319 const char *afb_api_name(
 320                         afb_api_t api);
 321 ```
 322
 323 ### afb_api_get_userdata
 324
 325 ```C
 326 /**
 327  * Get the "userdata" pointer of the 'api'
 328  *
 329  * @param api the api whose user's data is to be returned
 330  *
 331  * @return the user's data  pointer of the api.
 332  *
 333  * @see afb_api_set_userdata
 334  */
 335 void *afb_api_get_userdata(
 336                         afb_api_t api);
 337 ```
 338
 339 ### afb_api_set_userdata
 340
 341 ```C
 342 /**
 343  * Set the "userdata" pointer of the 'api' to 'value'
 344  *
 345  * @param api   the api whose user's data is to be set
 346  * @param value the data to set
 347  *
 348  * @see afb_api_get_userdata
 349  */
 350 void afb_api_set_userdata(
 351                         afb_api_t api,
 352                         void *value);
 353 ```
 354
 355 ### afb_api_require_api
 356
 357 ```C
 358 /**
 359  * Check that it requires the API of 'name'.
 360  * If 'initialized' is not zero it requests the API to be
 361  * initialized, implying its initialization if needed.
 362  *
 363  * Calling this function is only allowed within init.
 364  *
 365  * A single request allows to require multiple apis.
 366  *
 367  * @param api the api that requires the other api by its name
 368  * @param name a space separated list of required api names
 369  * @param initialized if zero, the api is just required to exist. If not zero,
 370  * the api is required to exist and to be initialized at return of the call
 371  * (initializing it if needed and possible as a side effect of the call).
 372  *
 373  * @return 0 in case of success or -1 in case of error with errno set appropriately.
 374  */
 375 int afb_api_require_api(
 376                         afb_api_t api,
 377                         const char *name,
 378                         int initialized);
 379 ```
 380
 381
 382 ## Verbosity functions
 383
 384 ### afb_api_wants_log_level
 385
 386 ```C
 387 /**
 388  * Is the log message of 'level (as defined for syslog) required for the api?
 389  *
 390  * @param api   the api to check
 391  * @param level the level to check as defined for syslog:
 392  *
 393  *      EMERGENCY         0        System is unusable
 394  *      ALERT             1        Action must be taken immediately
 395  *      CRITICAL          2        Critical conditions
 396  *      ERROR             3        Error conditions
 397  *      WARNING           4        Warning conditions
 398  *      NOTICE            5        Normal but significant condition
 399  *      INFO              6        Informational
 400  *      DEBUG             7        Debug-level messages
 401  *
 402  * @return 0 if not required or a value not null if required
 403  *
 404  * @see syslog
 405  */
 406 int afb_api_wants_log_level(
 407                         afb_api_t api,
 408                         int level);
 409 ```
 410
 411 ### afb_api_vverbose
 412
 413 ```C
 414 /**
 415  * Send to the journal with the logging 'level' a message described
 416  * by 'fmt' applied to the va-list 'args'.
 417  *
 418  * 'file', 'line' and 'func' are indicators of code position in source files
 419  * (see macros __FILE__, __LINE__ and __func__).
 420  *
 421  * 'level' is defined by syslog standard:
 422  *
 423  *      EMERGENCY         0        System is unusable
 424  *      ALERT             1        Action must be taken immediately
 425  *      CRITICAL          2        Critical conditions
 426  *      ERROR             3        Error conditions
 427  *      WARNING           4        Warning conditions
 428  *      NOTICE            5        Normal but significant condition
 429  *      INFO              6        Informational
 430  *      DEBUG             7        Debug-level messages
 431  *
 432  * @param api the api that collects the logging message
 433  * @param level the level of the message
 434  * @param file the source file that logs the messages or NULL
 435  * @param line the line in the source file that logs the message
 436  * @param func the name of the function in the source file that logs
 437  * @param fmt the format of the message as in printf
 438  * @param args the arguments to the format string of the message as a va_list
 439  *
 440  * @see syslog
 441  * @see printf
 442  */
 443 void afb_api_vverbose(
 444                         afb_api_t api,
 445                         int level,
 446                         const char *file,
 447                         int line,
 448                         const char *func,
 449                         const char *fmt,
 450                         va_list args);
 451 ```
 452
 453 ### afb_api_verbose
 454
 455 ```C
 456 /**
 457  * Send to the journal with the log 'level' a message described
 458  * by 'fmt' and following parameters.
 459  *
 460  * 'file', 'line' and 'func' are indicators of position of the code in source files
 461  * (see macros __FILE__, __LINE__ and __func__).
 462  *
 463  * 'level' is defined by syslog standard:
 464  *      EMERGENCY         0        System is unusable
 465  *      ALERT             1        Action must be taken immediately
 466  *      CRITICAL          2        Critical conditions
 467  *      ERROR             3        Error conditions
 468  *      WARNING           4        Warning conditions
 469  *      NOTICE            5        Normal but significant condition
 470  *      INFO              6        Informational
 471  *      DEBUG             7        Debug-level messages
 472  *
 473  * @param api the api that collects the logging message
 474  * @param level the level of the message
 475  * @param file the source file that logs the messages or NULL
 476  * @param line the line in the source file that logs the message
 477  * @param func the name of the function in the source file that logs
 478  * @param fmt the format of the message as in printf
 479  * @param ... the arguments to the format string of the message
 480  *
 481  * @see syslog
 482  * @see printf
 483  */
 484 void afb_api_verbose(
 485                         afb_api_t api,
 486                         int level,
 487                         const char *file,
 488                         int line,
 489                         const char *func,
 490                         const char *fmt,
 491                         ...);
 492 ```
 493
 494 ## Data retrieval functions
 495
 496 ### afb_api_rootdir_get_fd
 497
 498 ```C
 499 /**
 500  * Get the root directory file descriptor. This file descriptor can
 501  * be used with functions 'openat', 'fstatat', ...
 502  *
 503  * CAUTION, manipulate this descriptor with care, in particular, don't close
 504  * it.
 505  *
 506  * This can be used to get the path of the root directory using:
 507  *
 508  * char buffer[MAX_PATH], proc[100];
 509  * int dirfd = afb_api_rootdir_get_fd(api);
 510  * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd);
 511  * readlink(proc, buffer, sizeof buffer);
 512  *
 513  * But note that within AGL this is the value given by the environment variable
 514  * AFM_APP_INSTALL_DIR.
 515  *
 516  * @param api the api that uses the directory file descriptor
 517  *
 518  * @return the file descriptor of the root directory.
 519  *
 520  * @see afb_api_rootdir_open_locale
 521  */
 522 int afb_api_rootdir_get_fd(
 523                         afb_api_t api);
 524 ```
 525
 526 ### afb_api_rootdir_open_locale
 527
 528 ```C
 529 /**
 530  * Opens 'filename' within the root directory with 'flags' (see function openat)
 531  * using the 'locale' definition (example: "jp,en-US") that can be NULL.
 532  *
 533  * The filename must be relative to the root of the bindings.
 534  *
 535  * The opening mode must be for read or write but not for O_CREAT.
 536  *
 537  * The definition of locales and of how files are searched can be checked
 538  * here: https://www.w3.org/TR/widgets/#folder-based-localization
 539  * and https://tools.ietf.org/html/rfc7231#section-5.3.5
 540  *
 541  * @param api the api that queries the file
 542  * @param filename the relative path to the file to open
 543  * @param flags the flags for opening as for C function 'open'
 544  * @param locale string indicating how to search content, can be NULL
 545  *
 546  * @return the file descriptor or -1 in case of error and errno is set with the
 547  * error indication.
 548  *
 549  * @see open
 550  * @see afb_api_rootdir_get_fd
 551  */
 552 int afb_api_rootdir_open_locale(
 553                         afb_api_t api,
 554                         const char *filename,
 555                         int flags,
 556                         const char *locale);
 557 ```
 558
 559 ### afb_api_settings
 560
 561 ```C
 562 /**
 563  * Settings of the api.
 564  *
 565  * Get the settings of the API. The settings are recorded
 566  * as a JSON object. The returned object should not be modified.
 567  * It MUST NOT be released using json_object_put.
 568  *
 569  * @param api the api whose settings are required
 570  *
 571  * @returns The setting object.
 572  */
 573 struct json_object *afb_api_settings(
 574                         struct afb_api_x3 *api);
 575 ```
 576
 577 ## Calls and job functions
 578
 579 ### afb_api_call
 580
 581 ```C
 582 /**
 583  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
 584  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 585  *
 586  * For convenience, the function calls 'json_object_put' for 'args'.
 587  * Thus, in the case where 'args' should remain available after
 588  * the function returns, the function 'json_object_get' shall be used.
 589  *
 590  * The 'callback' receives 5 arguments:
 591  *  1. 'closure' the user defined closure pointer 'closure',
 592  *  2. 'object'  a JSON object returned (can be NULL)
 593  *  3. 'error'   a string not NULL in case of error but NULL on success
 594  *  4. 'info'    a string handling some info (can be NULL)
 595  *  5. 'api'     the api
 596  *
 597  * NOTE: For convenience, *json_object_put* is called on 'object' after the
 598  * callback returns. So, it is wrong to call *json_object_put* in the callback.
 599  *
 600  * @param api      The api that makes the call
 601  * @param apiname  The api name of the method to call
 602  * @param verb     The verb name of the method to call
 603  * @param args     The arguments to pass to the method
 604  * @param callback The to call on completion
 605  * @param closure  The closure to pass to the callback
 606  *
 607  *
 608  * @see afb_req_subcall
 609  * @see afb_req_subcall_sync
 610  * @see afb_api_call_sync
 611  */
 612 void afb_api_call(
 613                         afb_api_t api,
 614                         const char *apiname,
 615                         const char *verb,
 616                         struct json_object *args,
 617                         void (*callback)(
 618                                         void *closure,
 619                                         struct json_object *object,
 620                                         const char *error,
 621                                         const char * info,
 622                                         afb_api_t api),
 623                         void *closure);
 624 ```
 625
 626 ### afb_api_call_sync
 627
 628 ```C
 629 /**
 630  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
 631  * 'result' will receive the response.
 632  *
 633  * For convenience, the function calls 'json_object_put' for 'args'.
 634  * Thus, in the case where 'args' should remain available after
 635  * the function returns, the function 'json_object_get' shall be used.
 636  *
 637  * @param api      The api that makes the call
 638  * @param apiname  The api name of the method to call
 639  * @param verb     The verb name of the method to call
 640  * @param args     The arguments to pass to the method
 641  * @param object   Where to store the returned object - should call json_object_put on it - can be NULL
 642  * @param error    Where to store the copied returned error - should call free on it - can be NULL
 643  * @param info     Where to store the copied returned info - should call free on it - can be NULL
 644  *
 645  * @returns 0 in case of success or a negative value in case of error.
 646  *
 647  * @see afb_req_subcall
 648  * @see afb_req_subcall_sync
 649  * @see afb_api_call
 650  */
 651 int afb_api_call_sync(
 652                         afb_api_t api,
 653                         const char *apiname,
 654                         const char *verb,
 655                         struct json_object *args,
 656                         struct json_object **object,
 657                         char **error,
 658                         char **info);
 659 ```
 660
 661 ### afb_api_queue_job
 662
 663 ```C
 664 /**
 665  * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
 666  * in this thread (later) or in an other thread.
 667  *
 668  * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group')
 669  * are executed in sequence in the order of there submission.
 670  *
 671  * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
 672  * At first, the job is called with 0 as signum and the given argument.
 673  *
 674  * The job is executed with the monitoring of its time and some signals like SIGSEGV and
 675  * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
 676  * signum being the signal number (SIGALRM when timeout expired).
 677  *
 678  * When executed, the callback function receives 2 arguments:
 679  *
 680  *  - int signum: the signal catched if any or zero at the beginning
 681  *  - void *arg: the parameter 'argument'
 682  *
 683  * A typical implementation of the job callback is:
 684  *
 685  * void my_job_cb(int signum, void *arg)
 686  * {
 687  *      struct myarg_t *myarg = arg;
 688  *      if (signum)
 689  *              AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
 690  *      else
 691  *              really_do_my_job(myarg);
 692  * }
 693  *
 694  * @param api the api that queue the job
 695  * @param callback the job as a callback function
 696  * @param argument the argument to pass to the queued job
 697  * @param group the group of the job, NULL if no group
 698  * @param timeout the timeout of execution of the job
 699  *
 700  * @return 0 in case of success or -1 in case of error with errno set appropriately.
 701  */
 702 int afb_api_queue_job(
 703                         afb_api_t api,
 704                         void (*callback)(int signum, void *arg),
 705                         void *argument,
 706                         void *group,
 707                         int timeout);
 708 ```
 709
 710 ## Event functions
 711
 712 ### afb_api_broadcast_event
 713
 714 ```C
 715 /**
 716  * Broadcasts widely the event of 'name' with the data 'object'.
 717  * 'object' can be NULL.
 718  *
 719  * For convenience, the function calls 'json_object_put' for 'object'.
 720  * Thus, in the case where 'object' should remain available after
 721  * the function returns, the function 'json_object_get' shall be used.
 722  *
 723  * Calling this function is only forbidden during preinit.
 724  *
 725  * The event sent as the name API/name where API is the name of the
 726  * api.
 727  *
 728  * @param api the api that broadcast the event
 729  * @param name the event name suffix
 730  * @param object the object that comes with the event
 731  *
 732  * @return 0 in case of success or -1 in case of error
 733  */
 734 int afb_api_broadcast_event(
 735                         afb_api_t api,
 736                         const char *name,
 737                         struct json_object *object);
 738 ```
 739
 740 ### afb_api_make_event
 741
 742 ```C
 743 /**
 744  * Creates an event of 'name' and returns it.
 745  *
 746  * Calling this function is only forbidden during preinit.
 747  *
 748  * See afb_event_is_valid to check if there is an error.
 749  *
 750  * The event created as the name API/name where API is the name of the
 751  * api.
 752  *
 753  * @param api the api that creates the event
 754  * @param name the event name suffix
 755  *
 756  * @return the created event. Use the function afb_event_is_valid to check
 757  * whether the event is valid (created) or not (error as reported by errno).
 758  *
 759  * @see afb_event_is_valid
 760  */
 761 afb_event_t afb_api_make_event(
 762                         afb_api_t api,
 763                         const char *name);
 764 ```
 765
 766 ### afb_api_event_handler_add
 767
 768 ```C
 769 /**
 770  * Add a specific event handler for the api
 771  *
 772  * The handler callback is called when an event matching the given pattern
 773  * is received (it is received if broadcasted or after subscription through
 774  * a call or a subcall).
 775  *
 776  * The handler callback receive 4 arguments:
 777  *
 778  *  - the closure given here
 779  *  - the event full name
 780  *  - the companion JSON object of the event
 781  *  - the api that subscribed the event
 782  *
 783  * @param api the api that creates the handler
 784  * @param pattern the global pattern of the event to handle
 785  * @param callback the handler callback function
 786  * @param closure the closure of the handler
 787  *
 788  * @return 0 in case of success or -1 on failure with errno set
 789  *
 790  * @see afb_api_on_event
 791  * @see afb_api_event_handler_del
 792  */
 793 int afb_api_event_handler_add(
 794                         afb_api_t api,
 795                         const char *pattern,
 796                         void (*callback)(
 797                                         void *,
 798                                         const char*,
 799                                         struct json_object*,
 800                                         afb_api_t),
 801                         void *closure);
 802 ```
 803
 804 ### afb_api_event_handler_del
 805
 806 ```C
 807 /**
 808  * Delete a specific event handler for the api
 809  *
 810  * @param api the api that the handler belongs to
 811  * @param pattern the global pattern of the handler to remove
 812  * @param closure if not NULL it will receive the closure set to the handler
 813  *
 814  * @return 0 in case of success or -1 on failure with errno set
 815  *
 816  * @see afb_api_on_event
 817  * @see afb_api_event_handler_add
 818  */
 819 int afb_api_event_handler_del(
 820                         afb_api_t api,
 821                         const char *pattern,
 822                         void **closure);
 823
 824 ```
 825
 826 ## Systemd functions
 827
 828 ### afb_api_get_event_loop
 829
 830 ```C
 831 /**
 832  * Retrieves the common systemd's event loop of AFB
 833  *
 834  * @param api the api that uses the event loop
 835  *
 836  * @return the systemd event loop if active, NULL otherwise
 837  *
 838  * @see afb_api_get_user_bus
 839  * @see afb_api_get_system_bus
 840  */
 841 struct sd_event *afb_api_get_event_loop(
 842                         afb_api_t api);
 843 ```
 844
 845 ### afb_api_get_user_bus
 846
 847 ```C
 848 /**
 849  * Retrieves the common systemd's user/session d-bus of AFB
 850  *
 851  * @param api the api that uses the user dbus
 852  *
 853  * @return the systemd user connection to dbus if active, NULL otherwise
 854  *
 855  * @see afb_api_get_event_loop
 856  * @see afb_api_get_system_bus
 857  */
 858 struct sd_bus *afb_api_get_user_bus(
 859                         afb_api_t api);
 860 ```
 861
 862 ### afb_api_get_system_bus
 863
 864 ```C
 865 /**
 866  * Retrieves the common systemd's system d-bus of AFB
 867  *
 868  * @param api the api that uses the system dbus
 869  *
 870  * @return the systemd system connection to dbus if active, NULL otherwise
 871  *
 872  * @see afb_api_get_event_loop
 873  * @see afb_api_get_user_bus
 874  */
 875 struct sd_bus *afb_api_get_system_bus(
 876                         afb_api_t api);
 877 ```
 878
 879
 880 ## Dynamic api functions
 881
 882 ### afb_api_new_api
 883
 884 ```C
 885 /**
 886  * Creates a new api of name 'apiname' briefly described by 'info' (that can
 887  * be NULL).
 888  *
 889  * When the pre-initialization function is given, it is a function that
 890  * receives 2 parameters:
 891  *
 892  *  - the closure as given in the call
 893  *  - the created api that can be initialised
 894  *
 895  * This pre-initialization function must return a negative value to abort
 896  * the creation of the api. Otherwise, it returns a non-negative value to
 897  * continue.
 898  *
 899  * @param api the api that creates the other one
 900  * @param apiname the name of the new api
 901  * @param info the brief description of the new api (can be NULL)
 902  * @param noconcurrency zero or not zero whether the new api is reentrant or not
 903  * @param preinit the pre-initialization function if any (can be NULL)
 904  * @param closure the closure for the pre-initialization preinit
 905  *
 906  * @return the created api in case of success or NULL on error
 907  *
 908  * @see afb_api_delete_api
 909  */
 910 afb_api_t afb_api_new_api(
 911                         afb_api_t api,
 912                         const char *apiname,
 913                         const char *info,
 914                         int noconcurrency,
 915                         int (*preinit)(void*, afb_api_t ),
 916                         void *closure);
 917 ```
 918
 919 ### afb_api_set_verbs_v2
 920
 921 ```C
 922 /**
 923  * @deprecated use @ref afb_api_set_verbs_v3 instead
 924  *
 925  * Set the verbs of the 'api' using description of verbs of the api v2
 926  *
 927  * @param api the api that will get the verbs
 928  * @param verbs the array of verbs to add terminated with an item with name=NULL
 929  *
 930  * @return 0 in case of success or -1 on failure with errno set
 931  *
 932  * @see afb_verb_v2
 933  * @see afb_api_add_verb
 934  * @see afb_api_set_verbs_v3
 935  */
 936 int afb_api_set_verbs_v2(
 937                         afb_api_t api,
 938                         const struct afb_verb_v2 *verbs);
 939 ```
 940
 941 ### afb_api_set_verbs_v3
 942
 943 ```C
 944 /**
 945  * Set the verbs of the 'api' using description of verbs of the api v2
 946  *
 947  * @param api the api that will get the verbs
 948  * @param verbs the array of verbs to add terminated with an item with name=NULL
 949  *
 950  * @return 0 in case of success or -1 on failure with errno set
 951  *
 952  * @see afb_verb_v3
 953  * @see afb_api_add_verb
 954  * @see afb_api_del_verb
 955  */
 956 int afb_api_set_verbs_v3(
 957                         afb_api_t api,
 958                         const struct afb_verb_v3 *verbs);
 959 ```
 960
 961 ### afb_api_add_verb
 962
 963 ```C
 964 /**
 965  * Add one verb to the dynamic set of the api
 966  *
 967  * @param api the api to change
 968  * @param verb name of the verb
 969  * @param info brief description of the verb, can be NULL
 970  * @param callback callback function implementing the verb
 971  * @param vcbdata data for the verb callback, available through req
 972  * @param auth required authorization, can be NULL
 973  * @param session authorization and session requirements of the verb
 974  * @param glob is the verb glob name
 975  *
 976  * @return 0 in case of success or -1 on failure with errno set
 977  *
 978  * @see afb_verb_v3
 979  * @see afb_api_del_verb
 980  * @see afb_api_set_verbs_v3
 981  * @see fnmatch for matching names using glob
 982  */
 983 int afb_api_add_verb(
 984                         afb_api_t api,
 985                         const char *verb,
 986                         const char *info,
 987                         void (*callback)(struct afb_req_x2 *req),
 988                         void *vcbdata,
 989                         const struct afb_auth *auth,
 990                         uint32_t session,
 991                         int glob);
 992 ```
 993
 994 ### afb_api_del_verb
 995
 996 ```C
 997 /**
 998  * Delete one verb from the dynamic set of the api
 999  *
1000  * @param api the api to change
1001  * @param verb name of the verb to delete
1002  * @param vcbdata if not NULL will receive the vcbdata of the deleted verb
1003  *
1004  * @return 0 in case of success or -1 on failure with errno set
1005  *
1006  * @see afb_api_add_verb
1007  */
1008 int afb_api_del_verb(
1009                         afb_api_t api,
1010                         const char *verb,
1011                         void **vcbdata);
1012 ```
1013
1014 ### afb_api_on_event
1015
1016 ```C
1017 /**
1018  * Set the callback 'onevent' to process events in the name of the 'api'.
1019  *
1020  * This setting can be done statically using the global variable
1021  * @ref afbBindingV3.
1022  *
1023  * This function replace any previously global event callback set.
1024  *
1025  * When an event is received, the callback 'onevent' is called with 3 parameters
1026  *
1027  *  - the api that recorded the event handler
1028  *  - the full name of the event
1029  *  - the companion JSON object of the event
1030  *
1031  * @param api the api that wants to process events
1032  * @param onevent the callback function that will process events (can be NULL
1033  *        to remove event callback)
1034  *
1035  * @return 0 in case of success or -1 on failure with errno set
1036  *
1037  * @see afbBindingV3
1038  * @see afb_binding_v3
1039  * @see afb_api_event_handler_add
1040  * @see afb_api_event_handler_del
1041  */
1042 int afb_api_on_event(
1043                         afb_api_t api,
1044                         void (*onevent)(
1045                                         afb_api_t api,
1046                                         const char *event,
1047                                         struct json_object *object));
1048 ```
1049
1050 ### afb_api_on_init
1051
1052 ```C
1053 /**
1054  * Set the callback 'oninit' to process initialization of the 'api'.
1055  *
1056  * This setting can be done statically using the global variable
1057  * @ref afbBindingV3
1058  *
1059  * This function replace any previously initialization callback set.
1060  *
1061  * This function is only valid during the pre-initialization stage.
1062  *
1063  * The callback initialization function will receive one argument: the api
1064  * to initialize.
1065  *
1066  * @param api the api that wants to process events
1067  * @param oninit the callback function that initialize the api
1068  *
1069  * @return 0 in case of success or -1 on failure with errno set
1070  *
1071  * @see afbBindingV3
1072  * @see afb_binding_v3
1073  */
1074 int afb_api_on_init(
1075                         afb_api_t api,
1076                         int (*oninit)(afb_api_t api));
1077 ```
1078
1079 ### afb_api_provide_class
1080
1081 ```C
1082 /**
1083  * Tells that the api provides a class of features. Classes are intended to
1084  * allow ordering of initializations: apis that provides a given class are
1085  * initialized before apis requiring it.
1086  *
1087  * This function is only valid during the pre-initialization stage.
1088  *
1089  * @param api  the api that provides the classes
1090  * @param name a space separated list of the names of the provided classes
1091  *
1092  * @returns 0 in case of success or a negative value in case of error.
1093  *
1094  * @see afb_api_require_class
1095  */
1096 int afb_api_provide_class(
1097                         afb_api_t api,
1098                         const char *name);
1099 ```
1100
1101 ### afb_api_require_class
1102
1103 ```C
1104 /**
1105  * Tells that the api requires a set of class features. Classes are intended to
1106  * allow ordering of initializations: apis that provides a given class are
1107  * initialized before apis requiring it.
1108  *
1109  * This function is only valid during the pre-initialization stage.
1110  *
1111  * @param api  the api that requires the classes
1112  * @param name a space separated list of the names of the required classes
1113  *
1114  * @returns 0 in case of success or a negative value in case of error.
1115  *
1116  * @see afb_api_provide_class
1117  */
1118 int afb_api_require_class(
1119                         afb_api_t api,
1120                         const char *name);
1121 ```
1122
1123 ### afb_api_seal
1124
1125 ```C
1126 /**
1127  * Seal the api. After a call to this function the api can not be modified
1128  * anymore.
1129  *
1130  * @param api the api to be sealed
1131  */
1132 void afb_api_seal(
1133                         afb_api_t api);
1134 ```
1135
1136 ### afb_api_delete_api
1137
1138 ```C
1139 /**
1140  * Delete the given api.
1141  *
1142  * It is of the responsibility of the caller to don't used the deleted api
1143  * anymore after this function returned.
1144  *
1145  * @param api the api to delete
1146  *
1147  * @returns 0 in case of success or a negative value in case of error.
1148  *
1149  * @see afb_api_new_api
1150  */
1151 int afb_api_delete_api(
1152                         afb_api_t api);
1153 ```
1154
1155 ### afb_api_add_alias
1156
1157 ```C
1158 /**
1159  * Create an aliased name 'as_name' for the api 'name'.
1160  * Calling this function is only allowed within preinit.
1161  *
1162  * @param api the api that requires the aliasing
1163  * @param name the api to alias
1164  * @param as_name the aliased name of the aliased api
1165  *
1166  * @return 0 in case of success or -1 in case of error with errno set appropriately.
1167  */
1168 int afb_api_add_alias(
1169                         afb_api_t api,
1170                         const char *name,
1171                         const char *as_name);
1172 ```
1173
1174
1175 ## Legacy functions
1176
1177 The function for legacy calls are still provided for some time because
1178 adaptation of existing code to the new call functions require a small amount
1179 of work.
1180
1181 ### afb_api_call_legacy
1182
1183 ```C
1184 /**
1185  * @deprecated try to use @ref afb_api_call instead
1186  *
1187  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
1188  * in the name of the binding.
1189  * The result of the call is delivered to the 'callback' function
1190  * with the 'callback_closure'.
1191  *
1192  * For convenience, the function calls 'json_object_put' for 'args'.
1193  * Thus, in the case where 'args' should remain available after
1194  * the function returns, the function 'json_object_get' shall be used.
1195  *
1196  * The 'callback' receives 3 arguments:
1197  *  1. 'closure' the user defined closure pointer 'closure',
1198  *  2. 'status' a status being 0 on success or negative when an error occurred,
1199  *  2. 'result' the resulting data as a JSON object.
1200  *
1201  * @param api      The api
1202  * @param apiname  The api name of the method to call
1203  * @param verb     The verb name of the method to call
1204  * @param args     The arguments to pass to the method
1205  * @param callback The to call on completion
1206  * @param closure  The closure to pass to the callback
1207  *
1208  * @see also 'afb_api_call'
1209  * @see also 'afb_api_call_sync'
1210  * @see also 'afb_api_call_sync_legacy'
1211  * @see also 'afb_req_subcall'
1212  * @see also 'afb_req_subcall_sync'
1213  */
1214 void afb_api_call_legacy(
1215                         afb_api_t api,
1216                         const char *apiname,
1217                         const char *verb,
1218                         struct json_object *args,
1219                         void (*callback)(
1220                                         void *closure,
1221                                         int status,
1222                                         struct json_object *result,
1223                                         afb_api_t api),
1224                         void *closure);
1225 ```
1226
1227 ### afb_api_call_sync_legacy
1228
1229 ```C
1230 /**
1231  * @deprecated try to use @ref afb_api_call_sync instead
1232  *
1233  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
1234  * in the name of the binding.
1235  * 'result' will receive the response.
1236  *
1237  * For convenience, the function calls 'json_object_put' for 'args'.
1238  * Thus, in the case where 'args' should remain available after
1239  * the function returns, the function 'json_object_get' shall be used.
1240  *
1241  * @param api      The api
1242  * @param apiname  The api name of the method to call
1243  * @param verb     The verb name of the method to call
1244  * @param args     The arguments to pass to the method
1245  * @param result   Where to store the result - should call json_object_put on it -
1246  *
1247  * @returns 0 in case of success or a negative value in case of error.
1248  *
1249  * @see also 'afb_api_call'
1250  * @see also 'afb_api_call_sync'
1251  * @see also 'afb_api_call_legacy'
1252  * @see also 'afb_req_subcall'
1253  * @see also 'afb_req_subcall_sync'
1254  */
1255 int afb_api_call_sync_legacy(
1256                         afb_api_t api,
1257                         const char *apiname,
1258                         const char *verb,
1259                         struct json_object *args,
1260                         struct json_object **result);
1261 ```
1262
1263 iv. FUNCTIONS OF CLASS **afb_req**
1264 ============================
1265
1266 ## General function
1267
1268 ### afb_req_is_valid
1269
1270 ```C
1271 /**
1272  * Checks whether the request 'req' is valid or not.
1273  *
1274  * @param req the request to check
1275  *
1276  * @return 0 if not valid or 1 if valid.
1277  */
1278 int afb_req_is_valid(
1279                         afb_req_t req);
1280 ```
1281
1282 ### afb_req_get_api
1283
1284 ```C
1285 /**
1286  * Retrieves the api that serves the request
1287  *
1288  * @param req the request whose serving api is queried
1289  *
1290  * @return the api serving the request
1291  */
1292 afb_api_t afb_req_get_api(
1293                         afb_req_t req);
1294 ```
1295
1296 ### afb_req_get_vcbdata
1297
1298 ```C
1299 /**
1300  * Retrieves the callback data of the verb. This callback data is set
1301  * when the verb is created.
1302  *
1303  * @param req whose verb vcbdata is queried
1304  *
1305  * @return the callback data attached to the verb description
1306  */
1307 void *afb_req_get_vcbdata(
1308                         afb_req_t req);
1309 ```
1310
1311 ### afb_req_get_called_api
1312
1313 ```C
1314 /**
1315  * Retrieve the name of the called api.
1316  *
1317  * @param req the request
1318  *
1319  * @return the name of the called api
1320  *
1321  * @see afb_api_new_api
1322  * @see afb_api_add_alias
1323  */
1324 const char *afb_req_get_called_api(
1325                         afb_req_t req);
1326 ```
1327
1328 ### afb_req_get_called_verb
1329
1330 ```C
1331 /**
1332  * Retrieve the name of the called verb
1333  *
1334  * @param req the request
1335  *
1336  * @return the name of the called verb
1337  */
1338 const char *afb_req_get_called_verb(
1339                         afb_req_t req);
1340 ```
1341
1342 ### afb_req_addref
1343
1344 ```C
1345 /**
1346  * Increments the count of references of 'req'.
1347  *
1348  * @param req the request
1349  *
1350  * @return returns the request req
1351  */
1352 afb_req_t *afb_req_addref(
1353                         afb_req_t req);
1354 ```
1355
1356 ### afb_req_unref
1357
1358 ```C
1359 /**
1360  * Decrement the count of references of 'req'.
1361  *
1362  * @param req the request
1363  */
1364 void afb_req_unref(
1365                         afb_req_t req);
1366 ```
1367
1368
1369 ## Logging functions
1370
1371 ### afb_req_wants_log_level
1372
1373 ```C
1374 /**
1375  * Is the log message of 'level (as defined for syslog) required for the
1376  * request 'req'?
1377  *
1378  * @param req the request
1379  * @param level the level to check as defined for syslog:
1380  *
1381  *      EMERGENCY         0        System is unusable
1382  *      ALERT             1        Action must be taken immediately
1383  *      CRITICAL          2        Critical conditions
1384  *      ERROR             3        Error conditions
1385  *      WARNING           4        Warning conditions
1386  *      NOTICE            5        Normal but significant condition
1387  *      INFO              6        Informational
1388  *      DEBUG             7        Debug-level messages
1389  *
1390  * @return 0 if not required or a value not null if required
1391  *
1392  * @see syslog
1393  */
1394 int afb_req_wants_log_level(
1395                         afb_req_t req,
1396                         int level);
1397 ```
1398
1399 ### afb_req_vverbose
1400
1401 ```C
1402 /**
1403  * Send associated to 'req' a message described by 'fmt' and its 'args'
1404  * to the journal for the verbosity 'level'.
1405  *
1406  * 'file', 'line' and 'func' are indicators of position of the code in source files
1407  * (see macros __FILE__, __LINE__ and __func__).
1408  *
1409  * 'level' is defined by syslog standard:
1410  *      EMERGENCY         0        System is unusable
1411  *      ALERT             1        Action must be taken immediately
1412  *      CRITICAL          2        Critical conditions
1413  *      ERROR             3        Error conditions
1414  *      WARNING           4        Warning conditions
1415  *      NOTICE            5        Normal but significant condition
1416  *      INFO              6        Informational
1417  *      DEBUG             7        Debug-level messages
1418  *
1419  * @param req the request
1420  * @param level the level of the message
1421  * @param file the source filename that emits the message or NULL
1422  * @param line the line number in the source filename that emits the message
1423  * @param func the name of the function that emits the message or NULL
1424  * @param fmt the message format as for printf
1425  * @param args the arguments to the format
1426  *
1427  * @see printf
1428  * @see afb_req_verbose
1429  */
1430 void afb_req_vverbose(
1431                         afb_req_t req,
1432                         int level, const char *file,
1433                         int line,
1434                         const char * func,
1435                         const char *fmt,
1436                         va_list args);
1437 ```
1438
1439 ### afb_req_verbose
1440
1441 ```C
1442 /**
1443  * Send associated to 'req' a message described by 'fmt' and following parameters
1444  * to the journal for the verbosity 'level'.
1445  *
1446  * 'file', 'line' and 'func' are indicators of position of the code in source files
1447  * (see macros __FILE__, __LINE__ and __func__).
1448  *
1449  * 'level' is defined by syslog standard:
1450  *      EMERGENCY         0        System is unusable
1451  *      ALERT             1        Action must be taken immediately
1452  *      CRITICAL          2        Critical conditions
1453  *      ERROR             3        Error conditions
1454  *      WARNING           4        Warning conditions
1455  *      NOTICE            5        Normal but significant condition
1456  *      INFO              6        Informational
1457  *      DEBUG             7        Debug-level messages
1458  *
1459  * @param req the request
1460  * @param level the level of the message
1461  * @param file the source filename that emits the message or NULL
1462  * @param line the line number in the source filename that emits the message
1463  * @param func the name of the function that emits the message or NULL
1464  * @param fmt the message format as for printf
1465  * @param ... the arguments of the format 'fmt'
1466  *
1467  * @see printf
1468  */
1469 void afb_req_verbose(
1470                         afb_req_t req,
1471                         int level, const char *file,
1472                         int line,
1473                         const char * func,
1474                         const char *fmt,
1475                         ...);
1476 ```
1477
1478 ## Arguments/parameters function
1479
1480 ### afb_req_get
1481
1482 ```C
1483 /**
1484  * Gets from the request 'req' the argument of 'name'.
1485  *
1486  * Returns a PLAIN structure of type 'struct afb_arg'.
1487  *
1488  * When the argument of 'name' is not found, all fields of result are set to NULL.
1489  *
1490  * When the argument of 'name' is found, the fields are filled,
1491  * in particular, the field 'result.name' is set to 'name'.
1492  *
1493  * There is a special name value: the empty string.
1494  * The argument of name "" is defined only if the request was made using
1495  * an HTTP POST of Content-Type "application/json". In that case, the
1496  * argument of name "" receives the value of the body of the HTTP request.
1497  *
1498  * @param req the request
1499  * @param name the name of the argument to get
1500  *
1501  * @return a structure describing the retrieved argument for the request
1502  *
1503  * @see afb_req_value
1504  * @see afb_req_path
1505  */
1506 struct afb_arg afb_req_get(
1507                         afb_req_t req,
1508                         const char *name);
1509 ```
1510
1511 ### afb_req_value
1512
1513 ```C
1514 /**
1515  * Gets from the request 'req' the string value of the argument of 'name'.
1516  * Returns NULL if when there is no argument of 'name'.
1517  * Returns the value of the argument of 'name' otherwise.
1518  *
1519  * Shortcut for: afb_req_get(req, name).value
1520  *
1521  * @param req the request
1522  * @param name the name of the argument's value to get
1523  *
1524  * @return the value as a string or NULL
1525  *
1526  * @see afb_req_get
1527  * @see afb_req_path
1528  */
1529 const char *afb_req_value(
1530                         afb_req_t req,
1531                         const char *name);
1532 ```
1533
1534 ### afb_req_path
1535
1536 ```C
1537 /**
1538  * Gets from the request 'req' the path for file attached to the argument of 'name'.
1539  * Returns NULL if when there is no argument of 'name' or when there is no file.
1540  * Returns the path of the argument of 'name' otherwise.
1541  *
1542  * Shortcut for: afb_req_get(req, name).path
1543  *
1544  * @param req the request
1545  * @param name the name of the argument's path to get
1546  *
1547  * @return the path if any or NULL
1548  *
1549  * @see afb_req_get
1550  * @see afb_req_value
1551  */
1552 const char *afb_req_path(
1553                         afb_req_t req,
1554                         const char *name);
1555 ```
1556
1557 ### afb_req_json
1558
1559 ```C
1560 /**
1561  * Gets from the request 'req' the json object hashing the arguments.
1562  *
1563  * The returned object must not be released using 'json_object_put'.
1564  *
1565  * @param req the request
1566  *
1567  * @return the JSON object of the query
1568  *
1569  * @see afb_req_get
1570  * @see afb_req_value
1571  * @see afb_req_path
1572  */
1573 struct json_object *afb_req_json(
1574                         afb_req_t req);
1575 ```
1576
1577 ## Reply functions
1578
1579 The functions **success** and **fail** are still supported.
1580 These functions are now implemented as the following macros:
1581
1582 ```C
1583 #define afb_req_success(r,o,i)          afb_req_reply(r,o,NULL,i)
1584 #define afb_req_success_f(r,o,...)      afb_req_reply_f(r,o,NULL,__VA_ARGS__)
1585 #define afb_req_success_v(r,o,f,v)      afb_req_reply_v(r,o,NULL,f,v)
1586 #define afb_req_fail(r,e,i)             afb_req_reply(r,NULL,e,i)
1587 #define afb_req_fail_f(r,e,...)         afb_req_reply_f(r,NULL,e,__VA_ARGS__)
1588 #define afb_req_fail_v(r,e,f,v)         afb_req_reply_v(r,NULL,e,f,v)
1589 ```
1590
1591
1592 ### afb_req_reply
1593
1594 ```C
1595 /**
1596  * Sends a reply to the request 'req'.
1597  *
1598  * The status of the reply is set to 'error' (that must be NULL on success).
1599  * Its send the object 'obj' (can be NULL) with an
1600  * informational comment 'info (can also be NULL).
1601  *
1602  * For convenience, the function calls 'json_object_put' for 'obj'.
1603  * Thus, in the case where 'obj' should remain available after
1604  * the function returns, the function 'json_object_get' shall be used.
1605  *
1606  * @param req the request
1607  * @param obj the replied object or NULL
1608  * @param error the error message if it is a reply error or NULL
1609  * @param info an informative text or NULL
1610  *
1611  * @see afb_req_reply_v
1612  * @see afb_req_reply_f
1613  */
1614 void afb_req_reply(
1615                         afb_req_t req,
1616                         struct json_object *obj,
1617                         const char *error,
1618                         const char *info);
1619 ```
1620
1621 ### afb_req_reply_v
1622
1623 ```C
1624 /**
1625  * Same as 'afb_req_reply_f' but the arguments to the format 'info'
1626  * are given as a variable argument list instance.
1627  *
1628  * For convenience, the function calls 'json_object_put' for 'obj'.
1629  * Thus, in the case where 'obj' should remain available after
1630  * the function returns, the function 'json_object_get' shall be used.
1631  *
1632  * @param req the request
1633  * @param obj the replied object or NULL
1634  * @param error the error message if it is a reply error or NULL
1635  * @param info an informative text containing a format as for vprintf
1636  * @param args the va_list of arguments to the format as for vprintf
1637  *
1638  * @see afb_req_reply
1639  * @see afb_req_reply_f
1640  * @see vprintf
1641  */
1642 void afb_req_reply_v(
1643                         afb_req_t req,
1644                         struct json_object *obj,
1645                         const char *error,
1646                         const char *info,
1647                         va_list args);
1648 ```
1649
1650 ### afb_req_reply_f
1651
1652 ```C
1653 /**
1654  * Same as 'afb_req_reply' but the 'info' is a formatting
1655  * string followed by arguments.
1656  *
1657  * For convenience, the function calls 'json_object_put' for 'obj'.
1658  * Thus, in the case where 'obj' should remain available after
1659  * the function returns, the function 'json_object_get' shall be used.
1660  *
1661  * @param req the request
1662  * @param obj the replied object or NULL
1663  * @param error the error message if it is a reply error or NULL
1664  * @param info an informative text containing a format as for printf
1665  * @param ... the arguments to the format as for printf
1666  *
1667  * @see afb_req_reply
1668  * @see afb_req_reply_v
1669  * @see printf
1670  */
1671 void afb_req_reply_f(
1672                         afb_req_t req,
1673                         struct json_object *obj,
1674                         const char *error,
1675                         const char *info,
1676                         ...);
1677 ```
1678
1679 ## Subcall functions
1680
1681
1682
1683 ### afb_req_subcall
1684
1685 ```C
1686 /**
1687  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
1688  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
1689  *
1690  * For convenience, the function calls 'json_object_put' for 'args'.
1691  * Thus, in the case where 'args' should remain available after
1692  * the function returns, the function 'json_object_get' shall be used.
1693  *
1694  * The 'callback' receives 5 arguments:
1695  *  1. 'closure' the user defined closure pointer 'closure',
1696  *  2. 'object'  a JSON object returned (can be NULL)
1697  *  3. 'error'   a string not NULL in case of error
1698  *  4. 'info'    a string handling some info (can be NULL)
1699  *  5. 'req'     the req
1700  *
1701  * NOTE: For convenience, *json_object_put* is called on 'object' after the
1702  * callback returns. So, it is wrong to call *json_object_put* in the callback.
1703  *
1704  * @param req      The request
1705  * @param api      The api name of the method to call
1706  * @param verb     The verb name of the method to call
1707  * @param args     The arguments to pass to the method
1708  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags_t
1709  * @param callback The to call on completion
1710  * @param closure  The closure to pass to the callback
1711  *
1712  * The flags are any combination of the following values:
1713  *
1714  *    - afb_req_x2_subcall_catch_events = 1
1715  *
1716  *        the calling API wants to receive the events from subscription
1717  *
1718  *    - afb_req_x2_subcall_pass_events = 2
1719  *
1720  *        the original request will receive the events from subscription
1721  *
1722  *    - afb_req_x2_subcall_on_behalf = 4
1723  *
1724  *        the calling API wants to use the credentials of the original request
1725  *
1726  *    - afb_req_x2_subcall_api_session = 8
1727  *
1728  *        the calling API wants to use its session instead of the one of the
1729  *        original request
1730  *
1731  * @see also 'afb_req_subcall_sync'
1732  */
1733 void afb_req_subcall(
1734                         afb_req_t req,
1735                         const char *api,
1736                         const char *verb,
1737                         struct json_object *args,
1738                         int flags,
1739                         void (*callback)(
1740                                         void *closure,
1741                                         struct json_object *object,
1742                                         const char *error,
1743                                         const char * info,
1744                                         afb_req_t req),
1745                         void *closure);
1746 ```
1747
1748 ### afb_req_subcall_sync
1749
1750 ```C
1751 /**
1752  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
1753  * This call is made in the context of the request 'req'.
1754  * This call is synchronous, it waits untill completion of the request.
1755  * It returns 0 on success or a negative value on error answer.
1756  *
1757  * For convenience, the function calls 'json_object_put' for 'args'.
1758  * Thus, in the case where 'args' should remain available after
1759  * the function returns, the function 'json_object_get' shall be used.
1760  *
1761  * See also:
1762  *  - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
1763  *  - 'afb_req_subcall' that doesn't keep request alive automatically.
1764  *
1765  * @param req      The request
1766  * @param api      The api name of the method to call
1767  * @param verb     The verb name of the method to call
1768  * @param args     The arguments to pass to the method
1769  * @param flags    The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags
1770  * @param object   a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL)
1771  * @param error    a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL)
1772  * @param info     a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL)
1773  *
1774  * @return 0 in case of success or -1 in case of error
1775  */
1776 int afb_req_subcall_sync(
1777                         afb_req_t req,
1778                         const char *api,
1779                         const char *verb,
1780                         struct json_object *args,
1781                         int flags,
1782                         struct json_object **object,
1783                         char **error,
1784                         char **info);
1785 ```
1786
1787 ## Event functions
1788
1789 ### afb_req_subscribe
1790
1791 ```C
1792 /**
1793  * Establishes for the client link identified by 'req' a subscription
1794  * to the 'event'.
1795  *
1796  * Establishing subscription MUST be called BEFORE replying to the request.
1797  *
1798  * @param req the request
1799  * @param event the event to subscribe
1800  *
1801  * @return 0 in case of successful subscription or -1 in case of error.
1802  */
1803 int afb_req_subscribe(
1804                         afb_req_t req,
1805                         afb_event_t event);
1806 ```
1807
1808 ### afb_req_unsubscribe
1809
1810 ```C
1811 /**
1812  * Revokes the subscription established to the 'event' for the client
1813  * link identified by 'req'.
1814  * Returns 0 in case of successful subscription or -1 in case of error.
1815  *
1816  * Revoking subscription MUST be called BEFORE replying to the request.
1817  *
1818  * @param req the request
1819  * @param event the event to revoke
1820  *
1821  * @return 0 in case of successful subscription or -1 in case of error.
1822  */
1823 int afb_req_unsubscribe(
1824                         afb_req_t req,
1825                         afb_event_t event);
1826 ```
1827
1828 ## Session functions
1829
1830 ### afb_req_context
1831
1832 ```C
1833 /**
1834  * Manage the pointer stored by the binding for the client session of 'req'.
1835  *
1836  * If no previous pointer is stored or if 'replace' is not zero, a new value
1837  * is generated using the function 'create_context' called with the 'closure'.
1838  * If 'create_context' is NULL the generated value is 'closure'.
1839  *
1840  * When a value is created, the function 'free_context' is recorded and will
1841  * be called (with the created value as argument) to free the created value when
1842  * it is not more used.
1843  *
1844  * This function is atomic: it ensures that 2 threads will not race together.
1845  *
1846  * @param req the request
1847  * @param replace if not zero an existing value is replaced
1848  * @param create_context the creation function or NULL
1849  * @param free_context the destroying function or NULL
1850  * @param closure the closure to the creation function
1851  *
1852  * @return the stored value
1853  */
1854 void *afb_req_context(
1855                         afb_req_t req,
1856                         int replace,
1857                         void *(*create_context)(void *closure),
1858                         void (*free_context)(void*),
1859                         void *closure);
1860 ```
1861
1862 ### afb_req_context_get
1863
1864 ```C
1865 /**
1866  * Gets the pointer stored by the binding for the session of 'req'.
1867  * When the binding has not yet recorded a pointer, NULL is returned.
1868  *
1869  * Shortcut for: afb_req_context(req, 0, NULL, NULL, NULL)
1870  *
1871  * @param req the request
1872  *
1873  * @return the previously stored value
1874  */
1875 void *afb_req_context_get(
1876                         afb_req_t req);
1877 ```
1878
1879 ### afb_req_context_set
1880
1881 ```C
1882 /**
1883  * Stores for the binding the pointer 'context' to the session of 'req'.
1884  * The function 'free_context' will be called when the session is closed
1885  * or if binding stores an other pointer.
1886  *
1887  * Shortcut for: afb_req_context(req, 1, NULL, free_context, context)
1888  *
1889  *
1890  * @param req the request
1891  * @param context the context value to store
1892  * @param free_context the cleaning function for the stored context (can be NULL)
1893  */
1894 void afb_req_context_set(
1895                         afb_req_t req,
1896                         void *context,
1897                         void (*free_context)(void*));
1898 ```
1899
1900 ### afb_req_context_clear
1901
1902 ```C
1903 /**
1904  * Frees the pointer stored by the binding for the session of 'req'
1905  * and sets it to NULL.
1906  *
1907  * Shortcut for: afb_req_context_set(req, NULL, NULL)
1908  *
1909  * @param req the request
1910  */
1911 void afb_req_context_clear(
1912                         afb_req_t req);
1913 ```
1914
1915 ### afb_req_session_close
1916
1917 ```C
1918 /**
1919  * Closes the session associated with 'req'
1920  * and delete all associated contexts.
1921  *
1922  * @param req the request
1923  */
1924 void afb_req_session_close(
1925                         afb_req_t req);
1926 ```
1927
1928 ### afb_req_session_set_LOA
1929
1930 ```C
1931 /**
1932  * Sets the level of assurance of the session of 'req'
1933  * to 'level'. The effect of this function is subject of
1934  * security policies.
1935  *
1936  * @param req the request
1937  * @param level of assurance from 0 to 7
1938  *
1939  * @return 0 on success or -1 if failed.
1940  */
1941 int afb_req_session_set_LOA(
1942                         afb_req_t req,
1943                         unsigned level);
1944 ```
1945
1946 ## Credential/client functions
1947
1948 ### afb_req_has_permission
1949
1950 ```C
1951 /**
1952  * Check whether the 'permission' is granted or not to the client
1953  * identified by 'req'.
1954  *
1955  * @param req the request
1956  * @param permission string to check
1957  *
1958  * @return 1 if the permission is granted or 0 otherwise.
1959  */
1960 int afb_req_has_permission(
1961                         afb_req_t req,
1962                         const char *permission);
1963 ```
1964
1965 ### afb_req_get_application_id
1966
1967 ```C
1968 /**
1969  * Get the application identifier of the client application for the
1970  * request 'req'.
1971  *
1972  * Returns the application identifier or NULL when the application
1973  * can not be identified.
1974  *
1975  * The returned value if not NULL must be freed by the caller
1976  *
1977  * @param req the request
1978  *
1979  * @return the string for the application id of the client MUST BE FREED
1980  */
1981 char *afb_req_get_application_id(
1982                         afb_req_t req);
1983 ```
1984
1985 ### afb_req_get_uid
1986
1987 ```C
1988 /**
1989  * Get the user identifier (UID) of the client for the
1990  * request 'req'.
1991  *
1992  * @param req the request
1993  *
1994  * @return -1 when the application can not be identified or the unix uid.
1995  *
1996  */
1997 int afb_req_get_uid(
1998                         afb_req_t req);
1999 ```
2000
2001 ### afb_req_get_client_info
2002
2003 ```C
2004 /**
2005  * Get informations about the client of the
2006  * request 'req'.
2007  *
2008  * Returns an object with client informations:
2009  *  {
2010  *    "pid": int, "uid": int, "gid": int,
2011  *    "label": string, "id": string, "user": string,
2012  *    "uuid": string, "LOA": int
2013  *  }
2014  *
2015  * If some of this information can't be computed, the field of the return
2016  * object will not be set at all.
2017  *
2018  * @param req the request
2019  *
2020  * @return a JSON object that must be freed using @ref json_object_put
2021  */
2022 struct json_object *afb_req_get_client_info(
2023                         afb_req_t req);
2024 ```
2025
2026 ## Legacy functions
2027
2028 ### afb_req_subcall_legacy
2029
2030 ```C
2031 /**
2032  * @deprecated use @ref afb_req_subcall
2033  *
2034  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
2035  * This call is made in the context of the request 'req'.
2036  * On completion, the function 'callback' is invoked with the
2037  * 'closure' given at call and two other parameters: 'iserror' and 'result'.
2038  * 'status' is 0 on success or negative when on an error reply.
2039  * 'result' is the json object of the reply, you must not call json_object_put
2040  * on the result.
2041  *
2042  * For convenience, the function calls 'json_object_put' for 'args'.
2043  * Thus, in the case where 'args' should remain available after
2044  * the function returns, the function 'json_object_get' shall be used.
2045  *
2046  * @param req the request
2047  * @param api the name of the api to call
2048  * @param verb the name of the verb to call
2049  * @param args the arguments of the call as a JSON object
2050  * @param callback the call back that will receive the reply
2051  * @param closure the closure passed back to the callback
2052  *
2053  * @see afb_req_subcall
2054  * @see afb_req_subcall_sync
2055  */
2056 void afb_req_subcall_legacy(
2057                         afb_req_t req,
2058                         const char *api,
2059                         const char *verb,
2060                         struct json_object *args,
2061                         void (*callback)(
2062                                         void *closure,
2063                                         int iserror,
2064                                         struct json_object *result,
2065                                         afb_req_t req),
2066                         void *closure);
2067 ```
2068
2069 ### afb_req_subcall_sync_legacy
2070
2071 ```C
2072 /**
2073  * @deprecated use @ref afb_req_subcall_sync
2074  *
2075  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
2076  * This call is made in the context of the request 'req'.
2077  * This call is synchronous, it waits until completion of the request.
2078  * It returns 0 on success or a negative value on error answer.
2079  * The object pointed by 'result' is filled and must be released by the caller
2080  * after its use by calling 'json_object_put'.
2081  *
2082  * For convenience, the function calls 'json_object_put' for 'args'.
2083  * Thus, in the case where 'args' should remain available after
2084  * the function returns, the function 'json_object_get' shall be used.
2085  *
2086  * @param req the request
2087  * @param api the name of the api to call
2088  * @param verb the name of the verb to call
2089  * @param args the arguments of the call as a JSON object
2090  * @param result the pointer to the JSON object pointer that will receive the result
2091  *
2092  * @return 0 on success or a negative value on error answer.
2093  *
2094  * @see afb_req_subcall
2095  * @see afb_req_subcall_sync
2096  */
2097 int afb_req_subcall_sync_legacy(
2098                         afb_req_t req,
2099                         const char *api,
2100                         const char *verb,
2101                         struct json_object *args,
2102                         struct json_object **result);
2103 ```
2104
2105 v. FUNCTIONS OF CLASS **afb_event**
2106 ==============================
2107
2108 ## General functions
2109
2110 ### afb_event_is_valid
2111
2112 ```C
2113 /**
2114  * Checks whether the 'event' is valid or not.
2115  *
2116  * @param event the event to check
2117  *
2118  * @return 0 if not valid or 1 if valid.
2119  */
2120 int afb_event_is_valid(
2121                         afb_event_t event);
2122 ```
2123
2124 ### afb_event_name
2125
2126 ```C
2127 /**
2128  * Gets the name associated to 'event'.
2129  *
2130  * @param event the event whose name is requested
2131  *
2132  * @return the name of the event
2133  *
2134  * The returned name can be used until call to 'afb_event_unref'.
2135  * It shouldn't be freed.
2136  */
2137 const char *afb_event_name(
2138                         afb_event_t event);
2139 ```
2140
2141 ### afb_event_unref
2142
2143 ```C
2144 /**
2145  * Decrease the count of references to 'event'.
2146  * Call this function when the evenid is no more used.
2147  * It destroys the event_x2 when the reference count falls to zero.
2148  *
2149  * @param event the event
2150  */
2151 void afb_event_unref(
2152                         afb_event_t event);
2153 ```
2154
2155 ### afb_event_addref
2156
2157 ```C
2158 /**
2159  * Increases the count of references to 'event'
2160  *
2161  * @param event the event
2162  *
2163  * @return the event
2164  */
2165 afb_event_t *afb_event_addref(
2166                         afb_event_t event);
2167 ```
2168
2169 ## Pushing functions
2170
2171 ### afb_event_broadcast
2172
2173 ```C
2174 /**
2175  * Broadcasts widely an event of 'event' with the data 'object'.
2176  * 'object' can be NULL.
2177  *
2178  * For convenience, the function calls 'json_object_put' for 'object'.
2179  * Thus, in the case where 'object' should remain available after
2180  * the function returns, the function 'json_object_get' shall be used.
2181  *
2182  * @param event the event to broadcast
2183  * @param object the companion object to associate to the broadcasted event (can be NULL)
2184  *
2185  * @return 0 in case of success or -1 in case of error
2186  */
2187 int afb_event_broadcast(
2188                         afb_event_t event,
2189                         struct json_object *object);
2190 ```
2191
2192 ### afb_event_push
2193
2194 ```C
2195 /**
2196  * Pushes an event of 'event' with the data 'object' to its observers.
2197  * 'object' can be NULL.
2198  *
2199  * For convenience, the function calls 'json_object_put' for 'object'.
2200  * Thus, in the case where 'object' should remain available after
2201  * the function returns, the function 'json_object_get' shall be used.
2202  *
2203  * @param event the event to push
2204  * @param object the companion object to associate to the pushed event (can be NULL)
2205  *
2206  * @Return
2207  *   *  1 if at least one client listen for the event
2208  *   *  0 if no more client listen for the event
2209  *   * -1 in case of error (the event can't be delivered)
2210  */
2211 int afb_event_push(
2212                         afb_event_t event,
2213                         struct json_object *object);
2214 ```
2215
2216 vi. FUNCTIONS OF CLASS **afb_daemon**
2217 ============================
2218
2219 All the functions of the class **afb_daemon** use the default api.
2220 This are internally aliased to the corresponding function of class afb_api_t.
2221
2222 ```C
2223 /**
2224  * Retrieves the common systemd's event loop of AFB
2225  */
2226 struct sd_event *afb_daemon_get_event_loop();
2227
2228 /**
2229  * Retrieves the common systemd's user/session d-bus of AFB
2230  */
2231 struct sd_bus *afb_daemon_get_user_bus();
2232
2233 /**
2234  * Retrieves the common systemd's system d-bus of AFB
2235  */
2236 struct sd_bus *afb_daemon_get_system_bus();
2237
2238 /**
2239  * Broadcasts widely the event of 'name' with the data 'object'.
2240  * 'object' can be NULL.
2241  *
2242  * For convenience, the function calls 'json_object_put' for 'object'.
2243  * Thus, in the case where 'object' should remain available after
2244  * the function returns, the function 'json_object_get' shall be used.
2245  *
2246  * Calling this function is only forbidden during preinit.
2247  *
2248  * Returns the count of clients that received the event.
2249  */
2250 int afb_daemon_broadcast_event(
2251                         const char *name,
2252                         struct json_object *object);
2253
2254 /**
2255  * Creates an event of 'name' and returns it.
2256  *
2257  * Calling this function is only forbidden during preinit.
2258  *
2259  * See afb_event_is_valid to check if there is an error.
2260  */
2261 afb_event_t afb_daemon_make_event(
2262                         const char *name);
2263
2264 /**
2265  * @deprecated use bindings version 3
2266  *
2267  * Send a message described by 'fmt' and following parameters
2268  * to the journal for the verbosity 'level'.
2269  *
2270  * 'file', 'line' and 'func' are indicators of position of the code in source files
2271  * (see macros __FILE__, __LINE__ and __func__).
2272  *
2273  * 'level' is defined by syslog standard:
2274  *      EMERGENCY         0        System is unusable
2275  *      ALERT             1        Action must be taken immediately
2276  *      CRITICAL          2        Critical conditions
2277  *      ERROR             3        Error conditions
2278  *      WARNING           4        Warning conditions
2279  *      NOTICE            5        Normal but significant condition
2280  *      INFO              6        Informational
2281  *      DEBUG             7        Debug-level messages
2282  */
2283 void afb_daemon_verbose(
2284                         int level,
2285                         const char *file,
2286                         int line,
2287                         const char * func,
2288                         const char *fmt,
2289                         ...);
2290
2291 /**
2292  * @deprecated use bindings version 3
2293  *
2294  * Get the root directory file descriptor. This file descriptor can
2295  * be used with functions 'openat', 'fstatat', ...
2296  *
2297  * Returns the file descriptor or -1 in case of error.
2298  */
2299 int afb_daemon_rootdir_get_fd();
2300
2301 /**
2302  * Opens 'filename' within the root directory with 'flags' (see function openat)
2303  * using the 'locale' definition (example: "jp,en-US") that can be NULL.
2304  *
2305  * Returns the file descriptor or -1 in case of error.
2306  */
2307 int afb_daemon_rootdir_open_locale(
2308                         const char *filename,
2309                         int flags,
2310                         const char *locale);
2311
2312 /**
2313  * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
2314  * in this thread (later) or in an other thread.
2315  * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group')
2316  * are executed in sequence in the order of there submission.
2317  * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
2318  * At first, the job is called with 0 as signum and the given argument.
2319  * The job is executed with the monitoring of its time and some signals like SIGSEGV and
2320  * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
2321  * signum being the signal number (SIGALRM when timeout expired).
2322  *
2323  * Returns 0 in case of success or -1 in case of error.
2324  */
2325 int afb_daemon_queue_job(
2326                         void (*callback)(int signum, void *arg),
2327                         void *argument,
2328                         void *group,
2329                         int timeout);
2330
2331 /**
2332  * Tells that it requires the API of "name" to exist
2333  * and if 'initialized' is not null to be initialized.
2334  * Calling this function is only allowed within init.
2335  *
2336  * Returns 0 in case of success or -1 in case of error.
2337  */
2338 int afb_daemon_require_api(
2339                         const char *name,
2340                         int initialized);
2341
2342 /**
2343  * Create an aliased name 'as_name' for the api 'name'.
2344  * Calling this function is only allowed within preinit.
2345  *
2346  * Returns 0 in case of success or -1 in case of error.
2347  */
2348 int afb_daemon_add_alias(const char *name, const char *as_name);
2349
2350 /**
2351  * Creates a new api of name 'api' with brief 'info'.
2352  *
2353  * Returns 0 in case of success or -1 in case of error.
2354  */
2355 int afb_daemon_new_api(
2356                         const char *api,
2357                         const char *info,
2358                         int noconcurrency,
2359                         int (*preinit)(void*, struct afb_api_x3 *),
2360                         void *closure);
2361 ```
2362
2363 vii. FUNCTIONS OF CLASS **afb_service**
2364 ==============================
2365
2366 All the functions of the class **afb_service** use the default api.
2367
2368 All these function are deprecated, try to use functions of class **afb_api** instead.
2369
2370 ## afb_service_call
2371
2372 ```C
2373 /**
2374  * @deprecated try to use @ref afb_api_call instead
2375  *
2376  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
2377  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
2378  *
2379  * For convenience, the function calls 'json_object_put' for 'args'.
2380  * Thus, in the case where 'args' should remain available after
2381  * the function returns, the function 'json_object_get' shall be used.
2382  *
2383  * The 'callback' receives 5 arguments:
2384  *  1. 'closure' the user defined closure pointer 'closure',
2385  *  2. 'object'  a JSON object returned (can be NULL)
2386  *  3. 'error'   a string not NULL in case of error but NULL on success
2387  *  4. 'info'    a string handling some info (can be NULL)
2388  *  5. 'api'     the api
2389  *
2390  * @param api      The api name of the method to call
2391  * @param verb     The verb name of the method to call
2392  * @param args     The arguments to pass to the method
2393  * @param callback The to call on completion
2394  * @param closure  The closure to pass to the callback
2395  *
2396  *
2397  * @see afb_req_subcall
2398  * @see afb_req_subcall_sync
2399  * @see afb_api_call_sync
2400  */
2401 void afb_service_call(
2402                         const char *api,
2403                         const char *verb,
2404                         struct json_object *args,
2405                         void (*callback)(
2406                                         void *closure,
2407                                         struct json_object *object,
2408                                         const char *error,
2409                                         const char * info,
2410                                         afb_api_t api),
2411                         void *closure);
2412 ```
2413
2414 ## afb_service_call_sync
2415
2416 ```C
2417 /**
2418  * @deprecated try to use @ref afb_api_call_sync instead
2419  *
2420  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
2421  * 'result' will receive the response.
2422  *
2423  * For convenience, the function calls 'json_object_put' for 'args'.
2424  * Thus, in the case where 'args' should remain available after
2425  * the function returns, the function 'json_object_get' shall be used.
2426  *
2427  * @param api      The api name of the method to call
2428  * @param verb     The verb name of the method to call
2429  * @param args     The arguments to pass to the method
2430  * @param object   Where to store the returned object - should call json_object_put on it - can be NULL
2431  * @param error    Where to store the copied returned error - should call free on it - can be NULL
2432  * @param info     Where to store the copied returned info - should call free on it - can be NULL
2433  *
2434  * @returns 0 in case of success or a negative value in case of error.
2435  *
2436  * @see afb_req_subcall
2437  * @see afb_req_subcall_sync
2438  * @see afb_api_call
2439  */
2440 int afb_service_call_sync(
2441                         const char *api,
2442                         const char *verb,
2443                         struct json_object *args,
2444                         struct json_object **object,
2445                         char **error,
2446                         char **info);
2447 ```
2448
2449 ## afb_service_call_legacy
2450
2451 ```C
2452 /**
2453  * @deprecated try to use @ref afb_api_call instead
2454  *
2455  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb'
2456  * in the name of the binding.
2457  * The result of the call is delivered to the 'callback' function with
2458  * the 'callback_closure'.
2459  *
2460  * For convenience, the function calls 'json_object_put' for 'args'.
2461  * Thus, in the case where 'args' should remain available after
2462  * the function returns, the function 'json_object_get' shall be used.
2463  *
2464  * The 'callback' receives 3 arguments:
2465  *  1. 'closure' the user defined closure pointer 'closure',
2466  *  2. 'status' a status being 0 on success or negative when an error occurred,
2467  *  2. 'result' the resulting data as a JSON object.
2468  *
2469  * @param api      The api name of the method to call
2470  * @param verb     The verb name of the method to call
2471  * @param args     The arguments to pass to the method
2472  * @param callback The to call on completion
2473  * @param closure  The closure to pass to the callback
2474  *
2475  * @see also 'afb_api_call'
2476  * @see also 'afb_api_call_sync'
2477  * @see also 'afb_api_call_sync_legacy'
2478  * @see also 'afb_req_subcall'
2479  * @see also 'afb_req_subcall_sync'
2480  */
2481 void afb_service_call_legacy(
2482                         const char *api,
2483                         const char *verb,
2484                         struct json_object *args,
2485                         void (*callback)(
2486                                         void *closure,
2487                                         int status,
2488                                         struct json_object *result,
2489                                         afb_api_t api),
2490                         void *closure);
2491 ```
2492
2493 ## afb_service_call_sync_legacy
2494
2495 ```C
2496 /**
2497  * @deprecated try to use @ref afb_api_call_sync instead
2498  *
2499  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the
2500  * name of the binding. 'result' will receive the response.
2501  *
2502  * For convenience, the function calls 'json_object_put' for 'args'.
2503  * Thus, in the case where 'args' should remain available after
2504  * the function returns, the function 'json_object_get' shall be used.
2505  *
2506  * @param api      The api name of the method to call
2507  * @param verb     The verb name of the method to call
2508  * @param args     The arguments to pass to the method
2509  * @param result   Where to store the result - should call json_object_put on it -
2510  *
2511  * @returns 0 in case of success or a negative value in case of error.
2512  *
2513  * @see also 'afb_api_call'
2514  * @see also 'afb_api_call_sync'
2515  * @see also 'afb_api_call_legacy'
2516  * @see also 'afb_req_subcall'
2517  * @see also 'afb_req_subcall_sync'
2518  */
2519 int afb_service_call_sync_legacy(
2520                         const char *api,
2521                         const char *verb,
2522                         struct json_object *args,
2523                         struct json_object **result);
2524 ```