1 Functions of class **afb_api**
2 ============================
10 * Get the name of the 'api'.
12 * @param api the api whose name is to be returned
14 * @return the name of the api.
16 * The returned value must not be changed nor freed.
18 const char *afb_api_name(
22 ### afb_api_get_userdata
26 * Get the "userdata" pointer of the 'api'
28 * @param api the api whose user's data is to be returned
30 * @return the user's data pointer of the api.
32 * @see afb_api_set_userdata
34 void *afb_api_get_userdata(
38 ### afb_api_set_userdata
42 * Set the "userdata" pointer of the 'api' to 'value'
44 * @param api the api whose user's data is to be set
45 * @param value the data to set
47 * @see afb_api_get_userdata
49 void afb_api_set_userdata(
54 ### afb_api_require_api
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.
62 * Calling this function is only allowed within init.
64 * A single request allows to require multiple apis.
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).
72 * @return 0 in case of success or -1 in case of error with errno set appropriately.
74 int afb_api_require_api(
81 ## Verbosity functions
83 ### afb_api_wants_log_level
87 * Is the log message of 'level (as defined for syslog) required for the api?
89 * @param api the api to check
90 * @param level the level to check as defined for syslog:
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
101 * @return 0 if not required or a value not null if required
105 int afb_api_wants_log_level(
114 * Send to the journal with the logging 'level' a message described
115 * by 'fmt' applied to the va-list 'args'.
117 * 'file', 'line' and 'func' are indicators of code position in source files
118 * (see macros __FILE__, __LINE__ and __func__).
120 * 'level' is defined by syslog standard:
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
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
142 void afb_api_vverbose(
156 * Send to the journal with the log 'level' a message described
157 * by 'fmt' and following parameters.
159 * 'file', 'line' and 'func' are indicators of position of the code in source files
160 * (see macros __FILE__, __LINE__ and __func__).
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
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
183 void afb_api_verbose(
193 ## Data retrieval functions
195 ### afb_api_rootdir_get_fd
199 * Get the root directory file descriptor. This file descriptor can
200 * be used with functions 'openat', 'fstatat', ...
202 * CAUTION, manipulate this descriptor with care, in particular, don't close
205 * This can be used to get the path of the root directory using:
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);
212 * But note that within AGL this is the value given by the environment variable
213 * AFM_APP_INSTALL_DIR.
215 * @param api the api that uses the directory file descriptor
217 * @return the file descriptor of the root directory.
219 * @see afb_api_rootdir_open_locale
221 int afb_api_rootdir_get_fd(
225 ### afb_api_rootdir_open_locale
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.
232 * The filename must be relative to the root of the bindings.
234 * The opening mode must be for read or write but not for O_CREAT.
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
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
245 * @return the file descriptor or -1 in case of error and errno is set with the
249 * @see afb_api_rootdir_get_fd
251 int afb_api_rootdir_open_locale(
253 const char *filename,
258 ## Calls and job functions
264 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
265 * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
267 * For convenience, the function calls 'json_object_put' for 'args'.
268 * Thus, in the case where 'args' should remain available after
269 * the function returns, the function 'json_object_get' shall be used.
271 * The 'callback' receives 5 arguments:
272 * 1. 'closure' the user defined closure pointer 'closure',
273 * 2. 'object' a JSON object returned (can be NULL)
274 * 3. 'error' a string not NULL in case of error but NULL on success
275 * 4. 'info' a string handling some info (can be NULL)
278 * @param api The api that makes the call
279 * @param apiname The api name of the method to call
280 * @param verb The verb name of the method to call
281 * @param args The arguments to pass to the method
282 * @param callback The to call on completion
283 * @param closure The closure to pass to the callback
286 * @see afb_req_subcall
287 * @see afb_req_subcall_sync
288 * @see afb_api_call_sync
294 struct json_object *args,
297 struct json_object *object,
304 ### afb_api_call_sync
308 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
309 * 'result' will receive the response.
311 * For convenience, the function calls 'json_object_put' for 'args'.
312 * Thus, in the case where 'args' should remain available after
313 * the function returns, the function 'json_object_get' shall be used.
315 * @param api The api that makes the call
316 * @param apiname The api name of the method to call
317 * @param verb The verb name of the method to call
318 * @param args The arguments to pass to the method
319 * @param object Where to store the returned object - should call json_object_put on it - can be NULL
320 * @param error Where to store the copied returned error - should call free on it - can be NULL
321 * @param info Where to store the copied returned info - should call free on it - can be NULL
323 * @returns 0 in case of success or a negative value in case of error.
325 * @see afb_req_subcall
326 * @see afb_req_subcall_sync
329 int afb_api_call_sync(
333 struct json_object *args,
334 struct json_object **object,
339 ### afb_api_queue_job
343 * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
344 * in this thread (later) or in an other thread.
346 * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group')
347 * are executed in sequence in the order of there submission.
349 * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
350 * At first, the job is called with 0 as signum and the given argument.
352 * The job is executed with the monitoring of its time and some signals like SIGSEGV and
353 * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
354 * signum being the signal number (SIGALRM when timeout expired).
356 * When executed, the callback function receives 2 arguments:
358 * - int signum: the signal catched if any or zero at the beginning
359 * - void *arg: the parameter 'argument'
361 * A typical implementation of the job callback is:
363 * void my_job_cb(int signum, void *arg)
365 * struct myarg_t *myarg = arg;
367 * AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
369 * really_do_my_job(myarg);
372 * @param api the api that queue the job
373 * @param callback the job as a callback function
374 * @param argument the argument to pass to the queued job
375 * @param group the group of the job, NULL if no group
376 * @param timeout the timeout of execution of the job
378 * @return 0 in case of success or -1 in case of error with errno set appropriately.
380 int afb_api_queue_job(
382 void (*callback)(int signum, void *arg),
390 ### afb_api_broadcast_event
394 * Broadcasts widely the event of 'name' with the data 'object'.
395 * 'object' can be NULL.
397 * For convenience, the function calls 'json_object_put' for 'object'.
398 * Thus, in the case where 'object' should remain available after
399 * the function returns, the function 'json_object_get' shall be used.
401 * Calling this function is only forbidden during preinit.
403 * The event sent as the name API/name where API is the name of the
406 * @param api the api that broadcast the event
407 * @param name the event name suffix
408 * @param object the object that comes with the event
410 * @return the count of clients that received the event.
412 int afb_api_broadcast_event(
415 struct json_object *object);
418 ### afb_api_make_event
422 * Creates an event of 'name' and returns it.
424 * Calling this function is only forbidden during preinit.
426 * See afb_event_is_valid to check if there is an error.
428 * The event created as the name API/name where API is the name of the
431 * @param api the api that creates the event
432 * @param name the event name suffix
434 * @return the created event. Use the function afb_event_is_valid to check
435 * whether the event is valid (created) or not (error as reported by errno).
437 * @see afb_event_is_valid
439 afb_event_t afb_api_make_event(
444 ### afb_api_event_handler_add
448 * Add a specific event handler for the api
450 * The handler callback is called when an event matching the given pattern
451 * is received (it is received if broadcasted or after subscription through
452 * a call or a subcall).
454 * The handler callback receive 4 arguments:
456 * - the closure given here
457 * - the event full name
458 * - the companion JSON object of the event
459 * - the api that subscribed the event
461 * @param api the api that creates the handler
462 * @param pattern the global pattern of the event to handle
463 * @param callback the handler callback function
464 * @param closure the closure of the handler
466 * @return 0 in case of success or -1 on failure with errno set
468 * @see afb_api_on_event
469 * @see afb_api_event_handler_del
471 int afb_api_event_handler_add(
482 ### afb_api_event_handler_del
486 * Delete a specific event handler for the api
488 * @param api the api that the handler belongs to
489 * @param pattern the global pattern of the handler to remove
490 * @param closure if not NULL it will receive the closure set to the handler
492 * @return 0 in case of success or -1 on failure with errno set
494 * @see afb_api_on_event
495 * @see afb_api_event_handler_add
497 int afb_api_event_handler_del(
506 ### afb_api_get_event_loop
510 * Retrieves the common systemd's event loop of AFB
512 * @param api the api that uses the event loop
514 * @return the systemd event loop if active, NULL otherwise
516 * @see afb_api_get_user_bus
517 * @see afb_api_get_system_bus
519 struct sd_event *afb_api_get_event_loop(
523 ### afb_api_get_user_bus
527 * Retrieves the common systemd's user/session d-bus of AFB
529 * @param api the api that uses the user dbus
531 * @return the systemd user connection to dbus if active, NULL otherwise
533 * @see afb_api_get_event_loop
534 * @see afb_api_get_system_bus
536 struct sd_bus *afb_api_get_user_bus(
540 ### afb_api_get_system_bus
544 * Retrieves the common systemd's system d-bus of AFB
546 * @param api the api that uses the system dbus
548 * @return the systemd system connection to dbus if active, NULL otherwise
550 * @see afb_api_get_event_loop
551 * @see afb_api_get_user_bus
553 struct sd_bus *afb_api_get_system_bus(
558 ## Dynamic api functions
564 * Creates a new api of name 'apiname' briefly described by 'info' (that can
567 * When the pre-initialization function is given, it is a function that
568 * receives 2 parameters:
570 * - the closure as given in the call
571 * - the created api that can be initialised
573 * This pre-initialization function must return a negative value to abort
574 * the creation of the api. Otherwise, it returns a non-negative value to
577 * @param api the api that creates the other one
578 * @param apiname the name of the new api
579 * @param info the brief description of the new api (can be NULL)
580 * @param noconcurrency zero or not zero whether the new api is reentrant or not
581 * @param preinit the pre-initialization function if any (can be NULL)
582 * @param closure the closure for the pre-initialization preinit
584 * @return the created api in case of success or NULL on error
586 * @see afb_api_delete_api
588 afb_api_t afb_api_new_api(
593 int (*preinit)(void*, afb_api_t ),
597 ### afb_api_set_verbs_v2
601 * @deprecated use @ref afb_api_set_verbs_v3 instead
603 * Set the verbs of the 'api' using description of verbs of the api v2
605 * @param api the api that will get the verbs
606 * @param verbs the array of verbs to add terminated with an item with name=NULL
608 * @return 0 in case of success or -1 on failure with errno set
611 * @see afb_api_add_verb
612 * @see afb_api_set_verbs_v3
614 int afb_api_set_verbs_v2(
616 const struct afb_verb_v2 *verbs);
619 ### afb_api_set_verbs_v3
623 * Set the verbs of the 'api' using description of verbs of the api v2
625 * @param api the api that will get the verbs
626 * @param verbs the array of verbs to add terminated with an item with name=NULL
628 * @return 0 in case of success or -1 on failure with errno set
631 * @see afb_api_add_verb
632 * @see afb_api_del_verb
634 int afb_api_set_verbs_v3(
636 const struct afb_verb_v3 *verbs);
643 * Add one verb to the dynamic set of the api
645 * @param api the api to change
646 * @param verb name of the verb
647 * @param info brief description of the verb, can be NULL
648 * @param callback callback function implementing the verb
649 * @param vcbdata data for the verb callback, available through req
650 * @param auth required authorization, can be NULL
651 * @param session authorization and session requirements of the verb
652 * @param glob is the verb glob name
654 * @return 0 in case of success or -1 on failure with errno set
657 * @see afb_api_del_verb
658 * @see afb_api_set_verbs_v3
659 * @see fnmatch for matching names using glob
661 int afb_api_add_verb(
665 void (*callback)(struct afb_req_x2 *req),
667 const struct afb_auth *auth,
676 * Delete one verb from the dynamic set of the api
678 * @param api the api to change
679 * @param verb name of the verb to delete
680 * @param vcbdata if not NULL will receive the vcbdata of the deleted verb
682 * @return 0 in case of success or -1 on failure with errno set
684 * @see afb_api_add_verb
686 int afb_api_del_verb(
696 * Set the callback 'onevent' to process events in the name of the 'api'.
698 * This setting can be done statically using the global variable
701 * This function replace any previously global event callback set.
703 * When an event is received, the callback 'onevent' is called with 3 parameters
705 * - the api that recorded the event handler
706 * - the full name of the event
707 * - the companion JSON object of the event
709 * @param api the api that wants to process events
710 * @param onevent the callback function that will process events (can be NULL
711 * to remove event callback)
713 * @return 0 in case of success or -1 on failure with errno set
716 * @see afb_binding_v3
717 * @see afb_api_event_handler_add
718 * @see afb_api_event_handler_del
720 int afb_api_on_event(
725 struct json_object *object));
732 * Set the callback 'oninit' to process initialization of the 'api'.
734 * This setting can be done statically using the global variable
737 * This function replace any previously initialization callback set.
739 * This function is only valid during the pre-initialization stage.
741 * The callback initialization function will receive one argument: the api
744 * @param api the api that wants to process events
745 * @param oninit the callback function that initialize the api
747 * @return 0 in case of success or -1 on failure with errno set
750 * @see afb_binding_v3
754 int (*oninit)(afb_api_t api));
757 ### afb_api_provide_class
761 * Tells that the api provides a class of features. Classes are intended to
762 * allow ordering of initializations: apis that provides a given class are
763 * initialized before apis requiring it.
765 * This function is only valid during the pre-initialization stage.
767 * @param api the api that provides the classes
768 * @param name a space separated list of the names of the provided classes
770 * @returns 0 in case of success or a negative value in case of error.
772 * @see afb_api_require_class
774 int afb_api_provide_class(
779 ### afb_api_require_class
783 * Tells that the api requires a set of class features. Classes are intended to
784 * allow ordering of initializations: apis that provides a given class are
785 * initialized before apis requiring it.
787 * This function is only valid during the pre-initialization stage.
789 * @param api the api that requires the classes
790 * @param name a space separated list of the names of the required classes
792 * @returns 0 in case of success or a negative value in case of error.
794 * @see afb_api_provide_class
796 int afb_api_require_class(
805 * Seal the api. After a call to this function the api can not be modified
808 * @param api the api to be sealed
814 ### afb_api_delete_api
818 * Delete the given api.
820 * It is of the responsibility of the caller to don't used the deleted api
821 * anymore after this function returned.
823 * @param api the api to delete
825 * @returns 0 in case of success or a negative value in case of error.
827 * @see afb_api_new_api
829 int afb_api_delete_api(
833 ### afb_api_add_alias
837 * Create an aliased name 'as_name' for the api 'name'.
838 * Calling this function is only allowed within preinit.
840 * @param api the api that requires the aliasing
841 * @param name the api to alias
842 * @param as_name the aliased name of the aliased api
844 * @return 0 in case of success or -1 in case of error with errno set appropriately.
846 int afb_api_add_alias(
849 const char *as_name);
855 The function for legacy calls are still provided for some time because
856 adaptation of existing code to the new call functions require a small amount
859 ### afb_api_call_legacy
863 * @deprecated try to use @ref afb_api_call instead
865 * * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
866 * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
868 * For convenience, the function calls 'json_object_put' for 'args'.
869 * Thus, in the case where 'args' should remain available after
870 * the function returns, the function 'json_object_get' shall be used.
872 * The 'callback' receives 3 arguments:
873 * 1. 'closure' the user defined closure pointer 'closure',
874 * 2. 'status' a status being 0 on success or negative when an error occurred,
875 * 2. 'result' the resulting data as a JSON object.
878 * @param apiname The api name of the method to call
879 * @param verb The verb name of the method to call
880 * @param args The arguments to pass to the method
881 * @param callback The to call on completion
882 * @param closure The closure to pass to the callback
884 * @see also 'afb_api_call'
885 * @see also 'afb_api_call_sync'
886 * @see also 'afb_api_call_sync_legacy'
887 * @see also 'afb_req_subcall'
888 * @see also 'afb_req_subcall_sync'
890 void afb_api_call_legacy(
894 struct json_object *args,
898 struct json_object *result,
903 ### afb_api_call_sync_legacy
907 * @deprecated try to use @ref afb_api_call_sync instead
909 * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
910 * 'result' will receive the response.
912 * For convenience, the function calls 'json_object_put' for 'args'.
913 * Thus, in the case where 'args' should remain available after
914 * the function returns, the function 'json_object_get' shall be used.
917 * @param apiname The api name of the method to call
918 * @param verb The verb name of the method to call
919 * @param args The arguments to pass to the method
920 * @param result Where to store the result - should call json_object_put on it -
922 * @returns 0 in case of success or a negative value in case of error.
924 * @see also 'afb_api_call'
925 * @see also 'afb_api_call_sync'
926 * @see also 'afb_api_call_legacy'
927 * @see also 'afb_req_subcall'
928 * @see also 'afb_req_subcall_sync'
930 int afb_api_call_sync_legacy(
934 struct json_object *args,
935 struct json_object **result);