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 ## Calls and job functions
 259
 260 ### afb_api_call
 261
 262 ```C
 263 /**
 264  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 265  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 266  *
 267  * For convenience, the function calls 'json_object_put' for 'args'.
 268  * Thus, in the case where 'args' should remain available after
 269  * the function returns, the function 'json_object_get' shall be used.
 270  *
 271  * The 'callback' receives 5 arguments:
 272  *  1. 'closure' the user defined closure pointer 'closure',
 273  *  2. 'object'  a JSON object returned (can be NULL)
 274  *  3. 'error'   a string not NULL in case of error but NULL on success
 275  *  4. 'info'    a string handling some info (can be NULL)
 276  *  5. 'api'     the api
 277  *
 278  * @param api      The api that makes the call
 279  * @param apiname  The api name of the method to call
 280  * @param verb     The verb name of the method to call
 281  * @param args     The arguments to pass to the method
 282  * @param callback The to call on completion
 283  * @param closure  The closure to pass to the callback
 284  *
 285  *
 286  * @see afb_req_subcall
 287  * @see afb_req_subcall_sync
 288  * @see afb_api_call_sync
 289  */
 290 void afb_api_call(
 291                         afb_api_t api,
 292                         const char *apiname,
 293                         const char *verb,
 294                         struct json_object *args,
 295                         void (*callback)(
 296                                         void *closure,
 297                                         struct json_object *object,
 298                                         const char *error,
 299                                         const char * info,
 300                                         afb_api_t api),
 301                         void *closure);
 302 ```
 303
 304 ### afb_api_call_sync
 305
 306 ```C
 307 /**
 308  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 309  * 'result' will receive the response.
 310  *
 311  * For convenience, the function calls 'json_object_put' for 'args'.
 312  * Thus, in the case where 'args' should remain available after
 313  * the function returns, the function 'json_object_get' shall be used.
 314  *
 315  * @param api      The api that makes the call
 316  * @param apiname  The api name of the method to call
 317  * @param verb     The verb name of the method to call
 318  * @param args     The arguments to pass to the method
 319  * @param object   Where to store the returned object - should call json_object_put on it - can be NULL
 320  * @param error    Where to store the copied returned error - should call free on it - can be NULL
 321  * @param info     Where to store the copied returned info - should call free on it - can be NULL
 322  *
 323  * @returns 0 in case of success or a negative value in case of error.
 324  *
 325  * @see afb_req_subcall
 326  * @see afb_req_subcall_sync
 327  * @see afb_api_call
 328  */
 329 int afb_api_call_sync(
 330                         afb_api_t api,
 331                         const char *apiname,
 332                         const char *verb,
 333                         struct json_object *args,
 334                         struct json_object **object,
 335                         char **error,
 336                         char **info);
 337 ```
 338
 339 ### afb_api_queue_job
 340
 341 ```C
 342 /**
 343  * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
 344  * in this thread (later) or in an other thread.
 345  *
 346  * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group')
 347  * are executed in sequence in the order of there submission.
 348  *
 349  * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
 350  * At first, the job is called with 0 as signum and the given argument.
 351  *
 352  * The job is executed with the monitoring of its time and some signals like SIGSEGV and
 353  * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
 354  * signum being the signal number (SIGALRM when timeout expired).
 355  *
 356  * When executed, the callback function receives 2 arguments:
 357  *
 358  *  - int signum: the signal catched if any or zero at the beginning
 359  *  - void *arg: the parameter 'argument'
 360  *
 361  * A typical implementation of the job callback is:
 362  *
 363  * void my_job_cb(int signum, void *arg)
 364  * {
 365  *      struct myarg_t *myarg = arg;
 366  *      if (signum)
 367  *              AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
 368  *      else
 369  *              really_do_my_job(myarg);
 370  * }
 371  *
 372  * @param api the api that queue the job
 373  * @param callback the job as a callback function
 374  * @param argument the argument to pass to the queued job
 375  * @param group the group of the job, NULL if no group
 376  * @param timeout the timeout of execution of the job
 377  *
 378  * @return 0 in case of success or -1 in case of error with errno set appropriately.
 379  */
 380 int afb_api_queue_job(
 381                         afb_api_t api,
 382                         void (*callback)(int signum, void *arg),
 383                         void *argument,
 384                         void *group,
 385                         int timeout);
 386 ```
 387
 388 ## Event functions
 389
 390 ### afb_api_broadcast_event
 391
 392 ```C
 393 /**
 394  * Broadcasts widely the event of 'name' with the data 'object'.
 395  * 'object' can be NULL.
 396  *
 397  * For convenience, the function calls 'json_object_put' for 'object'.
 398  * Thus, in the case where 'object' should remain available after
 399  * the function returns, the function 'json_object_get' shall be used.
 400  *
 401  * Calling this function is only forbidden during preinit.
 402  *
 403  * The event sent as the name API/name where API is the name of the
 404  * api.
 405  *
 406  * @param api the api that broadcast the event
 407  * @param name the event name suffix
 408  * @param object the object that comes with the event
 409  *
 410  * @return the count of clients that received the event.
 411  */
 412 int afb_api_broadcast_event(
 413                         afb_api_t api,
 414                         const char *name,
 415                         struct json_object *object);
 416 ```
 417
 418 ### afb_api_make_event
 419
 420 ```C
 421 /**
 422  * Creates an event of 'name' and returns it.
 423  *
 424  * Calling this function is only forbidden during preinit.
 425  *
 426  * See afb_event_is_valid to check if there is an error.
 427  *
 428  * The event created as the name API/name where API is the name of the
 429  * api.
 430  *
 431  * @param api the api that creates the event
 432  * @param name the event name suffix
 433  *
 434  * @return the created event. Use the function afb_event_is_valid to check
 435  * whether the event is valid (created) or not (error as reported by errno).
 436  *
 437  * @see afb_event_is_valid
 438  */
 439 afb_event_t afb_api_make_event(
 440                         afb_api_t api,
 441                         const char *name);
 442 ```
 443
 444 ### afb_api_event_handler_add
 445
 446 ```C
 447 /**
 448  * Add a specific event handler for the api
 449  *
 450  * The handler callback is called when an event matching the given pattern
 451  * is received (it is received if broadcasted or after subscription through
 452  * a call or a subcall).
 453  *
 454  * The handler callback receive 4 arguments:
 455  *
 456  *  - the closure given here
 457  *  - the event full name
 458  *  - the companion JSON object of the event
 459  *  - the api that subscribed the event
 460  *
 461  * @param api the api that creates the handler
 462  * @param pattern the global pattern of the event to handle
 463  * @param callback the handler callback function
 464  * @param closure the closure of the handler
 465  *
 466  * @return 0 in case of success or -1 on failure with errno set
 467  *
 468  * @see afb_api_on_event
 469  * @see afb_api_event_handler_del
 470  */
 471 int afb_api_event_handler_add(
 472                         afb_api_t api,
 473                         const char *pattern,
 474                         void (*callback)(
 475                                         void *,
 476                                         const char*,
 477                                         struct json_object*,
 478                                         afb_api_t),
 479                         void *closure);
 480 ```
 481
 482 ### afb_api_event_handler_del
 483
 484 ```C
 485 /**
 486  * Delete a specific event handler for the api
 487  *
 488  * @param api the api that the handler belongs to
 489  * @param pattern the global pattern of the handler to remove
 490  * @param closure if not NULL it will receive the closure set to the handler
 491  *
 492  * @return 0 in case of success or -1 on failure with errno set
 493  *
 494  * @see afb_api_on_event
 495  * @see afb_api_event_handler_add
 496  */
 497 int afb_api_event_handler_del(
 498                         afb_api_t api,
 499                         const char *pattern,
 500                         void **closure);
 501
 502 ```
 503
 504 ## Systemd functions
 505
 506 ### afb_api_get_event_loop
 507
 508 ```C
 509 /**
 510  * Retrieves the common systemd's event loop of AFB
 511  *
 512  * @param api the api that uses the event loop
 513  *
 514  * @return the systemd event loop if active, NULL otherwise
 515  *
 516  * @see afb_api_get_user_bus
 517  * @see afb_api_get_system_bus
 518  */
 519 struct sd_event *afb_api_get_event_loop(
 520                         afb_api_t api);
 521 ```
 522
 523 ### afb_api_get_user_bus
 524
 525 ```C
 526 /**
 527  * Retrieves the common systemd's user/session d-bus of AFB
 528  *
 529  * @param api the api that uses the user dbus
 530  *
 531  * @return the systemd user connection to dbus if active, NULL otherwise
 532  *
 533  * @see afb_api_get_event_loop
 534  * @see afb_api_get_system_bus
 535  */
 536 struct sd_bus *afb_api_get_user_bus(
 537                         afb_api_t api);
 538 ```
 539
 540 ### afb_api_get_system_bus
 541
 542 ```C
 543 /**
 544  * Retrieves the common systemd's system d-bus of AFB
 545  *
 546  * @param api the api that uses the system dbus
 547  *
 548  * @return the systemd system connection to dbus if active, NULL otherwise
 549  *
 550  * @see afb_api_get_event_loop
 551  * @see afb_api_get_user_bus
 552  */
 553 struct sd_bus *afb_api_get_system_bus(
 554                         afb_api_t api);
 555 ```
 556
 557
 558 ## Dynamic api functions
 559
 560 ### afb_api_new_api
 561
 562 ```C
 563 /**
 564  * Creates a new api of name 'apiname' briefly described by 'info' (that can
 565  * be NULL).
 566  *
 567  * When the pre-initialization function is given, it is a function that
 568  * receives 2 parameters:
 569  *
 570  *  - the closure as given in the call
 571  *  - the created api that can be initialised
 572  *
 573  * This pre-initialization function must return a negative value to abort
 574  * the creation of the api. Otherwise, it returns a non-negative value to
 575  * continue.
 576  *
 577  * @param api the api that creates the other one
 578  * @param apiname the name of the new api
 579  * @param info the brief description of the new api (can be NULL)
 580  * @param noconcurrency zero or not zero whether the new api is reentrant or not
 581  * @param preinit the pre-initialization function if any (can be NULL)
 582  * @param closure the closure for the pre-initialization \ref preinit
 583  *
 584  * @return 0 in case of success or -1 on failure with errno set
 585  *
 586  * @see afb_api_delete_api
 587  */
 588 afb_api_t afb_api_new_api(
 589                         afb_api_t api,
 590                         const char *apiname,
 591                         const char *info,
 592                         int noconcurrency,
 593                         int (*preinit)(void*, afb_api_t ),
 594                         void *closure);
 595 ```
 596
 597 ### afb_api_set_verbs_v2
 598
 599 ```C
 600 /**
 601  * @deprecated use @ref afb_api_set_verbs_v3 instead
 602  *
 603  * Set the verbs of the 'api' using description of verbs of the api v2
 604  *
 605  * @param api the api that will get the verbs
 606  * @param verbs the array of verbs to add terminated with an item with name=NULL
 607  *
 608  * @return 0 in case of success or -1 on failure with errno set
 609  *
 610  * @see afb_verb_v2
 611  * @see afb_api_add_verb
 612  * @see afb_api_set_verbs_v3
 613  */
 614 int afb_api_set_verbs_v2(
 615                         afb_api_t api,
 616                         const struct afb_verb_v2 *verbs);
 617 ```
 618
 619 ### afb_api_set_verbs_v3
 620
 621 ```C
 622 /**
 623  * Set the verbs of the 'api' using description of verbs of the api v2
 624  *
 625  * @param api the api that will get the verbs
 626  * @param verbs the array of verbs to add terminated with an item with name=NULL
 627  *
 628  * @return 0 in case of success or -1 on failure with errno set
 629  *
 630  * @see afb_verb_v3
 631  * @see afb_api_add_verb
 632  * @see afb_api_del_verb
 633  */
 634 int afb_api_set_verbs_v3(
 635                         afb_api_t api,
 636                         const struct afb_verb_v3 *verbs);
 637 ```
 638
 639 ### afb_api_add_verb
 640
 641 ```C
 642 /**
 643  * Add one verb to the dynamic set of the api
 644  *
 645  * @param api the api to change
 646  * @param verb name of the verb
 647  * @param info brief description of the verb, can be NULL
 648  * @param callback callback function implementing the verb
 649  * @param vcbdata data for the verb callback, available through req
 650  * @param auth required authorization, can be NULL
 651  * @param session authorization and session requirements of the verb
 652  * @param glob is the verb glob name
 653  *
 654  * @return 0 in case of success or -1 on failure with errno set
 655  *
 656  * @see afb_verb_v3
 657  * @see afb_api_del_verb
 658  * @see afb_api_set_verbs_v3
 659  * @see fnmatch for matching names using glob
 660  */
 661 int afb_api_add_verb(
 662                         afb_api_t api,
 663                         const char *verb,
 664                         const char *info,
 665                         void (*callback)(struct afb_req_x2 *req),
 666                         void *vcbdata,
 667                         const struct afb_auth *auth,
 668                         uint32_t session,
 669                         int glob);
 670 ```
 671
 672 ### afb_api_del_verb
 673
 674 ```C
 675 /**
 676  * Delete one verb from the dynamic set of the api
 677  *
 678  * @param api the api to change
 679  * @param verb name of the verb to delete
 680  * @param vcbdata if not NULL will receive the vcbdata of the deleted verb
 681  *
 682  * @return 0 in case of success or -1 on failure with errno set
 683  *
 684  * @see afb_api_add_verb
 685  */
 686 int afb_api_del_verb(
 687                         afb_api_t api,
 688                         const char *verb,
 689                         void **vcbdata);
 690 ```
 691
 692 ### afb_api_on_event
 693
 694 ```C
 695 /**
 696  * Set the callback 'onevent' to process events in the name of the 'api'.
 697  *
 698  * This setting can be done statically using the global variable
 699  * @ref afbBindingV3.
 700  *
 701  * This function replace any previously global event callback set.
 702  *
 703  * When an event is received, the callback 'onevent' is called with 3 parameters
 704  *
 705  *  - the api that recorded the event handler
 706  *  - the full name of the event
 707  *  - the companion JSON object of the event
 708  *
 709  * @param api the api that wants to process events
 710  * @param onevent the callback function that will process events (can be NULL
 711  *        to remove event callback)
 712  *
 713  * @return 0 in case of success or -1 on failure with errno set
 714  *
 715  * @see afbBindingV3
 716  * @see afb_binding_v3
 717  * @see afb_api_event_handler_add
 718  * @see afb_api_event_handler_del
 719  */
 720 int afb_api_on_event(
 721                         afb_api_t api,
 722                         void (*onevent)(
 723                                         afb_api_t api,
 724                                         const char *event,
 725                                         struct json_object *object));
 726 ```
 727
 728 ### afb_api_on_init
 729
 730 ```C
 731 /**
 732  * Set the callback 'oninit' to process initialization of the 'api'.
 733  *
 734  * This setting can be done statically using the global variable
 735  * @ref afbBindingV3
 736  *
 737  * This function replace any previously initialization callback set.
 738  *
 739  * This function is only valid during the pre-initialization stage.
 740  *
 741  * The callback initialization function will receive one argument: the api
 742  * to initialize.
 743  *
 744  * @param api the api that wants to process events
 745  * @param oninit the callback function that initialize the api
 746  *
 747  * @return 0 in case of success or -1 on failure with errno set
 748  *
 749  * @see afbBindingV3
 750  * @see afb_binding_v3
 751  */
 752 int afb_api_on_init(
 753                         afb_api_t api,
 754                         int (*oninit)(afb_api_t api));
 755 ```
 756
 757 ### afb_api_provide_class
 758
 759 ```C
 760 /**
 761  * Tells that the api provides a class of features. Classes are intended to
 762  * allow ordering of initializations: apis that provides a given class are
 763  * initialized before apis requiring it.
 764  *
 765  * This function is only valid during the pre-initialization stage.
 766  *
 767  * @param api  the api that provides the classes
 768  * @param name a space separated list of the names of the provided classes
 769  *
 770  * @returns 0 in case of success or a negative value in case of error.
 771  *
 772  * @see afb_api_require_class
 773  */
 774 int afb_api_provide_class(
 775                         afb_api_t api,
 776                         const char *name);
 777 ```
 778
 779 ### afb_api_require_class
 780
 781 ```C
 782 /**
 783  * Tells that the api requires a set of class features. Classes are intended to
 784  * allow ordering of initializations: apis that provides a given class are
 785  * initialized before apis requiring it.
 786  *
 787  * This function is only valid during the pre-initialization stage.
 788  *
 789  * @param api  the api that requires the classes
 790  * @param name a space separated list of the names of the required classes
 791  *
 792  * @returns 0 in case of success or a negative value in case of error.
 793  *
 794  * @see afb_api_provide_class
 795  */
 796 int afb_api_require_class(
 797                         afb_api_t api,
 798                         const char *name);
 799 ```
 800
 801 ### afb_api_seal
 802
 803 ```C
 804 /**
 805  * Seal the api. After a call to this function the api can not be modified
 806  * anymore.
 807  *
 808  * @param api the api to be sealed
 809  */
 810 void afb_api_seal(
 811                         afb_api_t api);
 812 ```
 813
 814 ### afb_api_delete_api
 815
 816 ```C
 817 /**
 818  * Delete the given api.
 819  *
 820  * It is of the responsibility of the caller to don't used the deleted api
 821  * anymore after this function returned.
 822  *
 823  * @param api the api to delete
 824  *
 825  * @returns 0 in case of success or a negative value in case of error.
 826  *
 827  * @see afb_api_new_api
 828  */
 829 int afb_api_delete_api(
 830                         afb_api_t api);
 831 ```
 832
 833 ### afb_api_add_alias
 834
 835 ```C
 836 /**
 837  * Create an aliased name 'as_name' for the api 'name'.
 838  * Calling this function is only allowed within preinit.
 839  *
 840  * @param api the api that requires the aliasing
 841  * @param name the api to alias
 842  * @param as_name the aliased name of the aliased api
 843  *
 844  * @return 0 in case of success or -1 in case of error with errno set appropriately.
 845  */
 846 int afb_api_add_alias(
 847                         afb_api_t api,
 848                         const char *name,
 849                         const char *as_name);
 850 ```
 851
 852
 853 ## Legacy functions
 854
 855 The function for legacy calls are still provided for some time because
 856 adaptation of existing code to the new call functions require a small amount
 857 of work.
 858
 859 ### afb_api_call_legacy
 860
 861 ```C
 862 /**
 863  * @deprecated try to use @ref afb_api_call instead
 864  *
 865  *  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 866  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 867  *
 868  * For convenience, the function calls 'json_object_put' for 'args'.
 869  * Thus, in the case where 'args' should remain available after
 870  * the function returns, the function 'json_object_get' shall be used.
 871  *
 872  * The 'callback' receives 3 arguments:
 873  *  1. 'closure' the user defined closure pointer 'closure',
 874  *  2. 'status' a status being 0 on success or negative when an error occurred,
 875  *  2. 'result' the resulting data as a JSON object.
 876  *
 877  * @param api      The api
 878  * @param apiname  The api name of the method to call
 879  * @param verb     The verb name of the method to call
 880  * @param args     The arguments to pass to the method
 881  * @param callback The to call on completion
 882  * @param closure  The closure to pass to the callback
 883  *
 884  * @see also 'afb_api_call'
 885  * @see also 'afb_api_call_sync'
 886  * @see also 'afb_api_call_sync_legacy'
 887  * @see also 'afb_req_subcall'
 888  * @see also 'afb_req_subcall_sync'
 889  */
 890 void afb_api_call_legacy(
 891                         afb_api_t api,
 892                         const char *apiname,
 893                         const char *verb,
 894                         struct json_object *args,
 895                         void (*callback)(
 896                                         void *closure,
 897                                         int status,
 898                                         struct json_object *result,
 899                                         afb_api_t api),
 900                         void *closure);
 901 ```
 902
 903 ### afb_api_call_sync_legacy
 904
 905 ```C
 906 /**
 907  * @deprecated try to use @ref afb_api_call_sync instead
 908  *
 909  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 910  * 'result' will receive the response.
 911  *
 912  * For convenience, the function calls 'json_object_put' for 'args'.
 913  * Thus, in the case where 'args' should remain available after
 914  * the function returns, the function 'json_object_get' shall be used.
 915  *
 916  * @param api      The api
 917  * @param apiname  The api name of the method to call
 918  * @param verb     The verb name of the method to call
 919  * @param args     The arguments to pass to the method
 920  * @param result   Where to store the result - should call json_object_put on it -
 921  *
 922  * @returns 0 in case of success or a negative value in case of error.
 923  *
 924  * @see also 'afb_api_call'
 925  * @see also 'afb_api_call_sync'
 926  * @see also 'afb_api_call_legacy'
 927  * @see also 'afb_req_subcall'
 928  * @see also 'afb_req_subcall_sync'
 929  */
 930 int afb_api_call_sync_legacy(
 931                         afb_api_t api,
 932                         const char *apiname,
 933                         const char *verb,
 934                         struct json_object *args,
 935                         struct json_object **result);
 936 ```
 937