summaryrefslogtreecommitdiffstats
path: root/include/afb
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
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')
-rw-r--r--include/afb/afb-api-x3-itf.h4
-rw-r--r--include/afb/afb-api-x3.h164
-rw-r--r--include/afb/afb-arg.h5
-rw-r--r--include/afb/afb-auth.h5
-rw-r--r--include/afb/afb-binding-postdefs.h3
-rw-r--r--include/afb/afb-binding-predefs.h4
-rw-r--r--include/afb/afb-binding-v3.h4
-rw-r--r--include/afb/afb-binding.hpp11
-rw-r--r--include/afb/afb-daemon-itf-x1.h4
-rw-r--r--include/afb/afb-daemon-v1.h5
-rw-r--r--include/afb/afb-daemon-v2.h5
-rw-r--r--include/afb/afb-event-x1-itf.h4
-rw-r--r--include/afb/afb-event-x1.h4
-rw-r--r--include/afb/afb-event-x2-itf.h4
-rw-r--r--include/afb/afb-event-x2.h4
-rw-r--r--include/afb/afb-req-v1.h5
-rw-r--r--include/afb/afb-req-v2.h5
-rw-r--r--include/afb/afb-req-x1-itf.h5
-rw-r--r--include/afb/afb-req-x1.h5
-rw-r--r--include/afb/afb-req-x2-itf.h12
-rw-r--r--include/afb/afb-req-x2.h51
-rw-r--r--include/afb/afb-service-itf-x1.h4
-rw-r--r--include/afb/afb-service-v1.h4
-rw-r--r--include/afb/afb-service-v2.h4
-rw-r--r--include/afb/afb-verbosity.h36
25 files changed, 287 insertions, 74 deletions
diff --git a/include/afb/afb-api-x3-itf.h b/include/afb/afb-api-x3-itf.h
index 38b29196..b8cfadf6 100644
--- a/include/afb/afb-api-x3-itf.h
+++ b/include/afb/afb-api-x3-itf.h
@@ -30,6 +30,9 @@ struct afb_auth;
struct afb_verb_v2;
struct afb_verb_v3;
+/** @addtogroup AFB_API
+ * @{ */
+
/**
* Structure for the APIv3
*/
@@ -260,3 +263,4 @@ struct afb_api_x3_itf
struct afb_api_x3 *api);
};
+/** @} */
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);
}
+
+/** @} */
diff --git a/include/afb/afb-arg.h b/include/afb/afb-arg.h
index de3fb9b5..61b78afa 100644
--- a/include/afb/afb-arg.h
+++ b/include/afb/afb-arg.h
@@ -17,6 +17,9 @@
#pragma once
+/** @addtogroup AFB_REQ
+ * @{ */
+
/**
* Describes an argument (or parameter) of a request.
*
@@ -31,3 +34,5 @@ struct afb_arg
/**< when the request is finalized this file is removed */
};
+
+/** @} */
diff --git a/include/afb/afb-auth.h b/include/afb/afb-auth.h
index 3ce78666..31cbf6f8 100644
--- a/include/afb/afb-auth.h
+++ b/include/afb/afb-auth.h
@@ -17,6 +17,10 @@
#pragma once
+/** @defgroup AFB_AUTH
+ * @{ */
+
+
/**
* Enumeration for authority (Session/Token/Assurance) definitions.
*
@@ -72,3 +76,4 @@ struct afb_auth
const struct afb_auth *next;
};
+/** @} */ \ No newline at end of file
diff --git a/include/afb/afb-binding-postdefs.h b/include/afb/afb-binding-postdefs.h
index 93cd46ef..9de630ab 100644
--- a/include/afb/afb-binding-postdefs.h
+++ b/include/afb/afb-binding-postdefs.h
@@ -74,8 +74,11 @@ typedef struct afb_binding_v3 afb_binding_t;
typedef struct afb_event_x2 *afb_event_t;
typedef struct afb_req_x2 *afb_req_t;
typedef struct afb_api_x3 *afb_api_t;
+typedef enum afb_req_subcall_flags afb_req_subcall_flags_t;
#define afbBindingExport afbBindingV3
+#define afbBindingRoot afbBindingV3root
+#define afbBindingEntry afbBindingV3entry
/* compatibility with previous versions */
diff --git a/include/afb/afb-binding-predefs.h b/include/afb/afb-binding-predefs.h
index f1765edb..f8806165 100644
--- a/include/afb/afb-binding-predefs.h
+++ b/include/afb/afb-binding-predefs.h
@@ -282,10 +282,12 @@
#define afb_req_x2_get_uid afb_req_get_uid
#define afb_req_x2_get_client_info afb_req_get_client_info
+#define afb_req_x2_subcall_flags afb_req_subcall_flags
#define afb_req_x2_subcall_catch_events afb_req_subcall_catch_events
#define afb_req_x2_subcall_pass_events afb_req_subcall_pass_events
#define afb_req_x2_subcall_on_behalf afb_req_subcall_on_behalf
-
+#define afb_req_x2_subcall_api_session afb_req_subcall_api_session
+
#define afb_event_x2 afb_event
#define afb_event_x2_is_valid afb_event_is_valid
#define afb_event_x2_broadcast afb_event_broadcast
diff --git a/include/afb/afb-binding-v3.h b/include/afb/afb-binding-v3.h
index ece3f1c4..52a3a8d2 100644
--- a/include/afb/afb-binding-v3.h
+++ b/include/afb/afb-binding-v3.h
@@ -257,6 +257,6 @@ extern const struct afb_binding_v3 afbBindingV3;
#define afb_daemon_require_api_v3(...) afb_api_require_api(afbBindingV3root,__VA_ARGS__)
#define afb_daemon_add_alias_v3(...) afb_api_add_alias(afbBindingV3root,__VA_ARGS__)
-#define afb_service_call_v3(...) afb_api_call_legacy(afbBindingV3root,__VA_ARGS__)
-#define afb_service_call_sync_v3(...) afb_api_call_sync_legacy(afbBindingV3root,__VA_ARGS__)
+#define afb_service_call_v3(...) afb_api_call(afbBindingV3root,__VA_ARGS__)
+#define afb_service_call_sync_v3(...) afb_api_call_sync(afbBindingV3root,__VA_ARGS__)
diff --git a/include/afb/afb-binding.hpp b/include/afb/afb-binding.hpp
index 27715f39..21847722 100644
--- a/include/afb/afb-binding.hpp
+++ b/include/afb/afb-binding.hpp
@@ -496,16 +496,21 @@ inline bool wants_debugs()
{ return AFB_SYSLOG_MASK_WANT_DEBUG(logmask()); }
#if AFB_BINDING_VERSION >= 3
-inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, int iserror, struct json_object *result, afb_api_t api), void *closure)
+inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, struct json_object *result, const char *error, const char *info, afb_api_t api), void *closure)
{
afb_service_call(api, verb, args, callback, closure);
}
template <class T>
-inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(T*closure, int iserror, struct json_object *result, afb_api_t api), T *closure)
+inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(T*closure, struct json_object *result, const char *error, const char *info, afb_api_t api), T *closure)
{
afb_service_call(api, verb, args, reinterpret_cast<void(*)(void*,int,json_object*,afb_api_t)>(callback), reinterpret_cast<void*>(closure));
}
+
+inline bool callsync(const char *api, const char *verb, struct json_object *args, struct json_object *&result, char *&error, char *&info)
+{
+ return !!afb_service_call_sync(api, verb, args, &result, &error, &info);
+}
#else
inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, int iserror, struct json_object *result), void *closure)
{
@@ -517,12 +522,12 @@ inline void call(const char *api, const char *verb, struct json_object *args, vo
{
afb_service_call(api, verb, args, reinterpret_cast<void(*)(void*,int,json_object*)>(callback), reinterpret_cast<void*>(closure));
}
-#endif
inline bool callsync(const char *api, const char *verb, struct json_object *args, struct json_object *&result)
{
return !!afb_service_call_sync(api, verb, args, &result);
}
+#endif
/*************************************************************************/
/* declaration of the binding's authorization s */
diff --git a/include/afb/afb-daemon-itf-x1.h b/include/afb/afb-daemon-itf-x1.h
index 3ca12eba..744892d4 100644
--- a/include/afb/afb-daemon-itf-x1.h
+++ b/include/afb/afb-daemon-itf-x1.h
@@ -27,6 +27,9 @@ struct afb_req_x1;
struct afb_event_x1;
struct afb_api_x3;
+/** @defgroup AFB_DAEMON
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -89,3 +92,4 @@ struct afb_daemon_x1
struct afb_api_x3 *closure; /**< the closure when calling these functions */
};
+/** @} */
diff --git a/include/afb/afb-daemon-v1.h b/include/afb/afb-daemon-v1.h
index d84517d1..c268bb83 100644
--- a/include/afb/afb-daemon-v1.h
+++ b/include/afb/afb-daemon-v1.h
@@ -19,6 +19,9 @@
#include "afb-daemon-itf-x1.h"
+/** @addtogroup AFB_DAEMON
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -236,3 +239,5 @@ static inline int afb_daemon_new_api_v1(
{
return -!daemon.itf->new_api(daemon.closure, api, info, noconcurrency, preinit, closure);
}
+
+/** @} */
diff --git a/include/afb/afb-daemon-v2.h b/include/afb/afb-daemon-v2.h
index f3c2c904..65e4afbc 100644
--- a/include/afb/afb-daemon-v2.h
+++ b/include/afb/afb-daemon-v2.h
@@ -19,6 +19,9 @@
#include "afb-daemon-itf-x1.h"
+/** @addtogroup AFB_DAEMON
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -214,3 +217,5 @@ static inline int afb_daemon_new_api_v2(
return -!(afb_get_daemon_v2().itf->new_api(afb_get_daemon_v2().closure, api, info, noconcurrency, preinit, closure));
}
+/** @} */
+
diff --git a/include/afb/afb-event-x1-itf.h b/include/afb/afb-event-x1-itf.h
index afd033b8..b2c582e4 100644
--- a/include/afb/afb-event-x1-itf.h
+++ b/include/afb/afb-event-x1-itf.h
@@ -19,6 +19,9 @@
#include "afb-event-x2-itf.h"
+/** @addtogroup AFB_EVENT
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -30,3 +33,4 @@ struct afb_event_x1
struct afb_event_x2 *closure; /**< the closure argument for functions of 'itf' */
};
+/** @} */
diff --git a/include/afb/afb-event-x1.h b/include/afb/afb-event-x1.h
index 1fc7696f..039a14fd 100644
--- a/include/afb/afb-event-x1.h
+++ b/include/afb/afb-event-x1.h
@@ -19,6 +19,9 @@
#include "afb-event-x1-itf.h"
+/** @addtogroup AFB_EVENT
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -109,3 +112,4 @@ static inline void afb_event_x1_addref(struct afb_event_x1 event)
event.itf->addref(event.closure);
}
+/** @} */
diff --git a/include/afb/afb-event-x2-itf.h b/include/afb/afb-event-x2-itf.h
index ecc42c79..b2a01c7b 100644
--- a/include/afb/afb-event-x2-itf.h
+++ b/include/afb/afb-event-x2-itf.h
@@ -20,6 +20,9 @@
struct afb_event_x2;
struct afb_event_x2_itf;
+/** @addtogroup AFB_EVENT
+ * @{ */
+
/**
* Interface for handling event_x2.
*
@@ -55,3 +58,4 @@ struct afb_event_x2
const struct afb_event_x2_itf *itf; /**< the interface functions to use */
};
+/** @} */
diff --git a/include/afb/afb-event-x2.h b/include/afb/afb-event-x2.h
index f0a27877..9732cad1 100644
--- a/include/afb/afb-event-x2.h
+++ b/include/afb/afb-event-x2.h
@@ -19,6 +19,9 @@
#include "afb-event-x2-itf.h"
+/** @defgroup AFB_EVENT
+ * @{ */
+
/**
* Checks whether the 'event' is valid or not.
*
@@ -111,3 +114,4 @@ static inline struct afb_event_x2 *afb_event_x2_addref(
return event->itf->addref(event);
}
+/** @} */
diff --git a/include/afb/afb-req-v1.h b/include/afb/afb-req-v1.h
index 40fb3b85..a6e202bd 100644
--- a/include/afb/afb-req-v1.h
+++ b/include/afb/afb-req-v1.h
@@ -20,6 +20,9 @@
#include <stdlib.h>
#include "afb-req-x1.h"
+/** @addtogroup AFB_REQ
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -54,3 +57,5 @@ static inline struct afb_req_x1 afb_req_unstore_x1_v1(struct afb_req_x1 *req)
return result;
}
+
+/** @} */
diff --git a/include/afb/afb-req-v2.h b/include/afb/afb-req-v2.h
index f7901908..75ef841d 100644
--- a/include/afb/afb-req-v2.h
+++ b/include/afb/afb-req-v2.h
@@ -19,6 +19,9 @@
#include "afb-req-x1.h"
+/** @addtogroup AFB_REQ
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -32,3 +35,5 @@ static inline struct afb_stored_req *afb_req_x1_store_v2(struct afb_req_x1 req)
return req.itf->legacy_store_req(req.closure);
}
+
+/** @} */
diff --git a/include/afb/afb-req-x1-itf.h b/include/afb/afb-req-x1-itf.h
index dce936d1..7d82ad03 100644
--- a/include/afb/afb-req-x1-itf.h
+++ b/include/afb/afb-req-x1-itf.h
@@ -19,6 +19,9 @@
#include "afb-req-x2-itf.h"
+/** @addtogroup AFB_REQ
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -30,3 +33,5 @@ struct afb_req_x1
struct afb_req_x2 *closure; /**< the closure argument for functions of 'itf' */
};
+
+/** @} */
diff --git a/include/afb/afb-req-x1.h b/include/afb/afb-req-x1.h
index cea17d0c..d9fa1bea 100644
--- a/include/afb/afb-req-x1.h
+++ b/include/afb/afb-req-x1.h
@@ -20,6 +20,9 @@
#include "afb-req-x1-itf.h"
#include "afb-event-x1.h"
+/** @addtogroup AFB_REQ
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -451,3 +454,5 @@ static inline struct json_object *afb_req_x1_get_client_info(struct afb_req_x1 r
}
+
+/** @} */
diff --git a/include/afb/afb-req-x2-itf.h b/include/afb/afb-req-x2-itf.h
index 9de7a214..c76329d0 100644
--- a/include/afb/afb-req-x2-itf.h
+++ b/include/afb/afb-req-x2-itf.h
@@ -29,6 +29,9 @@ struct afb_event_x2;
struct afb_api_x3;
struct afb_stored_req;
+/** @addtogroup AFB_REQ
+ * @{ */
+
/**
* structure for the request
*/
@@ -62,15 +65,16 @@ struct afb_req_x2
};
/**
- * subcall modes
+ * subcall flags
*
* When making subcalls, it is now possible to explicitely set the subcall
- * mode to a combination of the following mode using binary OR.
+ * mode to a combination of the following flags using binary OR.
*
- * In particular, the following combination of modes are to be known:
+ * In particular, the following combination of flags are to be known:
*
* - for **subcall** having a similar behaviour to the subcalls of bindings
* version 1 and 2: afb_req_x2_subcall_pass_events|afb_req_x2_subcall_on_behalf
+ *
* - for **subcall** having the behaviour of the **call**:
* afb_req_x2_subcall_catch_events|afb_req_x2_subcall_api_session
*
@@ -304,3 +308,5 @@ struct afb_req_x2_itf
char **info);
};
+
+/** @} */
diff --git a/include/afb/afb-req-x2.h b/include/afb/afb-req-x2.h
index 70ffab80..bd4bc767 100644
--- a/include/afb/afb-req-x2.h
+++ b/include/afb/afb-req-x2.h
@@ -20,6 +20,9 @@
#include "afb-req-x2-itf.h"
#include "afb-api-x3.h"
+/** @defgroup AFB_REQ
+ * @{ */
+
/**
* Checks whether the request 'req' is valid or not.
*
@@ -560,6 +563,46 @@ int afb_req_x2_subcall_sync_legacy(
}
/**
+ * Send associated to 'req' a message described by 'fmt' and its 'args'
+ * to the journal for the verbosity 'level'.
+ *
+ * 'file', 'line' and 'func' are indicators of position of the code in source files
+ * (see macros __FILE__, __LINE__ and __func__).
+ *
+ * 'level' is defined by syslog standard:
+ * EMERGENCY 0 System is unusable
+ * ALERT 1 Action must be taken immediately
+ * CRITICAL 2 Critical conditions
+ * ERROR 3 Error conditions
+ * WARNING 4 Warning conditions
+ * NOTICE 5 Normal but significant condition
+ * INFO 6 Informational
+ * DEBUG 7 Debug-level messages
+ *
+ * @param req the request
+ * @param level the level of the message
+ * @param file the source filename that emits the message or NULL
+ * @param line the line number in the source filename that emits the message
+ * @param func the name of the function that emits the message or NULL
+ * @param fmt the message format as for printf
+ * @param args the arguments to the format 'fmt'
+ *
+ * @see printf
+ * @see afb_req_x2_verbose
+ */
+static inline
+void afb_req_x2_vverbose(
+ struct afb_req_x2 *req,
+ int level, const char *file,
+ int line,
+ const char * func,
+ const char *fmt,
+ va_list args)
+{
+ req->itf->vverbose(req, level, file, line, func, fmt, args);
+}
+
+/**
* Send associated to 'req' a message described by 'fmt' and following parameters
* to the journal for the verbosity 'level'.
*
@@ -582,9 +625,10 @@ int afb_req_x2_subcall_sync_legacy(
* @param line the line number in the source filename that emits the message
* @param func the name of the function that emits the message or NULL
* @param fmt the message format as for printf
- * @param ... the arguments of the printf
+ * @param ... the arguments of the format 'fmt'
*
* @see printf
+ * @see afb_req_x2_vverbose
*/
__attribute__((format(printf, 6, 7)))
static inline
@@ -598,7 +642,7 @@ void afb_req_x2_verbose(
{
va_list args;
va_start(args, fmt);
- req->itf->vverbose(req, level, file, line, func, fmt, args);
+ afb_req_x2_verbose(req, level, file, line, func, fmt, args);
va_end(args);
}
@@ -756,3 +800,6 @@ int afb_req_x2_subcall_sync(
{
return req->itf->subcallsync(req, api, verb, args, flags, object, error, info);
}
+
+
+/** @} */
diff --git a/include/afb/afb-service-itf-x1.h b/include/afb/afb-service-itf-x1.h
index fcdd08e1..9e36fd0d 100644
--- a/include/afb/afb-service-itf-x1.h
+++ b/include/afb/afb-service-itf-x1.h
@@ -19,6 +19,9 @@
struct afb_api_x3;
+/** @defgroup AFB_SERVICE
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -49,3 +52,4 @@ struct afb_service_x1
struct afb_api_x3 *closure;
};
+/** @} */
diff --git a/include/afb/afb-service-v1.h b/include/afb/afb-service-v1.h
index a3265af8..e4a4eee1 100644
--- a/include/afb/afb-service-v1.h
+++ b/include/afb/afb-service-v1.h
@@ -19,6 +19,9 @@
#include "afb-service-itf-x1.h"
+/** @addtogroup AFB_SERVICE
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -84,3 +87,4 @@ static inline int afb_service_call_sync_v1(
return service.itf->call_sync(service.closure, api, verb, args, result);
}
+/** @} */
diff --git a/include/afb/afb-service-v2.h b/include/afb/afb-service-v2.h
index da59786d..1601a660 100644
--- a/include/afb/afb-service-v2.h
+++ b/include/afb/afb-service-v2.h
@@ -19,6 +19,9 @@
#include "afb-service-itf-x1.h"
+/** @addtogroup AFB_SERVICE
+ * @{ */
+
/**
* @deprecated use bindings version 3
*
@@ -80,3 +83,4 @@ static inline int afb_service_call_sync_v2(
return afb_get_service_v2().itf->call_sync(afb_get_service_v2().closure, api, verb, args, result);
}
+/** @} */
diff --git a/include/afb/afb-verbosity.h b/include/afb/afb-verbosity.h
index dd34f841..288205bd 100644
--- a/include/afb/afb-verbosity.h
+++ b/include/afb/afb-verbosity.h
@@ -17,11 +17,14 @@
#pragma once
-#define AFB_VERBOSITY_LEVEL_ERROR 0
-#define AFB_VERBOSITY_LEVEL_WARNING 1
-#define AFB_VERBOSITY_LEVEL_NOTICE 2
-#define AFB_VERBOSITY_LEVEL_INFO 3
-#define AFB_VERBOSITY_LEVEL_DEBUG 4
+/** @defgroup AFB_LOGGING
+ * @{ */
+
+#define AFB_VERBOSITY_LEVEL_ERROR 0 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_ERROR */
+#define AFB_VERBOSITY_LEVEL_WARNING 1 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_WARNING */
+#define AFB_VERBOSITY_LEVEL_NOTICE 2 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_NOTICE */
+#define AFB_VERBOSITY_LEVEL_INFO 3 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_INFO */
+#define AFB_VERBOSITY_LEVEL_DEBUG 4 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_DEBUG */
#define AFB_SYSLOG_LEVEL_EMERGENCY 0
#define AFB_SYSLOG_LEVEL_ALERT 1
@@ -32,13 +35,13 @@
#define AFB_SYSLOG_LEVEL_INFO 6
#define AFB_SYSLOG_LEVEL_DEBUG 7
-#define AFB_VERBOSITY_LEVEL_WANT(verbosity,level) ((verbosity) >= (level))
+#define AFB_VERBOSITY_LEVEL_WANT(verbosity,level) ((verbosity) >= (level)) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT */
-#define AFB_VERBOSITY_LEVEL_WANT_ERROR(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_ERROR)
-#define AFB_VERBOSITY_LEVEL_WANT_WARNING(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_WARNING)
-#define AFB_VERBOSITY_LEVEL_WANT_NOTICE(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_NOTICE)
-#define AFB_VERBOSITY_LEVEL_WANT_INFO(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_INFO)
-#define AFB_VERBOSITY_LEVEL_WANT_DEBUG(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_DEBUG)
+#define AFB_VERBOSITY_LEVEL_WANT_ERROR(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_ERROR) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_ERROR */
+#define AFB_VERBOSITY_LEVEL_WANT_WARNING(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_WARNING) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_WARNING */
+#define AFB_VERBOSITY_LEVEL_WANT_NOTICE(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_NOTICE) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_NOTICE */
+#define AFB_VERBOSITY_LEVEL_WANT_INFO(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_INFO) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_INFO */
+#define AFB_VERBOSITY_LEVEL_WANT_DEBUG(x) AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_DEBUG) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_DEBUG */
#define AFB_SYSLOG_MASK_WANT(verbomask,level) ((verbomask) & (1 << (level)))
@@ -54,6 +57,16 @@
#define AFB_SYSLOG_LEVEL_FROM_VERBOSITY(x) ((x) + (AFB_SYSLOG_LEVEL_ERROR - AFB_VERBOSITY_LEVEL_ERROR))
#define AFB_SYSLOG_LEVEL_TO_VERBOSITY(x) ((x) + (AFB_VERBOSITY_LEVEL_ERROR - AFB_SYSLOG_LEVEL_ERROR))
+/**
+ * Transform a mask of verbosity to its significant level of verbosity.
+ *
+ * @param verbomask the mask
+ *
+ * @return the upper level that is not null, truncated to AFB_SYSLOG_LEVEL_DEBUG
+ *
+ * @example _afb_verbomask_to_upper_level_(5) -> 2
+ * @example _afb_verbomask_to_upper_level_(16) -> 4
+ */
static inline int _afb_verbomask_to_upper_level_(int verbomask)
{
int result = 0;
@@ -62,3 +75,4 @@ static inline int _afb_verbomask_to_upper_level_(int verbomask)
return result;
}
+/** @} */ \ No newline at end of file