/*
- * Copyright (C) 2016, 2017, 2018 "IoT.bzh"
+ * Copyright (C) 2015-2020 "IoT.bzh"
* Author: José Bollo <jose.bollo@iot.bzh>
*
* Licensed under the Apache License, Version 2.0 (the "License");
#include "afb-verbosity.h"
#include "afb-api-x3-itf.h"
+/** @defgroup AFB_API
+ * @{ */
+
/**
* Get the name of the 'api'.
*
* 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;
}
* @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;
}
* @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;
}
* @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:
* @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
*
* @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);
}
* @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
*
* @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);
}
* @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);
}
*/
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);
}
* 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
* @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);
}
* @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);
}
* - 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);
* }
* @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);
}
* @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);
}
* @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);
}
* @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);
}
*/
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);
}
*/
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);
}
* @param info the brief description of the new api (can be NULL)
* @param noconcurrency zero or not zero whether the new api is reentrant or not
* @param preinit the pre-initialization function if any (can be NULL)
- * @param closure the closure for the pre-initialization \ref preinit
+ * @param closure the closure for the pre-initialization preinit
*
- * @return 0 in case of success or -1 on failure with errno set
+ * @return the created api in case of success or NULL on error
*
* @see afb_api_x3_delete_api
*/
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);
}
* @see afb_api_x3_add_verb
* @see afb_api_x3_set_verbs_v3
*/
-static inline
+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);
}
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);
}
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);
* 4. 'info' a string handling some info (can be NULL)
* 5. 'api' the api
*
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
* @param api The api that makes the call
* @param apiname The api name of the method to call
* @param verb The verb name of the method to call
* @param callback The to call on completion
* @param closure The closure to pass to the callback
*
- *
* @see afb_req_subcall
* @see afb_req_subcall_sync
* @see afb_api_x3_call_sync
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);
* 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.
*
{
return api->itf->delete_api(api);
}
+
+/**
+ * Settings of the api.
+ *
+ * Get the settings of the API. The settings are recorded
+ * as a JSON object. The returned object should not be modified.
+ * It MUST NOT be released using json_object_put.
+ *
+ * @param api the api whose settings are required
+ *
+ * @returns The setting object.
+ */
+static inline
+struct json_object *afb_api_x3_settings(
+ struct afb_api_x3 *api)
+{
+ return api->itf->settings(api);
+}
+
+/** @} */
Code Review / src / app-framework-binder.git / blobdiff