2 * Copyright (C) 2016-2019 "IoT.bzh"
3 * Author: José Bollo <jose.bollo@iot.bzh>
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
18 /**< @file afb/afb-binding-v3.h */
22 /******************************************************************************/
25 #include "afb-event-x2.h"
26 #include "afb-req-x2.h"
27 #include "afb-session-x2.h"
28 #include "afb-api-x3.h"
30 /******************************************************************************/
33 * @page validity-v3 Validity of a binding v3
35 * A binding V3 MUST have at least two exported symbols of name:
37 * - @ref afbBindingV3root
38 * - @ref afbBindingV3 and/or @ref afbBindingV3entry
40 * @ref afbBindingV3root is automatically created when **AFB_BINDING_VERSION == 3**
41 * without programmer action, as a hidden variable linked as *weak*.
43 * The symbols @ref afbBindingV3 and **afbBindingV3entry** are under control
46 * The symbol @ref afbBindingV3 if defined is used, as in binding v2, to describe
47 * an API that will be declared during pre-initialization of bindings.
49 * The symbol @ref afbBindingV3entry if defined will be called during
52 * If @ref afbBindingV3entry and @ref afbBindingV3 are both defined, it is an
53 * error to fill the field @ref preinit of @ref afbBindingV3.
56 * @see afbBindingV3root
57 * @see afbBindingV3entry
62 * Description of one verb as provided for binding API version 3
66 /** name of the verb, NULL only at end of the array */
69 /** callback function implementing the verb */
70 void (*callback)(struct afb_req_x2 *req);
72 /** required authorization, can be NULL */
73 const struct afb_auth *auth;
75 /** some info about the verb, can be NULL */
78 /**< data for the verb callback */
81 /** authorization and session requirements of the verb */
84 /** is the verb glob name */
89 * Description of the bindings of type version 3
93 /** api name for the binding, can't be NULL */
96 /** textual specification of the binding, can be NULL */
97 const char *specification;
99 /** some info about the api, can be NULL */
102 /** array of descriptions of verbs terminated by a NULL name, can be NULL */
103 const struct afb_verb_v3 *verbs;
105 /** callback at load of the binding */
106 int (*preinit)(struct afb_api_x3 *api);
108 /** callback for starting the service */
109 int (*init)(struct afb_api_x3 *api);
111 /** callback for handling events */
112 void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
114 /** userdata for afb_api_x3 */
117 /** space separated list of provided class(es) */
118 const char *provide_class;
120 /** space separated list of required class(es) */
121 const char *require_class;
123 /** space separated list of required API(es) */
124 const char *require_api;
126 /** avoids concurrent requests to verbs */
127 unsigned noconcurrency: 1;
131 * Default root binding's api that can be used when no explicit context is
134 * When @ref afbBindingV3 is defined, this variable records the corresponding
135 * api handler. Otherwise, it points to an fake handles that allows logging
138 * @see afbBindingV3entry
140 * @see @ref validity-v3
142 #if AFB_BINDING_VERSION != 3
145 struct afb_api_x3 *afbBindingV3root __attribute__((weak));
148 * Pre-initialization function.
150 * If this function is defined and exported in the produced binding
151 * (shared object), it will be called during pre-initialization with the
152 * rootapi defined by \ref afbBindingV3root
154 * @param rootapi the root api (equals to afbBindingV3root)
156 * @return the function must return a negative integer on error to abort the
157 * initialization of the binding. Any positive or zero returned value is a
158 * interpreted as a success.
160 * @see afbBindingV3root
162 * @see @ref validity-v3
164 extern int afbBindingV3entry(struct afb_api_x3 *rootapi);
167 * Static definition of the root api of the binding.
169 * This symbol if defined describes the API of the binding.
171 * If it is not defined then the function @ref afbBindingV3entry must be defined
173 * @see afbBindingV3root
174 * @see afbBindingV3entry
175 * @see @ref validity-v3
177 extern const struct afb_binding_v3 afbBindingV3;
179 #include "afb-auth.h"
180 #include "afb-session-x2.h"
181 #include "afb-verbosity.h"
183 #include "afb-event-x2.h"
184 #include "afb-req-x2.h"
185 #include "afb-api-x3.h"
188 * Macros for logging messages
191 #if defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DATA)
193 # define AFB_API_VERBOSE_V3(api,level,...) \
194 do { if(level <= AFB_VERBOSITY_LEVEL_ERROR) \
195 afb_api_x3_verbose(api,level,__FILE__,__LINE__,NULL,__VA_ARGS__); \
196 else afb_api_x3_verbose(api,level,__FILE__,__LINE__,NULL); } while(0)
198 # define AFB_REQ_VERBOSE_V3(req,level,...) \
199 do { if(level <= AFB_VERBOSITY_LEVEL_ERROR) \
200 afb_req_x2_verbose(req,level,__FILE__,__LINE__,NULL,__VA_ARGS__); \
201 else afb_req_x2_verbose(req,level,__FILE__,__LINE__,NULL); } while(0)
203 #elif defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS)
205 # define AFB_API_VERBOSE_V3(api,level,...) \
206 afb_api_x3_verbose(api,level,NULL,0,NULL,__VA_ARGS__)
208 # define AFB_REQ_VERBOSE_V3(req,level,...) \
209 afb_req_x2_verbose(req,level,NULL,0,NULL,__VA_ARGS__)
213 # define AFB_API_VERBOSE_V3(api,level,...) \
214 afb_api_x3_verbose(api,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
216 # define AFB_REQ_VERBOSE_V3(req,level,...) \
217 afb_req_x2_verbose(req,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
221 #define _AFB_API_LOGGING_V3_(api,llevel,...) \
222 do{ if(afb_api_wants_log_level((api),(llevel))) AFB_API_VERBOSE_V3((api),(llevel),__VA_ARGS__); }while(0)
223 #define _AFB_REQ_LOGGING_V3_(req,llevel,...) \
224 do{ if(afb_req_wants_log_level((req),(llevel))) AFB_REQ_VERBOSE_V3((req),(llevel),__VA_ARGS__); }while(0)
226 #define AFB_API_ERROR_V3(api,...) _AFB_API_LOGGING_V3_(api,AFB_SYSLOG_LEVEL_ERROR,__VA_ARGS__)
227 #define AFB_API_WARNING_V3(api,...) _AFB_API_LOGGING_V3_(api,AFB_SYSLOG_LEVEL_WARNING,__VA_ARGS__)
228 #define AFB_API_NOTICE_V3(api,...) _AFB_API_LOGGING_V3_(api,AFB_SYSLOG_LEVEL_NOTICE,__VA_ARGS__)
229 #define AFB_API_INFO_V3(api,...) _AFB_API_LOGGING_V3_(api,AFB_SYSLOG_LEVEL_INFO,__VA_ARGS__)
230 #define AFB_API_DEBUG_V3(api,...) _AFB_API_LOGGING_V3_(api,AFB_SYSLOG_LEVEL_DEBUG,__VA_ARGS__)
232 #define AFB_REQ_ERROR_V3(req,...) _AFB_REQ_LOGGING_V3_(req,AFB_SYSLOG_LEVEL_ERROR,__VA_ARGS__)
233 #define AFB_REQ_WARNING_V3(req,...) _AFB_REQ_LOGGING_V3_(req,AFB_SYSLOG_LEVEL_WARNING,__VA_ARGS__)
234 #define AFB_REQ_NOTICE_V3(req,...) _AFB_REQ_LOGGING_V3_(req,AFB_SYSLOG_LEVEL_NOTICE,__VA_ARGS__)
235 #define AFB_REQ_INFO_V3(req,...) _AFB_REQ_LOGGING_V3_(req,AFB_SYSLOG_LEVEL_INFO,__VA_ARGS__)
236 #define AFB_REQ_DEBUG_V3(req,...) _AFB_REQ_LOGGING_V3_(req,AFB_SYSLOG_LEVEL_DEBUG,__VA_ARGS__)
238 #define AFB_ERROR_V3(...) AFB_API_ERROR_V3(afbBindingV3root,__VA_ARGS__)
239 #define AFB_WARNING_V3(...) AFB_API_WARNING_V3(afbBindingV3root,__VA_ARGS__)
240 #define AFB_NOTICE_V3(...) AFB_API_NOTICE_V3(afbBindingV3root,__VA_ARGS__)
241 #define AFB_INFO_V3(...) AFB_API_INFO_V3(afbBindingV3root,__VA_ARGS__)
242 #define AFB_DEBUG_V3(...) AFB_API_DEBUG_V3(afbBindingV3root,__VA_ARGS__)
244 #define afb_get_root_api_v3() (afbBindingV3root)
245 #define afb_get_logmask_v3() (afbBindingV3root->logmask)
246 #define afb_get_verbosity_v3() AFB_SYSLOG_LEVEL_TO_VERBOSITY(_afb_verbomask_to_upper_level_(afbBindingV3root->logmask))
248 #define afb_daemon_get_event_loop_v3() afb_api_get_event_loop(afbBindingV3root)
249 #define afb_daemon_get_user_bus_v3() afb_api_get_user_bus(afbBindingV3root)
250 #define afb_daemon_get_system_bus_v3() afb_api_get_system_bus(afbBindingV3root)
251 #define afb_daemon_broadcast_event_v3(...) afb_api_broadcast_event(afbBindingV3root,__VA_ARGS__)
252 #define afb_daemon_make_event_v3(...) afb_api_make_event(afbBindingV3root,__VA_ARGS__)
253 #define afb_daemon_verbose_v3(...) afb_api_verbose(afbBindingV3root,__VA_ARGS__)
254 #define afb_daemon_rootdir_get_fd_v3() afb_api_rootdir_get_fd(afbBindingV3root)
255 #define afb_daemon_rootdir_open_locale_v3(...) afb_api_rootdir_open_locale(afbBindingV3root,__VA_ARGS__)
256 #define afb_daemon_queue_job_v3(...) afb_api_queue_job(afbBindingV3root,__VA_ARGS__)
257 #define afb_daemon_require_api_v3(...) afb_api_require_api(afbBindingV3root,__VA_ARGS__)
258 #define afb_daemon_add_alias_v3(...) afb_api_add_alias(afbBindingV3root,__VA_ARGS__)
260 #define afb_service_call_v3(...) afb_api_call(afbBindingV3root,__VA_ARGS__)
261 #define afb_service_call_sync_v3(...) afb_api_call_sync(afbBindingV3root,__VA_ARGS__)
262 #define afb_service_call_legacy_v3(...) afb_api_call_legacy(afbBindingV3root,__VA_ARGS__)
263 #define afb_service_call_sync_legacy_v3(...) afb_api_call_sync_legacy(afbBindingV3root,__VA_ARGS__)