summaryrefslogtreecommitdiffstats
path: root/include/afb/afb-api-x3.h
diff options
context:
space:
mode:
authorJosé Bollo <jose.bollo@iot.bzh>2018-06-19 20:16:28 +0200
committerJosé Bollo <jose.bollo@iot.bzh>2018-06-22 09:48:48 +0200
commit525e9eaa644ca92fad23adfbb7c3119ae8b57a30 (patch)
tree41de59627ccc937450daf4da6488efd4f4b2f3c2 /include/afb/afb-api-x3.h
parent9e15212d26916f59fae2be6d9e618ae9b75a4f40 (diff)
Improve documentation of api v3
The documentation is improved to reflect the new version. Tune the options Change-Id: I894c3db3bc0c10e89db66a9a51a9ad049bb8c0c4 Signed-off-by: José Bollo <jose.bollo@iot.bzh>
Diffstat (limited to 'include/afb/afb-api-x3.h')
-rw-r--r--include/afb/afb-api-x3.h164
1 files changed, 112 insertions, 52 deletions
diff --git a/include/afb/afb-api-x3.h b/include/afb/afb-api-x3.h
index 81323ef5..9f06172b 100644
--- a/include/afb/afb-api-x3.h
+++ b/include/afb/afb-api-x3.h
@@ -20,6 +20,9 @@
#include "afb-verbosity.h"
#include "afb-api-x3-itf.h"
+/** @defgroup AFB_API
+ * @{ */
+
/**
* Get the name of the 'api'.
*
@@ -30,7 +33,8 @@
* The returned value must not be changed nor freed.
*/
static inline
-const char *afb_api_x3_name(struct afb_api_x3 *api)
+const char *afb_api_x3_name(
+ struct afb_api_x3 *api)
{
return api->apiname;
}
@@ -45,7 +49,8 @@ const char *afb_api_x3_name(struct afb_api_x3 *api)
* @see afb_api_x3_set_userdata
*/
static inline
-void *afb_api_x3_get_userdata(struct afb_api_x3 *api)
+void *afb_api_x3_get_userdata(
+ struct afb_api_x3 *api)
{
return api->userdata;
}
@@ -59,7 +64,9 @@ void *afb_api_x3_get_userdata(struct afb_api_x3 *api)
* @see afb_api_x3_get_userdata
*/
static inline
-void afb_api_x3_set_userdata(struct afb_api_x3 *api, void *value)
+void afb_api_x3_set_userdata(
+ struct afb_api_x3 *api,
+ void *value)
{
api->userdata = value;
}
@@ -84,16 +91,18 @@ void afb_api_x3_set_userdata(struct afb_api_x3 *api, void *value)
* @see syslog
*/
static inline
-int afb_api_x3_wants_log_level(struct afb_api_x3 *api, int level)
+int afb_api_x3_wants_log_level(
+ struct afb_api_x3 *api,
+ int level)
{
return AFB_SYSLOG_MASK_WANT(api->logmask, level);
}
/**
- * Send to the journal with the log 'level' a message described
+ * Send to the journal with the logging 'level' a message described
* by 'fmt' applied to the va-list 'args'.
*
- * 'file', 'line' and 'func' are indicators of position of the code in source files
+ * 'file', 'line' and 'func' are indicators of code position in source files
* (see macros __FILE__, __LINE__ and __func__).
*
* 'level' is defined by syslog standard:
@@ -111,7 +120,7 @@ int afb_api_x3_wants_log_level(struct afb_api_x3 *api, int level)
* @param level the level of the message
* @param file the source file that logs the messages or NULL
* @param line the line in the source file that logs the message
- * @param func the name of the function in the source file that logs
+ * @param func the name of the function in the source file that logs (or NULL)
* @param fmt the format of the message as in printf
* @param args the arguments to the format string of the message as a va_list
*
@@ -119,7 +128,14 @@ int afb_api_x3_wants_log_level(struct afb_api_x3 *api, int level)
* @see printf
*/
static inline
-void afb_api_x3_vverbose(struct afb_api_x3 *api, int level, const char *file, int line, const char *func, const char *fmt, va_list args)
+void afb_api_x3_vverbose(
+ struct afb_api_x3 *api,
+ int level,
+ const char *file,
+ int line,
+ const char *func,
+ const char *fmt,
+ va_list args)
{
api->itf->vverbose(api, level, file, line, func, fmt, args);
}
@@ -145,7 +161,7 @@ void afb_api_x3_vverbose(struct afb_api_x3 *api, int level, const char *file, in
* @param level the level of the message
* @param file the source file that logs the messages or NULL
* @param line the line in the source file that logs the message
- * @param func the name of the function in the source file that logs
+ * @param func the name of the function in the source file that logs (or NULL)
* @param fmt the format of the message as in printf
* @param ... the arguments to the format string of the message
*
@@ -180,7 +196,8 @@ void afb_api_x3_verbose(
* @see afb_api_x3_get_system_bus
*/
static inline
-struct sd_event *afb_api_x3_get_event_loop(struct afb_api_x3 *api)
+struct sd_event *afb_api_x3_get_event_loop(
+ struct afb_api_x3 *api)
{
return api->itf->get_event_loop(api);
}
@@ -196,7 +213,8 @@ struct sd_event *afb_api_x3_get_event_loop(struct afb_api_x3 *api)
* @see afb_api_x3_get_system_bus
*/
static inline
-struct sd_bus *afb_api_x3_get_user_bus(struct afb_api_x3 *api)
+struct sd_bus *afb_api_x3_get_user_bus(
+ struct afb_api_x3 *api)
{
return api->itf->get_user_bus(api);
}
@@ -213,7 +231,8 @@ struct sd_bus *afb_api_x3_get_user_bus(struct afb_api_x3 *api)
*/
static inline
-struct sd_bus *afb_api_x3_get_system_bus(struct afb_api_x3 *api)
+struct sd_bus *afb_api_x3_get_system_bus(
+ struct afb_api_x3 *api)
{
return api->itf->get_system_bus(api);
}
@@ -228,10 +247,10 @@ struct sd_bus *afb_api_x3_get_system_bus(struct afb_api_x3 *api)
* This can be used to get the path of the root directory using:
*
* ```C
- * char buffer[MAX_PATH];
- * int dirfd = afb_api_x3_rootdir_get_fd(api);
- * snprintf(buffer, sizeof buffer, "/proc/self/fd/%d", dirfd);
- * readlink(buffer, buffer, sizeof buffer);
+ * char buffer[MAX_PATH], proc[100];
+ * int dirfd = afb_api_rootdir_get_fd(api);
+ * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd);
+ * readlink(proc, buffer, sizeof buffer);
* ```
*
* But note that within AGL this is the value given by the environment variable
@@ -244,7 +263,8 @@ struct sd_bus *afb_api_x3_get_system_bus(struct afb_api_x3 *api)
* @see afb_api_x3_rootdir_open_locale
*/
static inline
-int afb_api_x3_rootdir_get_fd(struct afb_api_x3 *api)
+int afb_api_x3_rootdir_get_fd(
+ struct afb_api_x3 *api)
{
return api->itf->rootdir_get_fd(api);
}
@@ -273,7 +293,11 @@ int afb_api_x3_rootdir_get_fd(struct afb_api_x3 *api)
* @see afb_api_x3_rootdir_get_fd
*/
static inline
-int afb_api_x3_rootdir_open_locale(struct afb_api_x3 *api, const char *filename, int flags, const char *locale)
+int afb_api_x3_rootdir_open_locale(
+ struct afb_api_x3 *api,
+ const char *filename,
+ int flags,
+ const char *locale)
{
return api->itf->rootdir_open_locale(api, filename, flags, locale);
}
@@ -297,14 +321,14 @@ int afb_api_x3_rootdir_open_locale(struct afb_api_x3 *api, const char *filename,
* - int signum: the signal catched if any or zero at the beginning
* - void *arg: the parameter 'argument'
*
- * A typical implmentation of the job callback is:
+ * A typical implementation of the job callback is:
*
* ```C
* void my_job_cb(int signum, void *arg)
* {
* struct myarg_t *myarg = arg;
* if (signum)
- * AFB_API_ERROR(myarg->api, "job interupted with signal %s", strsignal(signum));
+ * AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
* else
* really_do_my_job(myarg);
* }
@@ -319,27 +343,38 @@ int afb_api_x3_rootdir_open_locale(struct afb_api_x3 *api, const char *filename,
* @return 0 in case of success or -1 in case of error with errno set appropriately.
*/
static inline
-int afb_api_x3_queue_job(struct afb_api_x3 *api, void (*callback)(int signum, void *arg), void *argument, void *group, int timeout)
+int afb_api_x3_queue_job(
+ struct afb_api_x3 *api,
+ void (*callback)(int signum, void *arg),
+ void *argument,
+ void *group,
+ int timeout)
{
return api->itf->queue_job(api, callback, argument, group, timeout);
}
/**
- * Tells that it requires the API of "name" to exist
- * and if 'initialized' is not null to be initialized.
+ * Check that it requires the API of 'name'.
+ * If 'initialized' is not zero it request the API to be
+ * initialized, implying its initialization if needed.
+ *
* Calling this function is only allowed within init.
*
* A single request allows to require multiple apis.
*
* @param api the api that requires the other api by its name
- * @param name a space separated list of the names of the required api
+ * @param name a space separated list of required api names
* @param initialized if zero, the api is just required to exist. If not zero,
- * the api is required to exist and to be initialized.
+ * the api is required to exist and to be initialized at return of the call
+ * (initializing it if needed and possible as a side effect of the call).
*
* @return 0 in case of success or -1 in case of error with errno set appropriately.
*/
static inline
-int afb_api_x3_require_api(struct afb_api_x3 *api, const char *name, int initialized)
+int afb_api_x3_require_api(
+ struct afb_api_x3 *api,
+ const char *name,
+ int initialized)
{
return api->itf->require_api(api, name, initialized);
}
@@ -355,7 +390,10 @@ int afb_api_x3_require_api(struct afb_api_x3 *api, const char *name, int initial
* @return 0 in case of success or -1 in case of error with errno set appropriately.
*/
static inline
-int afb_api_x3_add_alias(struct afb_api_x3 *api, const char *name, const char *as_name)
+int afb_api_x3_add_alias(
+ struct afb_api_x3 *api,
+ const char *name,
+ const char *as_name)
{
return api->itf->add_alias(api, name, as_name);
}
@@ -380,7 +418,10 @@ int afb_api_x3_add_alias(struct afb_api_x3 *api, const char *name, const char *a
* @return the count of clients that received the event.
*/
static inline
-int afb_api_x3_broadcast_event(struct afb_api_x3 *api, const char *name, struct json_object *object)
+int afb_api_x3_broadcast_event(
+ struct afb_api_x3 *api,
+ const char *name,
+ struct json_object *object)
{
return api->itf->event_broadcast(api, name, object);
}
@@ -404,7 +445,9 @@ int afb_api_x3_broadcast_event(struct afb_api_x3 *api, const char *name, struct
* @see afb_event_is_valid
*/
static inline
-struct afb_event_x2 *afb_api_x3_make_event_x2(struct afb_api_x3 *api, const char *name)
+struct afb_event_x2 *afb_api_x3_make_event_x2(
+ struct afb_api_x3 *api,
+ const char *name)
{
return api->itf->event_make(api, name);
}
@@ -439,12 +482,15 @@ struct afb_event_x2 *afb_api_x3_make_event_x2(struct afb_api_x3 *api, const char
*/
static inline
void afb_api_x3_call_legacy(
- struct afb_api_x3 *api,
- const char *apiname,
- const char *verb,
- struct json_object *args,
- void (*callback)(void *closure, int status, struct json_object *result, struct afb_api_x3 *api),
- void *closure)
+ struct afb_api_x3 *api,
+ const char *apiname,
+ const char *verb,
+ struct json_object *args,
+ void (*callback)(void *closure,
+ int status,
+ struct json_object *result,
+ struct afb_api_x3 *api),
+ void *closure)
{
api->itf->legacy_call(api, apiname, verb, args, callback, closure);
}
@@ -475,11 +521,11 @@ void afb_api_x3_call_legacy(
*/
static inline
int afb_api_x3_call_sync_legacy(
- struct afb_api_x3 *api,
- const char *apiname,
- const char *verb,
- struct json_object *args,
- struct json_object **result)
+ struct afb_api_x3 *api,
+ const char *apiname,
+ const char *verb,
+ struct json_object *args,
+ struct json_object **result)
{
return api->itf->legacy_call_sync(api, apiname, verb, args, result);
}
@@ -511,12 +557,12 @@ int afb_api_x3_call_sync_legacy(
*/
static inline
struct afb_api_x3 *afb_api_x3_new_api(
- struct afb_api_x3 *api,
- const char *apiname,
- const char *info,
- int noconcurrency,
- int (*preinit)(void*, struct afb_api_x3 *),
- void *closure)
+ struct afb_api_x3 *api,
+ const char *apiname,
+ const char *info,
+ int noconcurrency,
+ int (*preinit)(void*, struct afb_api_x3 *),
+ void *closure)
{
return api->itf->api_new_api(api, apiname, info, noconcurrency, preinit, closure);
}
@@ -537,8 +583,8 @@ struct afb_api_x3 *afb_api_x3_new_api(
*/
static inline
int afb_api_x3_set_verbs_v2(
- struct afb_api_x3 *api,
- const struct afb_verb_v2 *verbs)
+ struct afb_api_x3 *api,
+ const struct afb_verb_v2 *verbs)
{
return api->itf->api_set_verbs_v2(api, verbs);
}
@@ -624,7 +670,10 @@ int afb_api_x3_del_verb(
static inline
int afb_api_x3_on_event(
struct afb_api_x3 *api,
- void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object))
+ void (*onevent)(
+ struct afb_api_x3 *api,
+ const char *event,
+ struct json_object *object))
{
return api->itf->api_set_on_event(api, onevent);
}
@@ -719,7 +768,11 @@ static inline
int afb_api_x3_event_handler_add(
struct afb_api_x3 *api,
const char *pattern,
- void (*callback)(void *, const char*, struct json_object*, struct afb_api_x3*),
+ void (*callback)(
+ void *,
+ const char*,
+ struct json_object*,
+ struct afb_api_x3*),
void *closure)
{
return api->itf->event_handler_add(api, pattern, callback, closure);
@@ -779,7 +832,12 @@ void afb_api_x3_call(
const char *apiname,
const char *verb,
struct json_object *args,
- void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_api_x3 *api),
+ void (*callback)(
+ void *closure,
+ struct json_object *object,
+ const char *error,
+ const char * info,
+ struct afb_api_x3 *api),
void *closure)
{
api->itf->call(api, apiname, verb, args, callback, closure);
@@ -850,7 +908,7 @@ int afb_api_x3_provide_class(
* This function is only valid during the pre-initialization stage.
*
* @param api the api that requires the classes
- * @param name a space separated list of the names of the requireded classes
+ * @param name a space separated list of the names of the required classes
*
* @returns 0 in case of success or a negative value in case of error.
*
@@ -882,3 +940,5 @@ int afb_api_x3_delete_api(
{
return api->itf->delete_api(api);
}
+
+/** @} */