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