2 title: Binder References
8 ## The global afbBindingRoot
10 The global **afbBindingRoot** of type **afb_api_t** is always implicitly
11 defined for bindings of version 3 or upper. It records the root api of
14 When the binding has a defined **afbBindingExport**, the root api
15 **afbBindingRoot** is the **afb_pi_t** relative to the api created for
16 this static description.
18 When the binding has no defined **afbBindingExport**, the root api is
19 a virtual api representing the shared object of the binding. In that case
20 the name of the api is the path of the shared object. Its use is restricted
21 but allows log messages.
23 ## The global afbBindingExport
25 The global **afbBindingExport** is not mandatory.
27 If **afbBindingExport** is defined and exported, it must be of the type
28 **const afb_binding_t** and must describe the *root* api of the binding.
32 Bindings now can declare more than one api. The counter part is that
33 a new handle is needed to manage apis. These handles are of the type
36 It is defined as below.
39 typedef struct afb_api_x3 afb_api_t;
42 ## The type afb_binding_t
44 The main structure, of type **afb_binding_t**, for describing the binding
45 must be exported under the name **afbBindingExport**.
47 This structure is defined as below.
50 typedef struct afb_binding_v3 afb_binding_t;
57 * Description of the bindings of type version 3
61 /** api name for the binding, can't be NULL */
64 /** textual specification of the binding, can be NULL */
65 const char *specification;
67 /** some info about the api, can be NULL */
70 /** array of descriptions of verbs terminated by a NULL name, can be NULL */
71 const struct afb_verb_v3 *verbs;
73 /** callback at load of the binding */
74 int (*preinit)(struct afb_api_x3 *api);
76 /** callback for starting the service */
77 int (*init)(struct afb_api_x3 *api);
79 /** callback for handling events */
80 void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
82 /** userdata for afb_api_x3 */
85 /** space separated list of provided class(es) */
86 const char *provide_class;
88 /** space separated list of required class(es) */
89 const char *require_class;
91 /** space separated list of required API(es) */
92 const char *require_api;
94 /** avoids concurrent requests to verbs */
95 unsigned noconcurrency: 1;
99 ## The type afb_verb_t
101 Each verb is described with a structure of type **afb_verb_t**
105 typedef struct afb_verb_v3 afb_verb_t;
110 * Description of one verb as provided for binding API version 3
114 /** name of the verb, NULL only at end of the array */
117 /** callback function implementing the verb */
118 void (*callback)(afb_req_t_x2 *req);
120 /** required authorization, can be NULL */
121 const struct afb_auth *auth;
123 /** some info about the verb, can be NULL */
126 /**< data for the verb callback */
129 /** authorization and session requirements of the verb */
132 /** is the verb glob name */
137 The **session** flags is one of the constant defined below:
140 |:----------------------:|------------------------------------------------------
141 | AFB_SESSION_NONE | no flag, synonym to 0
142 | AFB_SESSION_LOA_0 | Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE
143 | AFB_SESSION_LOA_1 | Requires the LOA to be 1 or more
144 | AFB_SESSION_LOA_2 | Requires the LOA to be 2 or more
145 | AFB_SESSION_LOA_3 | Requires the LOA to be 3 or more
146 | AFB_SESSION_CHECK | Requires the token to be set and valid
147 | AFB_SESSION_REFRESH | Implies a token refresh
148 | AFB_SESSION_CLOSE | Implies closing the session after request processed
150 The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**.
152 The session can be closed, by binding api, using the function **afb_req_session_close**.
154 ## The types afb_auth_t and afb_auth_type_t
156 The structure **afb_auth_t** is used within verb description to
157 set security requirements.
158 The interpretation of the structure depends on the value of the field **type**.
161 typedef struct afb_auth afb_auth_t;
164 * Definition of an authorization entry
168 /** type of entry @see afb_auth_type */
169 enum afb_auth_type type;
172 /** text when @ref type == @ref afb_auth_Permission */
175 /** level of assurancy when @ref type == @ref afb_auth_LOA */
178 /** first child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And, @ref afb_auth_Not } */
179 const struct afb_auth *first;
182 /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */
183 const struct afb_auth *next;
188 The possible values for **type** is defined here:
191 typedef enum afb_auth_type afb_auth_type_t;
194 * Enumeration for authority (Session/Token/Assurance) definitions.
200 /** never authorized, no data */
203 /** authorized if token valid, no data */
206 /** authorized if LOA greater than or equal to data 'loa' */
209 /** authorized if permission 'text' is granted */
212 /** authorized if 'first' or 'next' is authorized */
215 /** authorized if 'first' and 'next' are authorized */
218 /** authorized if 'first' is not authorized */
221 /** always authorized, no data */
229 static const afb_auth_t myauth[] = {
230 { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:set" },
231 { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:get" },
232 { .type = afb_auth_Or, .first = &myauth[1], .next = &myauth[0] }
237 ## The type afb_req_subcall_flags_t
239 This is an enumeration that defines bit's positions for setting behaviour
242 | flag | value | description
243 |----------------------------|-------|--------------
244 | afb_req_subcall_catch_events | 1 | the calling API wants to receive the events from subscription
245 | afb_req_subcall_pass_events | 2 | the original request will receive the events from subscription
246 | afb_req_subcall_on_behalf | 4 | the calling API wants to use the credentials of the original request
247 | afb_req_subcall_api_session | 8 | the calling API wants to use its session instead of the one of the original request
249 ii. MACROS FOR LOGGING
252 The final behaviour of macros can be tuned using 2 defines that must be defined
253 before including **<afb/afb-binding.h>**.
256 |---------------------------------------|--------------------
257 | AFB_BINDING_PRAGMA_NO_VERBOSE_DATA | show file and line, remove function and text message
258 | AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS | show text, remove function, line and file
260 ## Logging for an api
262 The following macros must be used for logging for an **api** of type
266 AFB_API_ERROR(api,fmt,...)
267 AFB_API_WARNING(api,fmt,...)
268 AFB_API_NOTICE(api,fmt,...)
269 AFB_API_INFO(api,fmt,...)
270 AFB_API_DEBUG(api,fmt,...)
273 ## Logging for a request
276 The following macros can be used for logging in the context
277 of a request **req** of type **afb_req_t**:
280 AFB_REQ_ERROR(req,fmt,...)
281 AFB_REQ_WARNING(req,fmt,...)
282 AFB_REQ_NOTICE(req,fmt,...)
283 AFB_REQ_INFO(req,fmt,...)
284 AFB_REQ_DEBUG(req,fmt,...)
287 By default, the logging macros add file, line and function
292 The following macros are provided for legacy.
302 iii. FUNCTIONS OF CLASS **afb_api**
303 ============================
311 * Get the name of the 'api'.
313 * @param api the api whose name is to be returned
315 * @return the name of the api.
317 * The returned value must not be changed nor freed.
319 const char *afb_api_name(
323 ### afb_api_get_userdata
327 * Get the "userdata" pointer of the 'api'
329 * @param api the api whose user's data is to be returned
331 * @return the user's data pointer of the api.
333 * @see afb_api_set_userdata
335 void *afb_api_get_userdata(
339 ### afb_api_set_userdata
343 * Set the "userdata" pointer of the 'api' to 'value'
345 * @param api the api whose user's data is to be set
346 * @param value the data to set
348 * @see afb_api_get_userdata
350 void afb_api_set_userdata(
355 ### afb_api_require_api
359 * Check that it requires the API of 'name'.
360 * If 'initialized' is not zero it requests the API to be
361 * initialized, implying its initialization if needed.
363 * Calling this function is only allowed within init.
365 * A single request allows to require multiple apis.
367 * @param api the api that requires the other api by its name
368 * @param name a space separated list of required api names
369 * @param initialized if zero, the api is just required to exist. If not zero,
370 * the api is required to exist and to be initialized at return of the call
371 * (initializing it if needed and possible as a side effect of the call).
373 * @return 0 in case of success or -1 in case of error with errno set appropriately.
375 int afb_api_require_api(
382 ## Verbosity functions
384 ### afb_api_wants_log_level
388 * Is the log message of 'level (as defined for syslog) required for the api?
390 * @param api the api to check
391 * @param level the level to check as defined for syslog:
393 * EMERGENCY 0 System is unusable
394 * ALERT 1 Action must be taken immediately
395 * CRITICAL 2 Critical conditions
396 * ERROR 3 Error conditions
397 * WARNING 4 Warning conditions
398 * NOTICE 5 Normal but significant condition
399 * INFO 6 Informational
400 * DEBUG 7 Debug-level messages
402 * @return 0 if not required or a value not null if required
406 int afb_api_wants_log_level(
415 * Send to the journal with the logging 'level' a message described
416 * by 'fmt' applied to the va-list 'args'.
418 * 'file', 'line' and 'func' are indicators of code position in source files
419 * (see macros __FILE__, __LINE__ and __func__).
421 * 'level' is defined by syslog standard:
423 * EMERGENCY 0 System is unusable
424 * ALERT 1 Action must be taken immediately
425 * CRITICAL 2 Critical conditions
426 * ERROR 3 Error conditions
427 * WARNING 4 Warning conditions
428 * NOTICE 5 Normal but significant condition
429 * INFO 6 Informational
430 * DEBUG 7 Debug-level messages
432 * @param api the api that collects the logging message
433 * @param level the level of the message
434 * @param file the source file that logs the messages or NULL
435 * @param line the line in the source file that logs the message
436 * @param func the name of the function in the source file that logs
437 * @param fmt the format of the message as in printf
438 * @param args the arguments to the format string of the message as a va_list
443 void afb_api_vverbose(
457 * Send to the journal with the log 'level' a message described
458 * by 'fmt' and following parameters.
460 * 'file', 'line' and 'func' are indicators of position of the code in source files
461 * (see macros __FILE__, __LINE__ and __func__).
463 * 'level' is defined by syslog standard:
464 * EMERGENCY 0 System is unusable
465 * ALERT 1 Action must be taken immediately
466 * CRITICAL 2 Critical conditions
467 * ERROR 3 Error conditions
468 * WARNING 4 Warning conditions
469 * NOTICE 5 Normal but significant condition
470 * INFO 6 Informational
471 * DEBUG 7 Debug-level messages
473 * @param api the api that collects the logging message
474 * @param level the level of the message
475 * @param file the source file that logs the messages or NULL
476 * @param line the line in the source file that logs the message
477 * @param func the name of the function in the source file that logs
478 * @param fmt the format of the message as in printf
479 * @param ... the arguments to the format string of the message
484 void afb_api_verbose(
494 ## Data retrieval functions
496 ### afb_api_rootdir_get_fd
500 * Get the root directory file descriptor. This file descriptor can
501 * be used with functions 'openat', 'fstatat', ...
503 * CAUTION, manipulate this descriptor with care, in particular, don't close
506 * This can be used to get the path of the root directory using:
508 * char buffer[MAX_PATH], proc[100];
509 * int dirfd = afb_api_rootdir_get_fd(api);
510 * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd);
511 * readlink(proc, buffer, sizeof buffer);
513 * But note that within AGL this is the value given by the environment variable
514 * AFM_APP_INSTALL_DIR.
516 * @param api the api that uses the directory file descriptor
518 * @return the file descriptor of the root directory.
520 * @see afb_api_rootdir_open_locale
522 int afb_api_rootdir_get_fd(
526 ### afb_api_rootdir_open_locale
530 * Opens 'filename' within the root directory with 'flags' (see function openat)
531 * using the 'locale' definition (example: "jp,en-US") that can be NULL.
533 * The filename must be relative to the root of the bindings.
535 * The opening mode must be for read or write but not for O_CREAT.
537 * The definition of locales and of how files are searched can be checked
538 * here: https://www.w3.org/TR/widgets/#folder-based-localization
539 * and https://tools.ietf.org/html/rfc7231#section-5.3.5
541 * @param api the api that queries the file
542 * @param filename the relative path to the file to open
543 * @param flags the flags for opening as for C function 'open'
544 * @param locale string indicating how to search content, can be NULL
546 * @return the file descriptor or -1 in case of error and errno is set with the
550 * @see afb_api_rootdir_get_fd
552 int afb_api_rootdir_open_locale(
554 const char *filename,
563 * Settings of the api.
565 * Get the settings of the API. The settings are recorded
566 * as a JSON object. The returned object should not be modified.
567 * It MUST NOT be released using json_object_put.
569 * @param api the api whose settings are required
571 * @returns The setting object.
573 struct json_object *afb_api_settings(
574 struct afb_api_x3 *api);
577 ## Calls and job functions
583 * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
584 * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
586 * For convenience, the function calls 'json_object_put' for 'args'.
587 * Thus, in the case where 'args' should remain available after
588 * the function returns, the function 'json_object_get' shall be used.
590 * The 'callback' receives 5 arguments:
591 * 1. 'closure' the user defined closure pointer 'closure',
592 * 2. 'object' a JSON object returned (can be NULL)
593 * 3. 'error' a string not NULL in case of error but NULL on success
594 * 4. 'info' a string handling some info (can be NULL)
597 * NOTE: For convenience, *json_object_put* is called on 'object' after the
598 * callback returns. So, it is wrong to call *json_object_put* in the callback.
600 * @param api The api that makes the call
601 * @param apiname The api name of the method to call
602 * @param verb The verb name of the method to call
603 * @param args The arguments to pass to the method
604 * @param callback The to call on completion
605 * @param closure The closure to pass to the callback
608 * @see afb_req_subcall
609 * @see afb_req_subcall_sync
610 * @see afb_api_call_sync
616 struct json_object *args,
619 struct json_object *object,
626 ### afb_api_call_sync
630 * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'.
631 * 'result' will receive the response.
633 * For convenience, the function calls 'json_object_put' for 'args'.
634 * Thus, in the case where 'args' should remain available after
635 * the function returns, the function 'json_object_get' shall be used.
637 * @param api The api that makes the call
638 * @param apiname The api name of the method to call
639 * @param verb The verb name of the method to call
640 * @param args The arguments to pass to the method
641 * @param object Where to store the returned object - should call json_object_put on it - can be NULL
642 * @param error Where to store the copied returned error - should call free on it - can be NULL
643 * @param info Where to store the copied returned info - should call free on it - can be NULL
645 * @returns 0 in case of success or a negative value in case of error.
647 * @see afb_req_subcall
648 * @see afb_req_subcall_sync
651 int afb_api_call_sync(
655 struct json_object *args,
656 struct json_object **object,
661 ### afb_api_queue_job
665 * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
666 * in this thread (later) or in an other thread.
668 * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group')
669 * are executed in sequence in the order of there submission.
671 * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
672 * At first, the job is called with 0 as signum and the given argument.
674 * The job is executed with the monitoring of its time and some signals like SIGSEGV and
675 * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
676 * signum being the signal number (SIGALRM when timeout expired).
678 * When executed, the callback function receives 2 arguments:
680 * - int signum: the signal catched if any or zero at the beginning
681 * - void *arg: the parameter 'argument'
683 * A typical implementation of the job callback is:
685 * void my_job_cb(int signum, void *arg)
687 * struct myarg_t *myarg = arg;
689 * AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
691 * really_do_my_job(myarg);
694 * @param api the api that queue the job
695 * @param callback the job as a callback function
696 * @param argument the argument to pass to the queued job
697 * @param group the group of the job, NULL if no group
698 * @param timeout the timeout of execution of the job
700 * @return 0 in case of success or -1 in case of error with errno set appropriately.
702 int afb_api_queue_job(
704 void (*callback)(int signum, void *arg),
712 ### afb_api_broadcast_event
716 * Broadcasts widely the event of 'name' with the data 'object'.
717 * 'object' can be NULL.
719 * For convenience, the function calls 'json_object_put' for 'object'.
720 * Thus, in the case where 'object' should remain available after
721 * the function returns, the function 'json_object_get' shall be used.
723 * Calling this function is only forbidden during preinit.
725 * The event sent as the name API/name where API is the name of the
728 * @param api the api that broadcast the event
729 * @param name the event name suffix
730 * @param object the object that comes with the event
732 * @return 0 in case of success or -1 in case of error
734 int afb_api_broadcast_event(
737 struct json_object *object);
740 ### afb_api_make_event
744 * Creates an event of 'name' and returns it.
746 * Calling this function is only forbidden during preinit.
748 * See afb_event_is_valid to check if there is an error.
750 * The event created as the name API/name where API is the name of the
753 * @param api the api that creates the event
754 * @param name the event name suffix
756 * @return the created event. Use the function afb_event_is_valid to check
757 * whether the event is valid (created) or not (error as reported by errno).
759 * @see afb_event_is_valid
761 afb_event_t afb_api_make_event(
766 ### afb_api_event_handler_add
770 * Add a specific event handler for the api
772 * The handler callback is called when an event matching the given pattern
773 * is received (it is received if broadcasted or after subscription through
774 * a call or a subcall).
776 * The handler callback receive 4 arguments:
778 * - the closure given here
779 * - the event full name
780 * - the companion JSON object of the event
781 * - the api that subscribed the event
783 * @param api the api that creates the handler
784 * @param pattern the global pattern of the event to handle
785 * @param callback the handler callback function
786 * @param closure the closure of the handler
788 * @return 0 in case of success or -1 on failure with errno set
790 * @see afb_api_on_event
791 * @see afb_api_event_handler_del
793 int afb_api_event_handler_add(
804 ### afb_api_event_handler_del
808 * Delete a specific event handler for the api
810 * @param api the api that the handler belongs to
811 * @param pattern the global pattern of the handler to remove
812 * @param closure if not NULL it will receive the closure set to the handler
814 * @return 0 in case of success or -1 on failure with errno set
816 * @see afb_api_on_event
817 * @see afb_api_event_handler_add
819 int afb_api_event_handler_del(
828 ### afb_api_get_event_loop
832 * Retrieves the common systemd's event loop of AFB
834 * @param api the api that uses the event loop
836 * @return the systemd event loop if active, NULL otherwise
838 * @see afb_api_get_user_bus
839 * @see afb_api_get_system_bus
841 struct sd_event *afb_api_get_event_loop(
845 ### afb_api_get_user_bus
849 * Retrieves the common systemd's user/session d-bus of AFB
851 * @param api the api that uses the user dbus
853 * @return the systemd user connection to dbus if active, NULL otherwise
855 * @see afb_api_get_event_loop
856 * @see afb_api_get_system_bus
858 struct sd_bus *afb_api_get_user_bus(
862 ### afb_api_get_system_bus
866 * Retrieves the common systemd's system d-bus of AFB
868 * @param api the api that uses the system dbus
870 * @return the systemd system connection to dbus if active, NULL otherwise
872 * @see afb_api_get_event_loop
873 * @see afb_api_get_user_bus
875 struct sd_bus *afb_api_get_system_bus(
880 ## Dynamic api functions
886 * Creates a new api of name 'apiname' briefly described by 'info' (that can
889 * When the pre-initialization function is given, it is a function that
890 * receives 2 parameters:
892 * - the closure as given in the call
893 * - the created api that can be initialised
895 * This pre-initialization function must return a negative value to abort
896 * the creation of the api. Otherwise, it returns a non-negative value to
899 * @param api the api that creates the other one
900 * @param apiname the name of the new api
901 * @param info the brief description of the new api (can be NULL)
902 * @param noconcurrency zero or not zero whether the new api is reentrant or not
903 * @param preinit the pre-initialization function if any (can be NULL)
904 * @param closure the closure for the pre-initialization preinit
906 * @return the created api in case of success or NULL on error
908 * @see afb_api_delete_api
910 afb_api_t afb_api_new_api(
915 int (*preinit)(void*, afb_api_t ),
919 ### afb_api_set_verbs_v2
923 * @deprecated use @ref afb_api_set_verbs_v3 instead
925 * Set the verbs of the 'api' using description of verbs of the api v2
927 * @param api the api that will get the verbs
928 * @param verbs the array of verbs to add terminated with an item with name=NULL
930 * @return 0 in case of success or -1 on failure with errno set
933 * @see afb_api_add_verb
934 * @see afb_api_set_verbs_v3
936 int afb_api_set_verbs_v2(
938 const struct afb_verb_v2 *verbs);
941 ### afb_api_set_verbs_v3
945 * Set the verbs of the 'api' using description of verbs of the api v2
947 * @param api the api that will get the verbs
948 * @param verbs the array of verbs to add terminated with an item with name=NULL
950 * @return 0 in case of success or -1 on failure with errno set
953 * @see afb_api_add_verb
954 * @see afb_api_del_verb
956 int afb_api_set_verbs_v3(
958 const struct afb_verb_v3 *verbs);
965 * Add one verb to the dynamic set of the api
967 * @param api the api to change
968 * @param verb name of the verb
969 * @param info brief description of the verb, can be NULL
970 * @param callback callback function implementing the verb
971 * @param vcbdata data for the verb callback, available through req
972 * @param auth required authorization, can be NULL
973 * @param session authorization and session requirements of the verb
974 * @param glob is the verb glob name
976 * @return 0 in case of success or -1 on failure with errno set
979 * @see afb_api_del_verb
980 * @see afb_api_set_verbs_v3
981 * @see fnmatch for matching names using glob
983 int afb_api_add_verb(
987 void (*callback)(struct afb_req_x2 *req),
989 const struct afb_auth *auth,
998 * Delete one verb from the dynamic set of the api
1000 * @param api the api to change
1001 * @param verb name of the verb to delete
1002 * @param vcbdata if not NULL will receive the vcbdata of the deleted verb
1004 * @return 0 in case of success or -1 on failure with errno set
1006 * @see afb_api_add_verb
1008 int afb_api_del_verb(
1014 ### afb_api_on_event
1018 * Set the callback 'onevent' to process events in the name of the 'api'.
1020 * This setting can be done statically using the global variable
1021 * @ref afbBindingV3.
1023 * This function replace any previously global event callback set.
1025 * When an event is received, the callback 'onevent' is called with 3 parameters
1027 * - the api that recorded the event handler
1028 * - the full name of the event
1029 * - the companion JSON object of the event
1031 * @param api the api that wants to process events
1032 * @param onevent the callback function that will process events (can be NULL
1033 * to remove event callback)
1035 * @return 0 in case of success or -1 on failure with errno set
1038 * @see afb_binding_v3
1039 * @see afb_api_event_handler_add
1040 * @see afb_api_event_handler_del
1042 int afb_api_on_event(
1047 struct json_object *object));
1054 * Set the callback 'oninit' to process initialization of the 'api'.
1056 * This setting can be done statically using the global variable
1059 * This function replace any previously initialization callback set.
1061 * This function is only valid during the pre-initialization stage.
1063 * The callback initialization function will receive one argument: the api
1066 * @param api the api that wants to process events
1067 * @param oninit the callback function that initialize the api
1069 * @return 0 in case of success or -1 on failure with errno set
1072 * @see afb_binding_v3
1074 int afb_api_on_init(
1076 int (*oninit)(afb_api_t api));
1079 ### afb_api_provide_class
1083 * Tells that the api provides a class of features. Classes are intended to
1084 * allow ordering of initializations: apis that provides a given class are
1085 * initialized before apis requiring it.
1087 * This function is only valid during the pre-initialization stage.
1089 * @param api the api that provides the classes
1090 * @param name a space separated list of the names of the provided classes
1092 * @returns 0 in case of success or a negative value in case of error.
1094 * @see afb_api_require_class
1096 int afb_api_provide_class(
1101 ### afb_api_require_class
1105 * Tells that the api requires a set of class features. Classes are intended to
1106 * allow ordering of initializations: apis that provides a given class are
1107 * initialized before apis requiring it.
1109 * This function is only valid during the pre-initialization stage.
1111 * @param api the api that requires the classes
1112 * @param name a space separated list of the names of the required classes
1114 * @returns 0 in case of success or a negative value in case of error.
1116 * @see afb_api_provide_class
1118 int afb_api_require_class(
1127 * Seal the api. After a call to this function the api can not be modified
1130 * @param api the api to be sealed
1136 ### afb_api_delete_api
1140 * Delete the given api.
1142 * It is of the responsibility of the caller to don't used the deleted api
1143 * anymore after this function returned.
1145 * @param api the api to delete
1147 * @returns 0 in case of success or a negative value in case of error.
1149 * @see afb_api_new_api
1151 int afb_api_delete_api(
1155 ### afb_api_add_alias
1159 * Create an aliased name 'as_name' for the api 'name'.
1160 * Calling this function is only allowed within preinit.
1162 * @param api the api that requires the aliasing
1163 * @param name the api to alias
1164 * @param as_name the aliased name of the aliased api
1166 * @return 0 in case of success or -1 in case of error with errno set appropriately.
1168 int afb_api_add_alias(
1171 const char *as_name);
1177 The function for legacy calls are still provided for some time because
1178 adaptation of existing code to the new call functions require a small amount
1181 ### afb_api_call_legacy
1185 * @deprecated try to use @ref afb_api_call instead
1187 * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
1188 * in the name of the binding.
1189 * The result of the call is delivered to the 'callback' function
1190 * with the 'callback_closure'.
1192 * For convenience, the function calls 'json_object_put' for 'args'.
1193 * Thus, in the case where 'args' should remain available after
1194 * the function returns, the function 'json_object_get' shall be used.
1196 * The 'callback' receives 3 arguments:
1197 * 1. 'closure' the user defined closure pointer 'closure',
1198 * 2. 'status' a status being 0 on success or negative when an error occurred,
1199 * 2. 'result' the resulting data as a JSON object.
1201 * @param api The api
1202 * @param apiname The api name of the method to call
1203 * @param verb The verb name of the method to call
1204 * @param args The arguments to pass to the method
1205 * @param callback The to call on completion
1206 * @param closure The closure to pass to the callback
1208 * @see also 'afb_api_call'
1209 * @see also 'afb_api_call_sync'
1210 * @see also 'afb_api_call_sync_legacy'
1211 * @see also 'afb_req_subcall'
1212 * @see also 'afb_req_subcall_sync'
1214 void afb_api_call_legacy(
1216 const char *apiname,
1218 struct json_object *args,
1222 struct json_object *result,
1227 ### afb_api_call_sync_legacy
1231 * @deprecated try to use @ref afb_api_call_sync instead
1233 * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb'
1234 * in the name of the binding.
1235 * 'result' will receive the response.
1237 * For convenience, the function calls 'json_object_put' for 'args'.
1238 * Thus, in the case where 'args' should remain available after
1239 * the function returns, the function 'json_object_get' shall be used.
1241 * @param api The api
1242 * @param apiname The api name of the method to call
1243 * @param verb The verb name of the method to call
1244 * @param args The arguments to pass to the method
1245 * @param result Where to store the result - should call json_object_put on it -
1247 * @returns 0 in case of success or a negative value in case of error.
1249 * @see also 'afb_api_call'
1250 * @see also 'afb_api_call_sync'
1251 * @see also 'afb_api_call_legacy'
1252 * @see also 'afb_req_subcall'
1253 * @see also 'afb_req_subcall_sync'
1255 int afb_api_call_sync_legacy(
1257 const char *apiname,
1259 struct json_object *args,
1260 struct json_object **result);
1263 iv. FUNCTIONS OF CLASS **afb_req**
1264 ============================
1268 ### afb_req_is_valid
1272 * Checks whether the request 'req' is valid or not.
1274 * @param req the request to check
1276 * @return 0 if not valid or 1 if valid.
1278 int afb_req_is_valid(
1286 * Retrieves the api that serves the request
1288 * @param req the request whose serving api is queried
1290 * @return the api serving the request
1292 afb_api_t afb_req_get_api(
1296 ### afb_req_get_vcbdata
1300 * Retrieves the callback data of the verb. This callback data is set
1301 * when the verb is created.
1303 * @param req whose verb vcbdata is queried
1305 * @return the callback data attached to the verb description
1307 void *afb_req_get_vcbdata(
1311 ### afb_req_get_called_api
1315 * Retrieve the name of the called api.
1317 * @param req the request
1319 * @return the name of the called api
1321 * @see afb_api_new_api
1322 * @see afb_api_add_alias
1324 const char *afb_req_get_called_api(
1328 ### afb_req_get_called_verb
1332 * Retrieve the name of the called verb
1334 * @param req the request
1336 * @return the name of the called verb
1338 const char *afb_req_get_called_verb(
1346 * Increments the count of references of 'req'.
1348 * @param req the request
1350 * @return returns the request req
1352 afb_req_t *afb_req_addref(
1360 * Decrement the count of references of 'req'.
1362 * @param req the request
1369 ## Logging functions
1371 ### afb_req_wants_log_level
1375 * Is the log message of 'level (as defined for syslog) required for the
1378 * @param req the request
1379 * @param level the level to check as defined for syslog:
1381 * EMERGENCY 0 System is unusable
1382 * ALERT 1 Action must be taken immediately
1383 * CRITICAL 2 Critical conditions
1384 * ERROR 3 Error conditions
1385 * WARNING 4 Warning conditions
1386 * NOTICE 5 Normal but significant condition
1387 * INFO 6 Informational
1388 * DEBUG 7 Debug-level messages
1390 * @return 0 if not required or a value not null if required
1394 int afb_req_wants_log_level(
1399 ### afb_req_vverbose
1403 * Send associated to 'req' a message described by 'fmt' and its 'args'
1404 * to the journal for the verbosity 'level'.
1406 * 'file', 'line' and 'func' are indicators of position of the code in source files
1407 * (see macros __FILE__, __LINE__ and __func__).
1409 * 'level' is defined by syslog standard:
1410 * EMERGENCY 0 System is unusable
1411 * ALERT 1 Action must be taken immediately
1412 * CRITICAL 2 Critical conditions
1413 * ERROR 3 Error conditions
1414 * WARNING 4 Warning conditions
1415 * NOTICE 5 Normal but significant condition
1416 * INFO 6 Informational
1417 * DEBUG 7 Debug-level messages
1419 * @param req the request
1420 * @param level the level of the message
1421 * @param file the source filename that emits the message or NULL
1422 * @param line the line number in the source filename that emits the message
1423 * @param func the name of the function that emits the message or NULL
1424 * @param fmt the message format as for printf
1425 * @param args the arguments to the format
1428 * @see afb_req_verbose
1430 void afb_req_vverbose(
1432 int level, const char *file,
1443 * Send associated to 'req' a message described by 'fmt' and following parameters
1444 * to the journal for the verbosity 'level'.
1446 * 'file', 'line' and 'func' are indicators of position of the code in source files
1447 * (see macros __FILE__, __LINE__ and __func__).
1449 * 'level' is defined by syslog standard:
1450 * EMERGENCY 0 System is unusable
1451 * ALERT 1 Action must be taken immediately
1452 * CRITICAL 2 Critical conditions
1453 * ERROR 3 Error conditions
1454 * WARNING 4 Warning conditions
1455 * NOTICE 5 Normal but significant condition
1456 * INFO 6 Informational
1457 * DEBUG 7 Debug-level messages
1459 * @param req the request
1460 * @param level the level of the message
1461 * @param file the source filename that emits the message or NULL
1462 * @param line the line number in the source filename that emits the message
1463 * @param func the name of the function that emits the message or NULL
1464 * @param fmt the message format as for printf
1465 * @param ... the arguments of the format 'fmt'
1469 void afb_req_verbose(
1471 int level, const char *file,
1478 ## Arguments/parameters function
1484 * Gets from the request 'req' the argument of 'name'.
1486 * Returns a PLAIN structure of type 'struct afb_arg'.
1488 * When the argument of 'name' is not found, all fields of result are set to NULL.
1490 * When the argument of 'name' is found, the fields are filled,
1491 * in particular, the field 'result.name' is set to 'name'.
1493 * There is a special name value: the empty string.
1494 * The argument of name "" is defined only if the request was made using
1495 * an HTTP POST of Content-Type "application/json". In that case, the
1496 * argument of name "" receives the value of the body of the HTTP request.
1498 * @param req the request
1499 * @param name the name of the argument to get
1501 * @return a structure describing the retrieved argument for the request
1503 * @see afb_req_value
1506 struct afb_arg afb_req_get(
1515 * Gets from the request 'req' the string value of the argument of 'name'.
1516 * Returns NULL if when there is no argument of 'name'.
1517 * Returns the value of the argument of 'name' otherwise.
1519 * Shortcut for: afb_req_get(req, name).value
1521 * @param req the request
1522 * @param name the name of the argument's value to get
1524 * @return the value as a string or NULL
1529 const char *afb_req_value(
1538 * Gets from the request 'req' the path for file attached to the argument of 'name'.
1539 * Returns NULL if when there is no argument of 'name' or when there is no file.
1540 * Returns the path of the argument of 'name' otherwise.
1542 * Shortcut for: afb_req_get(req, name).path
1544 * @param req the request
1545 * @param name the name of the argument's path to get
1547 * @return the path if any or NULL
1550 * @see afb_req_value
1552 const char *afb_req_path(
1561 * Gets from the request 'req' the json object hashing the arguments.
1563 * The returned object must not be released using 'json_object_put'.
1565 * @param req the request
1567 * @return the JSON object of the query
1570 * @see afb_req_value
1573 struct json_object *afb_req_json(
1579 The functions **success** and **fail** are still supported.
1580 These functions are now implemented as the following macros:
1583 #define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i)
1584 #define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__)
1585 #define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v)
1586 #define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i)
1587 #define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__)
1588 #define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v)
1596 * Sends a reply to the request 'req'.
1598 * The status of the reply is set to 'error' (that must be NULL on success).
1599 * Its send the object 'obj' (can be NULL) with an
1600 * informational comment 'info (can also be NULL).
1602 * For convenience, the function calls 'json_object_put' for 'obj'.
1603 * Thus, in the case where 'obj' should remain available after
1604 * the function returns, the function 'json_object_get' shall be used.
1606 * @param req the request
1607 * @param obj the replied object or NULL
1608 * @param error the error message if it is a reply error or NULL
1609 * @param info an informative text or NULL
1611 * @see afb_req_reply_v
1612 * @see afb_req_reply_f
1616 struct json_object *obj,
1625 * Same as 'afb_req_reply_f' but the arguments to the format 'info'
1626 * are given as a variable argument list instance.
1628 * For convenience, the function calls 'json_object_put' for 'obj'.
1629 * Thus, in the case where 'obj' should remain available after
1630 * the function returns, the function 'json_object_get' shall be used.
1632 * @param req the request
1633 * @param obj the replied object or NULL
1634 * @param error the error message if it is a reply error or NULL
1635 * @param info an informative text containing a format as for vprintf
1636 * @param args the va_list of arguments to the format as for vprintf
1638 * @see afb_req_reply
1639 * @see afb_req_reply_f
1642 void afb_req_reply_v(
1644 struct json_object *obj,
1654 * Same as 'afb_req_reply' but the 'info' is a formatting
1655 * string followed by arguments.
1657 * For convenience, the function calls 'json_object_put' for 'obj'.
1658 * Thus, in the case where 'obj' should remain available after
1659 * the function returns, the function 'json_object_get' shall be used.
1661 * @param req the request
1662 * @param obj the replied object or NULL
1663 * @param error the error message if it is a reply error or NULL
1664 * @param info an informative text containing a format as for printf
1665 * @param ... the arguments to the format as for printf
1667 * @see afb_req_reply
1668 * @see afb_req_reply_v
1671 void afb_req_reply_f(
1673 struct json_object *obj,
1679 ## Subcall functions
1687 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
1688 * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
1690 * For convenience, the function calls 'json_object_put' for 'args'.
1691 * Thus, in the case where 'args' should remain available after
1692 * the function returns, the function 'json_object_get' shall be used.
1694 * The 'callback' receives 5 arguments:
1695 * 1. 'closure' the user defined closure pointer 'closure',
1696 * 2. 'object' a JSON object returned (can be NULL)
1697 * 3. 'error' a string not NULL in case of error
1698 * 4. 'info' a string handling some info (can be NULL)
1701 * NOTE: For convenience, *json_object_put* is called on 'object' after the
1702 * callback returns. So, it is wrong to call *json_object_put* in the callback.
1704 * @param req The request
1705 * @param api The api name of the method to call
1706 * @param verb The verb name of the method to call
1707 * @param args The arguments to pass to the method
1708 * @param flags The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags_t
1709 * @param callback The to call on completion
1710 * @param closure The closure to pass to the callback
1712 * The flags are any combination of the following values:
1714 * - afb_req_x2_subcall_catch_events = 1
1716 * the calling API wants to receive the events from subscription
1718 * - afb_req_x2_subcall_pass_events = 2
1720 * the original request will receive the events from subscription
1722 * - afb_req_x2_subcall_on_behalf = 4
1724 * the calling API wants to use the credentials of the original request
1726 * - afb_req_x2_subcall_api_session = 8
1728 * the calling API wants to use its session instead of the one of the
1731 * @see also 'afb_req_subcall_sync'
1733 void afb_req_subcall(
1737 struct json_object *args,
1741 struct json_object *object,
1748 ### afb_req_subcall_sync
1752 * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
1753 * This call is made in the context of the request 'req'.
1754 * This call is synchronous, it waits untill completion of the request.
1755 * It returns 0 on success or a negative value on error answer.
1757 * For convenience, the function calls 'json_object_put' for 'args'.
1758 * Thus, in the case where 'args' should remain available after
1759 * the function returns, the function 'json_object_get' shall be used.
1762 * - 'afb_req_subcall_req' that is convenient to keep request alive automatically.
1763 * - 'afb_req_subcall' that doesn't keep request alive automatically.
1765 * @param req The request
1766 * @param api The api name of the method to call
1767 * @param verb The verb name of the method to call
1768 * @param args The arguments to pass to the method
1769 * @param flags The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags
1770 * @param object a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL)
1771 * @param error a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL)
1772 * @param info a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL)
1774 * @return 0 in case of success or -1 in case of error
1776 int afb_req_subcall_sync(
1780 struct json_object *args,
1782 struct json_object **object,
1789 ### afb_req_subscribe
1793 * Establishes for the client link identified by 'req' a subscription
1796 * Establishing subscription MUST be called BEFORE replying to the request.
1798 * @param req the request
1799 * @param event the event to subscribe
1801 * @return 0 in case of successful subscription or -1 in case of error.
1803 int afb_req_subscribe(
1808 ### afb_req_unsubscribe
1812 * Revokes the subscription established to the 'event' for the client
1813 * link identified by 'req'.
1814 * Returns 0 in case of successful subscription or -1 in case of error.
1816 * Revoking subscription MUST be called BEFORE replying to the request.
1818 * @param req the request
1819 * @param event the event to revoke
1821 * @return 0 in case of successful subscription or -1 in case of error.
1823 int afb_req_unsubscribe(
1828 ## Session functions
1834 * Manage the pointer stored by the binding for the client session of 'req'.
1836 * If no previous pointer is stored or if 'replace' is not zero, a new value
1837 * is generated using the function 'create_context' called with the 'closure'.
1838 * If 'create_context' is NULL the generated value is 'closure'.
1840 * When a value is created, the function 'free_context' is recorded and will
1841 * be called (with the created value as argument) to free the created value when
1842 * it is not more used.
1844 * This function is atomic: it ensures that 2 threads will not race together.
1846 * @param req the request
1847 * @param replace if not zero an existing value is replaced
1848 * @param create_context the creation function or NULL
1849 * @param free_context the destroying function or NULL
1850 * @param closure the closure to the creation function
1852 * @return the stored value
1854 void *afb_req_context(
1857 void *(*create_context)(void *closure),
1858 void (*free_context)(void*),
1862 ### afb_req_context_get
1866 * Gets the pointer stored by the binding for the session of 'req'.
1867 * When the binding has not yet recorded a pointer, NULL is returned.
1869 * Shortcut for: afb_req_context(req, 0, NULL, NULL, NULL)
1871 * @param req the request
1873 * @return the previously stored value
1875 void *afb_req_context_get(
1879 ### afb_req_context_set
1883 * Stores for the binding the pointer 'context' to the session of 'req'.
1884 * The function 'free_context' will be called when the session is closed
1885 * or if binding stores an other pointer.
1887 * Shortcut for: afb_req_context(req, 1, NULL, free_context, context)
1890 * @param req the request
1891 * @param context the context value to store
1892 * @param free_context the cleaning function for the stored context (can be NULL)
1894 void afb_req_context_set(
1897 void (*free_context)(void*));
1900 ### afb_req_context_clear
1904 * Frees the pointer stored by the binding for the session of 'req'
1905 * and sets it to NULL.
1907 * Shortcut for: afb_req_context_set(req, NULL, NULL)
1909 * @param req the request
1911 void afb_req_context_clear(
1915 ### afb_req_session_close
1919 * Closes the session associated with 'req'
1920 * and delete all associated contexts.
1922 * @param req the request
1924 void afb_req_session_close(
1928 ### afb_req_session_set_LOA
1932 * Sets the level of assurance of the session of 'req'
1933 * to 'level'. The effect of this function is subject of
1934 * security policies.
1936 * @param req the request
1937 * @param level of assurance from 0 to 7
1939 * @return 0 on success or -1 if failed.
1941 int afb_req_session_set_LOA(
1946 ## Credential/client functions
1948 ### afb_req_has_permission
1952 * Check whether the 'permission' is granted or not to the client
1953 * identified by 'req'.
1955 * @param req the request
1956 * @param permission string to check
1958 * @return 1 if the permission is granted or 0 otherwise.
1960 int afb_req_has_permission(
1962 const char *permission);
1965 ### afb_req_get_application_id
1969 * Get the application identifier of the client application for the
1972 * Returns the application identifier or NULL when the application
1973 * can not be identified.
1975 * The returned value if not NULL must be freed by the caller
1977 * @param req the request
1979 * @return the string for the application id of the client MUST BE FREED
1981 char *afb_req_get_application_id(
1989 * Get the user identifier (UID) of the client for the
1992 * @param req the request
1994 * @return -1 when the application can not be identified or the unix uid.
1997 int afb_req_get_uid(
2001 ### afb_req_get_client_info
2005 * Get informations about the client of the
2008 * Returns an object with client informations:
2010 * "pid": int, "uid": int, "gid": int,
2011 * "label": string, "id": string, "user": string,
2012 * "uuid": string, "LOA": int
2015 * If some of this information can't be computed, the field of the return
2016 * object will not be set at all.
2018 * @param req the request
2020 * @return a JSON object that must be freed using @ref json_object_put
2022 struct json_object *afb_req_get_client_info(
2028 ### afb_req_subcall_legacy
2032 * @deprecated use @ref afb_req_subcall
2034 * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
2035 * This call is made in the context of the request 'req'.
2036 * On completion, the function 'callback' is invoked with the
2037 * 'closure' given at call and two other parameters: 'iserror' and 'result'.
2038 * 'status' is 0 on success or negative when on an error reply.
2039 * 'result' is the json object of the reply, you must not call json_object_put
2042 * For convenience, the function calls 'json_object_put' for 'args'.
2043 * Thus, in the case where 'args' should remain available after
2044 * the function returns, the function 'json_object_get' shall be used.
2046 * @param req the request
2047 * @param api the name of the api to call
2048 * @param verb the name of the verb to call
2049 * @param args the arguments of the call as a JSON object
2050 * @param callback the call back that will receive the reply
2051 * @param closure the closure passed back to the callback
2053 * @see afb_req_subcall
2054 * @see afb_req_subcall_sync
2056 void afb_req_subcall_legacy(
2060 struct json_object *args,
2064 struct json_object *result,
2069 ### afb_req_subcall_sync_legacy
2073 * @deprecated use @ref afb_req_subcall_sync
2075 * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
2076 * This call is made in the context of the request 'req'.
2077 * This call is synchronous, it waits until completion of the request.
2078 * It returns 0 on success or a negative value on error answer.
2079 * The object pointed by 'result' is filled and must be released by the caller
2080 * after its use by calling 'json_object_put'.
2082 * For convenience, the function calls 'json_object_put' for 'args'.
2083 * Thus, in the case where 'args' should remain available after
2084 * the function returns, the function 'json_object_get' shall be used.
2086 * @param req the request
2087 * @param api the name of the api to call
2088 * @param verb the name of the verb to call
2089 * @param args the arguments of the call as a JSON object
2090 * @param result the pointer to the JSON object pointer that will receive the result
2092 * @return 0 on success or a negative value on error answer.
2094 * @see afb_req_subcall
2095 * @see afb_req_subcall_sync
2097 int afb_req_subcall_sync_legacy(
2101 struct json_object *args,
2102 struct json_object **result);
2105 v. FUNCTIONS OF CLASS **afb_event**
2106 ==============================
2108 ## General functions
2110 ### afb_event_is_valid
2114 * Checks whether the 'event' is valid or not.
2116 * @param event the event to check
2118 * @return 0 if not valid or 1 if valid.
2120 int afb_event_is_valid(
2128 * Gets the name associated to 'event'.
2130 * @param event the event whose name is requested
2132 * @return the name of the event
2134 * The returned name can be used until call to 'afb_event_unref'.
2135 * It shouldn't be freed.
2137 const char *afb_event_name(
2145 * Decrease the count of references to 'event'.
2146 * Call this function when the evenid is no more used.
2147 * It destroys the event_x2 when the reference count falls to zero.
2149 * @param event the event
2151 void afb_event_unref(
2155 ### afb_event_addref
2159 * Increases the count of references to 'event'
2161 * @param event the event
2165 afb_event_t *afb_event_addref(
2169 ## Pushing functions
2171 ### afb_event_broadcast
2175 * Broadcasts widely an event of 'event' with the data 'object'.
2176 * 'object' can be NULL.
2178 * For convenience, the function calls 'json_object_put' for 'object'.
2179 * Thus, in the case where 'object' should remain available after
2180 * the function returns, the function 'json_object_get' shall be used.
2182 * @param event the event to broadcast
2183 * @param object the companion object to associate to the broadcasted event (can be NULL)
2185 * @return 0 in case of success or -1 in case of error
2187 int afb_event_broadcast(
2189 struct json_object *object);
2196 * Pushes an event of 'event' with the data 'object' to its observers.
2197 * 'object' can be NULL.
2199 * For convenience, the function calls 'json_object_put' for 'object'.
2200 * Thus, in the case where 'object' should remain available after
2201 * the function returns, the function 'json_object_get' shall be used.
2203 * @param event the event to push
2204 * @param object the companion object to associate to the pushed event (can be NULL)
2207 * * 1 if at least one client listen for the event
2208 * * 0 if no more client listen for the event
2209 * * -1 in case of error (the event can't be delivered)
2213 struct json_object *object);
2216 vi. FUNCTIONS OF CLASS **afb_daemon**
2217 ============================
2219 All the functions of the class **afb_daemon** use the default api.
2220 This are internally aliased to the corresponding function of class afb_api_t.
2224 * Retrieves the common systemd's event loop of AFB
2226 struct sd_event *afb_daemon_get_event_loop();
2229 * Retrieves the common systemd's user/session d-bus of AFB
2231 struct sd_bus *afb_daemon_get_user_bus();
2234 * Retrieves the common systemd's system d-bus of AFB
2236 struct sd_bus *afb_daemon_get_system_bus();
2239 * Broadcasts widely the event of 'name' with the data 'object'.
2240 * 'object' can be NULL.
2242 * For convenience, the function calls 'json_object_put' for 'object'.
2243 * Thus, in the case where 'object' should remain available after
2244 * the function returns, the function 'json_object_get' shall be used.
2246 * Calling this function is only forbidden during preinit.
2248 * Returns the count of clients that received the event.
2250 int afb_daemon_broadcast_event(
2252 struct json_object *object);
2255 * Creates an event of 'name' and returns it.
2257 * Calling this function is only forbidden during preinit.
2259 * See afb_event_is_valid to check if there is an error.
2261 afb_event_t afb_daemon_make_event(
2265 * @deprecated use bindings version 3
2267 * Send a message described by 'fmt' and following parameters
2268 * to the journal for the verbosity 'level'.
2270 * 'file', 'line' and 'func' are indicators of position of the code in source files
2271 * (see macros __FILE__, __LINE__ and __func__).
2273 * 'level' is defined by syslog standard:
2274 * EMERGENCY 0 System is unusable
2275 * ALERT 1 Action must be taken immediately
2276 * CRITICAL 2 Critical conditions
2277 * ERROR 3 Error conditions
2278 * WARNING 4 Warning conditions
2279 * NOTICE 5 Normal but significant condition
2280 * INFO 6 Informational
2281 * DEBUG 7 Debug-level messages
2283 void afb_daemon_verbose(
2292 * @deprecated use bindings version 3
2294 * Get the root directory file descriptor. This file descriptor can
2295 * be used with functions 'openat', 'fstatat', ...
2297 * Returns the file descriptor or -1 in case of error.
2299 int afb_daemon_rootdir_get_fd();
2302 * Opens 'filename' within the root directory with 'flags' (see function openat)
2303 * using the 'locale' definition (example: "jp,en-US") that can be NULL.
2305 * Returns the file descriptor or -1 in case of error.
2307 int afb_daemon_rootdir_open_locale(
2308 const char *filename,
2310 const char *locale);
2313 * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
2314 * in this thread (later) or in an other thread.
2315 * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group')
2316 * are executed in sequence in the order of there submission.
2317 * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
2318 * At first, the job is called with 0 as signum and the given argument.
2319 * The job is executed with the monitoring of its time and some signals like SIGSEGV and
2320 * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
2321 * signum being the signal number (SIGALRM when timeout expired).
2323 * Returns 0 in case of success or -1 in case of error.
2325 int afb_daemon_queue_job(
2326 void (*callback)(int signum, void *arg),
2332 * Tells that it requires the API of "name" to exist
2333 * and if 'initialized' is not null to be initialized.
2334 * Calling this function is only allowed within init.
2336 * Returns 0 in case of success or -1 in case of error.
2338 int afb_daemon_require_api(
2343 * Create an aliased name 'as_name' for the api 'name'.
2344 * Calling this function is only allowed within preinit.
2346 * Returns 0 in case of success or -1 in case of error.
2348 int afb_daemon_add_alias(const char *name, const char *as_name);
2351 * Creates a new api of name 'api' with brief 'info'.
2353 * Returns 0 in case of success or -1 in case of error.
2355 int afb_daemon_new_api(
2359 int (*preinit)(void*, struct afb_api_x3 *),
2363 vii. FUNCTIONS OF CLASS **afb_service**
2364 ==============================
2366 All the functions of the class **afb_service** use the default api.
2368 All these function are deprecated, try to use functions of class **afb_api** instead.
2374 * @deprecated try to use @ref afb_api_call instead
2376 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
2377 * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
2379 * For convenience, the function calls 'json_object_put' for 'args'.
2380 * Thus, in the case where 'args' should remain available after
2381 * the function returns, the function 'json_object_get' shall be used.
2383 * The 'callback' receives 5 arguments:
2384 * 1. 'closure' the user defined closure pointer 'closure',
2385 * 2. 'object' a JSON object returned (can be NULL)
2386 * 3. 'error' a string not NULL in case of error but NULL on success
2387 * 4. 'info' a string handling some info (can be NULL)
2390 * @param api The api name of the method to call
2391 * @param verb The verb name of the method to call
2392 * @param args The arguments to pass to the method
2393 * @param callback The to call on completion
2394 * @param closure The closure to pass to the callback
2397 * @see afb_req_subcall
2398 * @see afb_req_subcall_sync
2399 * @see afb_api_call_sync
2401 void afb_service_call(
2404 struct json_object *args,
2407 struct json_object *object,
2414 ## afb_service_call_sync
2418 * @deprecated try to use @ref afb_api_call_sync instead
2420 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
2421 * 'result' will receive the response.
2423 * For convenience, the function calls 'json_object_put' for 'args'.
2424 * Thus, in the case where 'args' should remain available after
2425 * the function returns, the function 'json_object_get' shall be used.
2427 * @param api The api name of the method to call
2428 * @param verb The verb name of the method to call
2429 * @param args The arguments to pass to the method
2430 * @param object Where to store the returned object - should call json_object_put on it - can be NULL
2431 * @param error Where to store the copied returned error - should call free on it - can be NULL
2432 * @param info Where to store the copied returned info - should call free on it - can be NULL
2434 * @returns 0 in case of success or a negative value in case of error.
2436 * @see afb_req_subcall
2437 * @see afb_req_subcall_sync
2440 int afb_service_call_sync(
2443 struct json_object *args,
2444 struct json_object **object,
2449 ## afb_service_call_legacy
2453 * @deprecated try to use @ref afb_api_call instead
2455 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb'
2456 * in the name of the binding.
2457 * The result of the call is delivered to the 'callback' function with
2458 * the 'callback_closure'.
2460 * For convenience, the function calls 'json_object_put' for 'args'.
2461 * Thus, in the case where 'args' should remain available after
2462 * the function returns, the function 'json_object_get' shall be used.
2464 * The 'callback' receives 3 arguments:
2465 * 1. 'closure' the user defined closure pointer 'closure',
2466 * 2. 'status' a status being 0 on success or negative when an error occurred,
2467 * 2. 'result' the resulting data as a JSON object.
2469 * @param api The api name of the method to call
2470 * @param verb The verb name of the method to call
2471 * @param args The arguments to pass to the method
2472 * @param callback The to call on completion
2473 * @param closure The closure to pass to the callback
2475 * @see also 'afb_api_call'
2476 * @see also 'afb_api_call_sync'
2477 * @see also 'afb_api_call_sync_legacy'
2478 * @see also 'afb_req_subcall'
2479 * @see also 'afb_req_subcall_sync'
2481 void afb_service_call_legacy(
2484 struct json_object *args,
2488 struct json_object *result,
2493 ## afb_service_call_sync_legacy
2497 * @deprecated try to use @ref afb_api_call_sync instead
2499 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the
2500 * name of the binding. 'result' will receive the response.
2502 * For convenience, the function calls 'json_object_put' for 'args'.
2503 * Thus, in the case where 'args' should remain available after
2504 * the function returns, the function 'json_object_get' shall be used.
2506 * @param api The api name of the method to call
2507 * @param verb The verb name of the method to call
2508 * @param args The arguments to pass to the method
2509 * @param result Where to store the result - should call json_object_put on it -
2511 * @returns 0 in case of success or a negative value in case of error.
2513 * @see also 'afb_api_call'
2514 * @see also 'afb_api_call_sync'
2515 * @see also 'afb_api_call_legacy'
2516 * @see also 'afb_req_subcall'
2517 * @see also 'afb_req_subcall_sync'
2519 int afb_service_call_sync_legacy(
2522 struct json_object *args,
2523 struct json_object **result);