docs/reference-v3/func-api.md

   1 Functions of class **afb_api**
   2 ============================
   3
   4 ## General functions
   5
   6 ### afb_api_name
   7
   8 ```C
   9 /**
  10  * Get the name of the 'api'.
  11  *
  12  * @param api the api whose name is to be returned
  13  *
  14  * @return the name of the api.
  15  *
  16  * The returned value must not be changed nor freed.
  17  */
  18 const char *afb_api_name(
  19                         afb_api_t api);
  20 ```
  21
  22 ### afb_api_get_userdata
  23
  24 ```C
  25 /**
  26  * Get the "userdata" pointer of the 'api'
  27  *
  28  * @param api the api whose user's data is to be returned
  29  *
  30  * @return the user's data  pointer of the api.
  31  *
  32  * @see afb_api_set_userdata
  33  */
  34 void *afb_api_get_userdata(
  35                         afb_api_t api);
  36 ```
  37
  38 ### afb_api_set_userdata
  39
  40 ```C
  41 /**
  42  * Set the "userdata" pointer of the 'api' to 'value'
  43  *
  44  * @param api   the api whose user's data is to be set
  45  * @param value the data to set
  46  *
  47  * @see afb_api_get_userdata
  48  */
  49 void afb_api_set_userdata(
  50                         afb_api_t api,
  51                         void *value);
  52 ```
  53
  54 ### afb_api_require_api
  55
  56 ```C
  57 /**
  58  * Check that it requires the API of 'name'.
  59  * If 'initialized' is not zero it requests the API to be
  60  * initialized, implying its initialization if needed.
  61  *
  62  * Calling this function is only allowed within init.
  63  *
  64  * A single request allows to require multiple apis.
  65  *
  66  * @param api the api that requires the other api by its name
  67  * @param name a space separated list of required api names
  68  * @param initialized if zero, the api is just required to exist. If not zero,
  69  * the api is required to exist and to be initialized at return of the call
  70  * (initializing it if needed and possible as a side effect of the call).
  71  *
  72  * @return 0 in case of success or -1 in case of error with errno set appropriately.
  73  */
  74 int afb_api_require_api(
  75                         afb_api_t api,
  76                         const char *name,
  77                         int initialized);
  78 ```
  79
  80
  81 ## Verbosity functions
  82
  83 ### afb_api_wants_log_level
  84
  85 ```C
  86 /**
  87  * Is the log message of 'level (as defined for syslog) required for the api?
  88  *
  89  * @param api   the api to check
  90  * @param level the level to check as defined for syslog:
  91  *
  92  *      EMERGENCY         0        System is unusable
  93  *      ALERT             1        Action must be taken immediately
  94  *      CRITICAL          2        Critical conditions
  95  *      ERROR             3        Error conditions
  96  *      WARNING           4        Warning conditions
  97  *      NOTICE            5        Normal but significant condition
  98  *      INFO              6        Informational
  99  *      DEBUG             7        Debug-level messages
 100  *
 101  * @return 0 if not required or a value not null if required
 102  *
 103  * @see syslog
 104  */
 105 int afb_api_wants_log_level(
 106                         afb_api_t api,
 107                         int level);
 108 ```
 109
 110 ### afb_api_vverbose
 111
 112 ```C
 113 /**
 114  * Send to the journal with the logging 'level' a message described
 115  * by 'fmt' applied to the va-list 'args'.
 116  *
 117  * 'file', 'line' and 'func' are indicators of code position in source files
 118  * (see macros __FILE__, __LINE__ and __func__).
 119  *
 120  * 'level' is defined by syslog standard:
 121  *
 122  *      EMERGENCY         0        System is unusable
 123  *      ALERT             1        Action must be taken immediately
 124  *      CRITICAL          2        Critical conditions
 125  *      ERROR             3        Error conditions
 126  *      WARNING           4        Warning conditions
 127  *      NOTICE            5        Normal but significant condition
 128  *      INFO              6        Informational
 129  *      DEBUG             7        Debug-level messages
 130  *
 131  * @param api the api that collects the logging message
 132  * @param level the level of the message
 133  * @param file the source file that logs the messages or NULL
 134  * @param line the line in the source file that logs the message
 135  * @param func the name of the function in the source file that logs
 136  * @param fmt the format of the message as in printf
 137  * @param args the arguments to the format string of the message as a va_list
 138  *
 139  * @see syslog
 140  * @see printf
 141  */
 142 void afb_api_vverbose(
 143                         afb_api_t api,
 144                         int level,
 145                         const char *file,
 146                         int line,
 147                         const char *func,
 148                         const char *fmt,
 149                         va_list args);
 150 ```
 151
 152 ### afb_api_verbose
 153
 154 ```C
 155 /**
 156  * Send to the journal with the log 'level' a message described
 157  * by 'fmt' and following parameters.
 158  *
 159  * 'file', 'line' and 'func' are indicators of position of the code in source files
 160  * (see macros __FILE__, __LINE__ and __func__).
 161  *
 162  * 'level' is defined by syslog standard:
 163  *      EMERGENCY         0        System is unusable
 164  *      ALERT             1        Action must be taken immediately
 165  *      CRITICAL          2        Critical conditions
 166  *      ERROR             3        Error conditions
 167  *      WARNING           4        Warning conditions
 168  *      NOTICE            5        Normal but significant condition
 169  *      INFO              6        Informational
 170  *      DEBUG             7        Debug-level messages
 171  *
 172  * @param api the api that collects the logging message
 173  * @param level the level of the message
 174  * @param file the source file that logs the messages or NULL
 175  * @param line the line in the source file that logs the message
 176  * @param func the name of the function in the source file that logs
 177  * @param fmt the format of the message as in printf
 178  * @param ... the arguments to the format string of the message
 179  *
 180  * @see syslog
 181  * @see printf
 182  */
 183 void afb_api_verbose(
 184                         afb_api_t api,
 185                         int level,
 186                         const char *file,
 187                         int line,
 188                         const char *func,
 189                         const char *fmt,
 190                         ...);
 191 ```
 192
 193 ## Data retrieval functions
 194
 195 ### afb_api_rootdir_get_fd
 196
 197 ```C
 198 /**
 199  * Get the root directory file descriptor. This file descriptor can
 200  * be used with functions 'openat', 'fstatat', ...
 201  *
 202  * CAUTION, manipulate this descriptor with care, in particular, don't close
 203  * it.
 204  *
 205  * This can be used to get the path of the root directory using:
 206  *
 207  * char buffer[MAX_PATH], proc[100];
 208  * int dirfd = afb_api_rootdir_get_fd(api);
 209  * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd);
 210  * readlink(proc, buffer, sizeof buffer);
 211  *
 212  * But note that within AGL this is the value given by the environment variable
 213  * AFM_APP_INSTALL_DIR.
 214  *
 215  * @param api the api that uses the directory file descriptor
 216  *
 217  * @return the file descriptor of the root directory.
 218  *
 219  * @see afb_api_rootdir_open_locale
 220  */
 221 int afb_api_rootdir_get_fd(
 222                         afb_api_t api);
 223 ```
 224
 225 ### afb_api_rootdir_open_locale
 226
 227 ```C
 228 /**
 229  * Opens 'filename' within the root directory with 'flags' (see function openat)
 230  * using the 'locale' definition (example: "jp,en-US") that can be NULL.
 231  *
 232  * The filename must be relative to the root of the bindings.
 233  *
 234  * The opening mode must be for read or write but not for O_CREAT.
 235  *
 236  * The definition of locales and of how files are searched can be checked
 237  * here: https://www.w3.org/TR/widgets/#folder-based-localization
 238  * and https://tools.ietf.org/html/rfc7231#section-5.3.5
 239  *
 240  * @param api the api that queries the file
 241  * @param filename the relative path to the file to open
 242  * @param flags the flags for opening as for C function 'open'
 243  * @param locale string indicating how to search content, can be NULL
 244  *
 245  * @return the file descriptor or -1 in case of error and errno is set with the
 246  * error indication.
 247  *
 248  * @see open
 249  * @see afb_api_rootdir_get_fd
 250  */
 251 int afb_api_rootdir_open_locale(
 252                         afb_api_t api,
 253                         const char *filename,
 254                         int flags,
 255                         const char *locale);
 256 ```
 257
 258 ### afb_api_settings
 259
 260 ```C
 261 /**
 262  * Settings of the api.
 263  *
 264  * Get the settings of the API. The settings are recorded
 265  * as a JSON object. The returned object should not be modified.
 266  * It MUST NOT be released using json_object_put.
 267  *
 268  * @param api the api whose settings are required
 269  *
 270  * @returns The setting object.
 271  */
 272 struct json_object *afb_api_settings(
 273                         struct afb_api_x3 *api);
 274 ```
 275
 276 ## Calls and job functions
 277
 278 ### afb_api_call
 279
 280 ```C
 281 /**
 282  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
 283  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 284  *
 285  * For convenience, the function calls 'json_object_put' for 'args'.
 286  * Thus, in the case where 'args' should remain available after
 287  * the function returns, the function 'json_object_get' shall be used.
 288  *
 289  * The 'callback' receives 5 arguments:
 290  *  1. 'closure' the user defined closure pointer 'closure',
 291  *  2. 'object'  a JSON object returned (can be NULL)
 292  *  3. 'error'   a string not NULL in case of error but NULL on success
 293  *  4. 'info'    a string handling some info (can be NULL)
 294  *  5. 'api'     the api
 295  *
 296  * @param api      The api that makes the call
 297  * @param apiname  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 callback The to call on completion
 301  * @param closure  The closure to pass to the callback
 302  *
 303  *
 304  * @see afb_req_subcall
 305  * @see afb_req_subcall_sync
 306  * @see afb_api_call_sync
 307  */
 308 void afb_api_call(
 309                         afb_api_t api,
 310                         const char *apiname,
 311                         const char *verb,
 312                         struct json_object *args,
 313                         void (*callback)(
 314                                         void *closure,
 315                                         struct json_object *object,
 316                                         const char *error,
 317                                         const char * info,
 318                                         afb_api_t api),
 319                         void *closure);
 320 ```
 321
 322 ### afb_api_call_sync
 323
 324 ```C
 325 /**
 326  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
 327  * 'result' will receive the response.
 328  *
 329  * For convenience, the function calls 'json_object_put' for 'args'.
 330  * Thus, in the case where 'args' should remain available after
 331  * the function returns, the function 'json_object_get' shall be used.
 332  *
 333  * @param api      The api that makes the call
 334  * @param apiname  The api name of the method to call
 335  * @param verb     The verb name of the method to call
 336  * @param args     The arguments to pass to the method
 337  * @param object   Where to store the returned object - should call json_object_put on it - can be NULL
 338  * @param error    Where to store the copied returned error - should call free on it - can be NULL
 339  * @param info     Where to store the copied returned info - should call free on it - can be NULL
 340  *
 341  * @returns 0 in case of success or a negative value in case of error.
 342  *
 343  * @see afb_req_subcall
 344  * @see afb_req_subcall_sync
 345  * @see afb_api_call
 346  */
 347 int afb_api_call_sync(
 348                         afb_api_t api,
 349                         const char *apiname,
 350                         const char *verb,
 351                         struct json_object *args,
 352                         struct json_object **object,
 353                         char **error,
 354                         char **info);
 355 ```
 356
 357 ### afb_api_queue_job
 358
 359 ```C
 360 /**
 361  * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
 362  * in this thread (later) or in an other thread.
 363  *
 364  * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group')
 365  * are executed in sequence in the order of there submission.
 366  *
 367  * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
 368  * At first, the job is called with 0 as signum and the given argument.
 369  *
 370  * The job is executed with the monitoring of its time and some signals like SIGSEGV and
 371  * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
 372  * signum being the signal number (SIGALRM when timeout expired).
 373  *
 374  * When executed, the callback function receives 2 arguments:
 375  *
 376  *  - int signum: the signal catched if any or zero at the beginning
 377  *  - void *arg: the parameter 'argument'
 378  *
 379  * A typical implementation of the job callback is:
 380  *
 381  * void my_job_cb(int signum, void *arg)
 382  * {
 383  *      struct myarg_t *myarg = arg;
 384  *      if (signum)
 385  *              AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
 386  *      else
 387  *              really_do_my_job(myarg);
 388  * }
 389  *
 390  * @param api the api that queue the job
 391  * @param callback the job as a callback function
 392  * @param argument the argument to pass to the queued job
 393  * @param group the group of the job, NULL if no group
 394  * @param timeout the timeout of execution of the job
 395  *
 396  * @return 0 in case of success or -1 in case of error with errno set appropriately.
 397  */
 398 int afb_api_queue_job(
 399                         afb_api_t api,
 400                         void (*callback)(int signum, void *arg),
 401                         void *argument,
 402                         void *group,
 403                         int timeout);
 404 ```
 405
 406 ## Event functions
 407
 408 ### afb_api_broadcast_event
 409
 410 ```C
 411 /**
 412  * Broadcasts widely the event of 'name' with the data 'object'.
 413  * 'object' can be NULL.
 414  *
 415  * For convenience, the function calls 'json_object_put' for 'object'.
 416  * Thus, in the case where 'object' should remain available after
 417  * the function returns, the function 'json_object_get' shall be used.
 418  *
 419  * Calling this function is only forbidden during preinit.
 420  *
 421  * The event sent as the name API/name where API is the name of the
 422  * api.
 423  *
 424  * @param api the api that broadcast the event
 425  * @param name the event name suffix
 426  * @param object the object that comes with the event
 427  *
 428  * @return the count of clients that received the event.
 429  */
 430 int afb_api_broadcast_event(
 431                         afb_api_t api,
 432                         const char *name,
 433                         struct json_object *object);
 434 ```
 435
 436 ### afb_api_make_event
 437
 438 ```C
 439 /**
 440  * Creates an event of 'name' and returns it.
 441  *
 442  * Calling this function is only forbidden during preinit.
 443  *
 444  * See afb_event_is_valid to check if there is an error.
 445  *
 446  * The event created as the name API/name where API is the name of the
 447  * api.
 448  *
 449  * @param api the api that creates the event
 450  * @param name the event name suffix
 451  *
 452  * @return the created event. Use the function afb_event_is_valid to check
 453  * whether the event is valid (created) or not (error as reported by errno).
 454  *
 455  * @see afb_event_is_valid
 456  */
 457 afb_event_t afb_api_make_event(
 458                         afb_api_t api,
 459                         const char *name);
 460 ```
 461
 462 ### afb_api_event_handler_add
 463
 464 ```C
 465 /**
 466  * Add a specific event handler for the api
 467  *
 468  * The handler callback is called when an event matching the given pattern
 469  * is received (it is received if broadcasted or after subscription through
 470  * a call or a subcall).
 471  *
 472  * The handler callback receive 4 arguments:
 473  *
 474  *  - the closure given here
 475  *  - the event full name
 476  *  - the companion JSON object of the event
 477  *  - the api that subscribed the event
 478  *
 479  * @param api the api that creates the handler
 480  * @param pattern the global pattern of the event to handle
 481  * @param callback the handler callback function
 482  * @param closure the closure of the handler
 483  *
 484  * @return 0 in case of success or -1 on failure with errno set
 485  *
 486  * @see afb_api_on_event
 487  * @see afb_api_event_handler_del
 488  */
 489 int afb_api_event_handler_add(
 490                         afb_api_t api,
 491                         const char *pattern,
 492                         void (*callback)(
 493                                         void *,
 494                                         const char*,
 495                                         struct json_object*,
 496                                         afb_api_t),
 497                         void *closure);
 498 ```
 499
 500 ### afb_api_event_handler_del
 501
 502 ```C
 503 /**
 504  * Delete a specific event handler for the api
 505  *
 506  * @param api the api that the handler belongs to
 507  * @param pattern the global pattern of the handler to remove
 508  * @param closure if not NULL it will receive the closure set to the handler
 509  *
 510  * @return 0 in case of success or -1 on failure with errno set
 511  *
 512  * @see afb_api_on_event
 513  * @see afb_api_event_handler_add
 514  */
 515 int afb_api_event_handler_del(
 516                         afb_api_t api,
 517                         const char *pattern,
 518                         void **closure);
 519
 520 ```
 521
 522 ## Systemd functions
 523
 524 ### afb_api_get_event_loop
 525
 526 ```C
 527 /**
 528  * Retrieves the common systemd's event loop of AFB
 529  *
 530  * @param api the api that uses the event loop
 531  *
 532  * @return the systemd event loop if active, NULL otherwise
 533  *
 534  * @see afb_api_get_user_bus
 535  * @see afb_api_get_system_bus
 536  */
 537 struct sd_event *afb_api_get_event_loop(
 538                         afb_api_t api);
 539 ```
 540
 541 ### afb_api_get_user_bus
 542
 543 ```C
 544 /**
 545  * Retrieves the common systemd's user/session d-bus of AFB
 546  *
 547  * @param api the api that uses the user dbus
 548  *
 549  * @return the systemd user connection to dbus if active, NULL otherwise
 550  *
 551  * @see afb_api_get_event_loop
 552  * @see afb_api_get_system_bus
 553  */
 554 struct sd_bus *afb_api_get_user_bus(
 555                         afb_api_t api);
 556 ```
 557
 558 ### afb_api_get_system_bus
 559
 560 ```C
 561 /**
 562  * Retrieves the common systemd's system d-bus of AFB
 563  *
 564  * @param api the api that uses the system dbus
 565  *
 566  * @return the systemd system connection to dbus if active, NULL otherwise
 567  *
 568  * @see afb_api_get_event_loop
 569  * @see afb_api_get_user_bus
 570  */
 571 struct sd_bus *afb_api_get_system_bus(
 572                         afb_api_t api);
 573 ```
 574
 575
 576 ## Dynamic api functions
 577
 578 ### afb_api_new_api
 579
 580 ```C
 581 /**
 582  * Creates a new api of name 'apiname' briefly described by 'info' (that can
 583  * be NULL).
 584  *
 585  * When the pre-initialization function is given, it is a function that
 586  * receives 2 parameters:
 587  *
 588  *  - the closure as given in the call
 589  *  - the created api that can be initialised
 590  *
 591  * This pre-initialization function must return a negative value to abort
 592  * the creation of the api. Otherwise, it returns a non-negative value to
 593  * continue.
 594  *
 595  * @param api the api that creates the other one
 596  * @param apiname the name of the new api
 597  * @param info the brief description of the new api (can be NULL)
 598  * @param noconcurrency zero or not zero whether the new api is reentrant or not
 599  * @param preinit the pre-initialization function if any (can be NULL)
 600  * @param closure the closure for the pre-initialization preinit
 601  *
 602  * @return the created api in case of success or NULL on error
 603  *
 604  * @see afb_api_delete_api
 605  */
 606 afb_api_t afb_api_new_api(
 607                         afb_api_t api,
 608                         const char *apiname,
 609                         const char *info,
 610                         int noconcurrency,
 611                         int (*preinit)(void*, afb_api_t ),
 612                         void *closure);
 613 ```
 614
 615 ### afb_api_set_verbs_v2
 616
 617 ```C
 618 /**
 619  * @deprecated use @ref afb_api_set_verbs_v3 instead
 620  *
 621  * Set the verbs of the 'api' using description of verbs of the api v2
 622  *
 623  * @param api the api that will get the verbs
 624  * @param verbs the array of verbs to add terminated with an item with name=NULL
 625  *
 626  * @return 0 in case of success or -1 on failure with errno set
 627  *
 628  * @see afb_verb_v2
 629  * @see afb_api_add_verb
 630  * @see afb_api_set_verbs_v3
 631  */
 632 int afb_api_set_verbs_v2(
 633                         afb_api_t api,
 634                         const struct afb_verb_v2 *verbs);
 635 ```
 636
 637 ### afb_api_set_verbs_v3
 638
 639 ```C
 640 /**
 641  * Set the verbs of the 'api' using description of verbs of the api v2
 642  *
 643  * @param api the api that will get the verbs
 644  * @param verbs the array of verbs to add terminated with an item with name=NULL
 645  *
 646  * @return 0 in case of success or -1 on failure with errno set
 647  *
 648  * @see afb_verb_v3
 649  * @see afb_api_add_verb
 650  * @see afb_api_del_verb
 651  */
 652 int afb_api_set_verbs_v3(
 653                         afb_api_t api,
 654                         const struct afb_verb_v3 *verbs);
 655 ```
 656
 657 ### afb_api_add_verb
 658
 659 ```C
 660 /**
 661  * Add one verb to the dynamic set of the api
 662  *
 663  * @param api the api to change
 664  * @param verb name of the verb
 665  * @param info brief description of the verb, can be NULL
 666  * @param callback callback function implementing the verb
 667  * @param vcbdata data for the verb callback, available through req
 668  * @param auth required authorization, can be NULL
 669  * @param session authorization and session requirements of the verb
 670  * @param glob is the verb glob name
 671  *
 672  * @return 0 in case of success or -1 on failure with errno set
 673  *
 674  * @see afb_verb_v3
 675  * @see afb_api_del_verb
 676  * @see afb_api_set_verbs_v3
 677  * @see fnmatch for matching names using glob
 678  */
 679 int afb_api_add_verb(
 680                         afb_api_t api,
 681                         const char *verb,
 682                         const char *info,
 683                         void (*callback)(struct afb_req_x2 *req),
 684                         void *vcbdata,
 685                         const struct afb_auth *auth,
 686                         uint32_t session,
 687                         int glob);
 688 ```
 689
 690 ### afb_api_del_verb
 691
 692 ```C
 693 /**
 694  * Delete one verb from the dynamic set of the api
 695  *
 696  * @param api the api to change
 697  * @param verb name of the verb to delete
 698  * @param vcbdata if not NULL will receive the vcbdata of the deleted verb
 699  *
 700  * @return 0 in case of success or -1 on failure with errno set
 701  *
 702  * @see afb_api_add_verb
 703  */
 704 int afb_api_del_verb(
 705                         afb_api_t api,
 706                         const char *verb,
 707                         void **vcbdata);
 708 ```
 709
 710 ### afb_api_on_event
 711
 712 ```C
 713 /**
 714  * Set the callback 'onevent' to process events in the name of the 'api'.
 715  *
 716  * This setting can be done statically using the global variable
 717  * @ref afbBindingV3.
 718  *
 719  * This function replace any previously global event callback set.
 720  *
 721  * When an event is received, the callback 'onevent' is called with 3 parameters
 722  *
 723  *  - the api that recorded the event handler
 724  *  - the full name of the event
 725  *  - the companion JSON object of the event
 726  *
 727  * @param api the api that wants to process events
 728  * @param onevent the callback function that will process events (can be NULL
 729  *        to remove event callback)
 730  *
 731  * @return 0 in case of success or -1 on failure with errno set
 732  *
 733  * @see afbBindingV3
 734  * @see afb_binding_v3
 735  * @see afb_api_event_handler_add
 736  * @see afb_api_event_handler_del
 737  */
 738 int afb_api_on_event(
 739                         afb_api_t api,
 740                         void (*onevent)(
 741                                         afb_api_t api,
 742                                         const char *event,
 743                                         struct json_object *object));
 744 ```
 745
 746 ### afb_api_on_init
 747
 748 ```C
 749 /**
 750  * Set the callback 'oninit' to process initialization of the 'api'.
 751  *
 752  * This setting can be done statically using the global variable
 753  * @ref afbBindingV3
 754  *
 755  * This function replace any previously initialization callback set.
 756  *
 757  * This function is only valid during the pre-initialization stage.
 758  *
 759  * The callback initialization function will receive one argument: the api
 760  * to initialize.
 761  *
 762  * @param api the api that wants to process events
 763  * @param oninit the callback function that initialize the api
 764  *
 765  * @return 0 in case of success or -1 on failure with errno set
 766  *
 767  * @see afbBindingV3
 768  * @see afb_binding_v3
 769  */
 770 int afb_api_on_init(
 771                         afb_api_t api,
 772                         int (*oninit)(afb_api_t api));
 773 ```
 774
 775 ### afb_api_provide_class
 776
 777 ```C
 778 /**
 779  * Tells that the api provides a class of features. Classes are intended to
 780  * allow ordering of initializations: apis that provides a given class are
 781  * initialized before apis requiring it.
 782  *
 783  * This function is only valid during the pre-initialization stage.
 784  *
 785  * @param api  the api that provides the classes
 786  * @param name a space separated list of the names of the provided classes
 787  *
 788  * @returns 0 in case of success or a negative value in case of error.
 789  *
 790  * @see afb_api_require_class
 791  */
 792 int afb_api_provide_class(
 793                         afb_api_t api,
 794                         const char *name);
 795 ```
 796
 797 ### afb_api_require_class
 798
 799 ```C
 800 /**
 801  * Tells that the api requires a set of class features. Classes are intended to
 802  * allow ordering of initializations: apis that provides a given class are
 803  * initialized before apis requiring it.
 804  *
 805  * This function is only valid during the pre-initialization stage.
 806  *
 807  * @param api  the api that requires the classes
 808  * @param name a space separated list of the names of the required classes
 809  *
 810  * @returns 0 in case of success or a negative value in case of error.
 811  *
 812  * @see afb_api_provide_class
 813  */
 814 int afb_api_require_class(
 815                         afb_api_t api,
 816                         const char *name);
 817 ```
 818
 819 ### afb_api_seal
 820
 821 ```C
 822 /**
 823  * Seal the api. After a call to this function the api can not be modified
 824  * anymore.
 825  *
 826  * @param api the api to be sealed
 827  */
 828 void afb_api_seal(
 829                         afb_api_t api);
 830 ```
 831
 832 ### afb_api_delete_api
 833
 834 ```C
 835 /**
 836  * Delete the given api.
 837  *
 838  * It is of the responsibility of the caller to don't used the deleted api
 839  * anymore after this function returned.
 840  *
 841  * @param api the api to delete
 842  *
 843  * @returns 0 in case of success or a negative value in case of error.
 844  *
 845  * @see afb_api_new_api
 846  */
 847 int afb_api_delete_api(
 848                         afb_api_t api);
 849 ```
 850
 851 ### afb_api_add_alias
 852
 853 ```C
 854 /**
 855  * Create an aliased name 'as_name' for the api 'name'.
 856  * Calling this function is only allowed within preinit.
 857  *
 858  * @param api the api that requires the aliasing
 859  * @param name the api to alias
 860  * @param as_name the aliased name of the aliased api
 861  *
 862  * @return 0 in case of success or -1 in case of error with errno set appropriately.
 863  */
 864 int afb_api_add_alias(
 865                         afb_api_t api,
 866                         const char *name,
 867                         const char *as_name);
 868 ```
 869
 870
 871 ## Legacy functions
 872
 873 The function for legacy calls are still provided for some time because
 874 adaptation of existing code to the new call functions require a small amount
 875 of work.
 876
 877 ### afb_api_call_legacy
 878
 879 ```C
 880 /**
 881  * @deprecated try to use @ref afb_api_call instead
 882  *
 883  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
 884  * in the name of the binding.
 885  * The result of the call is delivered to the 'callback' function
 886  * with the 'callback_closure'.
 887  *
 888  * For convenience, the function calls 'json_object_put' for 'args'.
 889  * Thus, in the case where 'args' should remain available after
 890  * the function returns, the function 'json_object_get' shall be used.
 891  *
 892  * The 'callback' receives 3 arguments:
 893  *  1. 'closure' the user defined closure pointer 'closure',
 894  *  2. 'status' a status being 0 on success or negative when an error occurred,
 895  *  2. 'result' the resulting data as a JSON object.
 896  *
 897  * @param api      The api
 898  * @param apiname  The api name of the method to call
 899  * @param verb     The verb name of the method to call
 900  * @param args     The arguments to pass to the method
 901  * @param callback The to call on completion
 902  * @param closure  The closure to pass to the callback
 903  *
 904  * @see also 'afb_api_call'
 905  * @see also 'afb_api_call_sync'
 906  * @see also 'afb_api_call_sync_legacy'
 907  * @see also 'afb_req_subcall'
 908  * @see also 'afb_req_subcall_sync'
 909  */
 910 void afb_api_call_legacy(
 911                         afb_api_t api,
 912                         const char *apiname,
 913                         const char *verb,
 914                         struct json_object *args,
 915                         void (*callback)(
 916                                         void *closure,
 917                                         int status,
 918                                         struct json_object *result,
 919                                         afb_api_t api),
 920                         void *closure);
 921 ```
 922
 923 ### afb_api_call_sync_legacy
 924
 925 ```C
 926 /**
 927  * @deprecated try to use @ref afb_api_call_sync instead
 928  *
 929  * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
 930  * in the name of the binding.
 931  * 'result' will receive the response.
 932  *
 933  * For convenience, the function calls 'json_object_put' for 'args'.
 934  * Thus, in the case where 'args' should remain available after
 935  * the function returns, the function 'json_object_get' shall be used.
 936  *
 937  * @param api      The api
 938  * @param apiname  The api name of the method to call
 939  * @param verb     The verb name of the method to call
 940  * @param args     The arguments to pass to the method
 941  * @param result   Where to store the result - should call json_object_put on it -
 942  *
 943  * @returns 0 in case of success or a negative value in case of error.
 944  *
 945  * @see also 'afb_api_call'
 946  * @see also 'afb_api_call_sync'
 947  * @see also 'afb_api_call_legacy'
 948  * @see also 'afb_req_subcall'
 949  * @see also 'afb_req_subcall_sync'
 950  */
 951 int afb_api_call_sync_legacy(
 952                         afb_api_t api,
 953                         const char *apiname,
 954                         const char *verb,
 955                         struct json_object *args,
 956                         struct json_object **result);
 957 ```
 958