include/afb/afb-binding-v3.h

   1 /*
   2  * Copyright (C) 2015-2020 "IoT.bzh"
   3  * Author: José Bollo <jose.bollo@iot.bzh>
   4  *
   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
   8  *
   9  *   http://www.apache.org/licenses/LICENSE-2.0
  10  *
  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.
  16  */
  17
  18 /**< @file afb/afb-binding-v3.h */
  19
  20 #pragma once
  21
  22 /******************************************************************************/
  23
  24 #include "afb-auth.h"
  25 #include "afb-event-x2.h"
  26 #include "afb-req-x2.h"
  27 #include "afb-session-x2.h"
  28 #include "afb-api-x3.h"
  29
  30 /******************************************************************************/
  31
  32 /**
  33  * @page validity-v3 Validity of a binding v3
  34  *
  35  * A binding V3 MUST have at least two exported symbols of name:
  36  *
  37  *   - @ref afbBindingV3root
  38  *   - @ref afbBindingV3  and/or  @ref afbBindingV3entry
  39  *
  40  * @ref afbBindingV3root is automatically created when **AFB_BINDING_VERSION == 3**
  41  * without programmer action, as a hidden variable linked as *weak*.
  42  *
  43  * The symbols @ref afbBindingV3  and  **afbBindingV3entry** are under control
  44  * of the programmer.
  45  *
  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.
  48  *
  49  * The symbol @ref afbBindingV3entry if defined will be called during
  50  * pre-initialization.
  51  *
  52  * If @ref afbBindingV3entry and @ref afbBindingV3 are both defined, it is an
  53  * error to fill the field @ref preinit of @ref afbBindingV3.
  54  *
  55  * @see afb_binding_v3
  56  * @see afbBindingV3root
  57  * @see afbBindingV3entry
  58  * @see afbBindingV3
  59  */
  60
  61 /**
  62  * Description of one verb as provided for binding API version 3
  63  */
  64 struct afb_verb_v3
  65 {
  66         /** name of the verb, NULL only at end of the array */
  67         const char *verb;
  68
  69         /** callback function implementing the verb */
  70         void (*callback)(struct afb_req_x2 *req);
  71
  72         /** required authorization, can be NULL */
  73         const struct afb_auth *auth;
  74
  75         /** some info about the verb, can be NULL */
  76         const char *info;
  77
  78         /**< data for the verb callback */
  79         void *vcbdata;
  80
  81         /** authorization and session requirements of the verb */
  82         uint16_t session;
  83
  84         /** is the verb glob name */
  85         uint16_t glob: 1;
  86 };
  87
  88 /**
  89  * Description of the bindings of type version 3
  90  */
  91 struct afb_binding_v3
  92 {
  93         /** api name for the binding, can't be NULL */
  94         const char *api;
  95
  96         /** textual specification of the binding, can be NULL */
  97         const char *specification;
  98
  99         /** some info about the api, can be NULL */
 100         const char *info;
 101
 102         /** array of descriptions of verbs terminated by a NULL name, can be NULL */
 103         const struct afb_verb_v3 *verbs;
 104
 105         /** callback at load of the binding */
 106         int (*preinit)(struct afb_api_x3 *api);
 107
 108         /** callback for starting the service */
 109         int (*init)(struct afb_api_x3 *api);
 110
 111         /** callback for handling events */
 112         void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object);
 113
 114         /** userdata for afb_api_x3 */
 115         void *userdata;
 116
 117         /** space separated list of provided class(es) */
 118         const char *provide_class;
 119
 120         /** space separated list of required class(es) */
 121         const char *require_class;
 122
 123         /** space separated list of required API(es) */
 124         const char *require_api;
 125
 126         /** avoids concurrent requests to verbs */
 127         unsigned noconcurrency: 1;
 128 };
 129
 130 /**
 131  * Default root binding's api that can be used when no explicit context is
 132  * available.
 133  *
 134  * When @ref afbBindingV3 is defined, this variable records the corresponding
 135  * api handler. Otherwise, it points to an fake handles that allows logging
 136  * and api creation.
 137  *
 138  * @see afbBindingV3entry
 139  * @see afbBindingV3
 140  * @see @ref validity-v3
 141  */
 142 #if AFB_BINDING_VERSION != 3
 143 extern
 144 #endif
 145 struct afb_api_x3 *afbBindingV3root __attribute__((weak));
 146
 147 /**
 148  * Pre-initialization function.
 149  *
 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
 153  *
 154  * @param rootapi the root api (equals to afbBindingV3root)
 155  *
 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.
 159
 160  * @see afbBindingV3root
 161  * @see afbBindingV3
 162  * @see @ref validity-v3
 163  */
 164 extern int afbBindingV3entry(struct afb_api_x3 *rootapi);
 165
 166 /**
 167  * Static definition of the root api of the binding.
 168  *
 169  * This symbol if defined describes the API of the binding.
 170  *
 171  * If it is not defined then the function @ref afbBindingV3entry must be defined
 172  *
 173  * @see afbBindingV3root
 174  * @see afbBindingV3entry
 175  * @see @ref validity-v3
 176  */
 177 extern const struct afb_binding_v3 afbBindingV3;
 178
 179 #include "afb-auth.h"
 180 #include "afb-session-x2.h"
 181 #include "afb-verbosity.h"
 182
 183 #include "afb-event-x2.h"
 184 #include "afb-req-x2.h"
 185 #include "afb-api-x3.h"
 186
 187 /*
 188  * Macros for logging messages
 189  */
 190
 191 #if defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DATA)
 192
 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)
 197
 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)
 202
 203 #elif defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS)
 204
 205 # define AFB_API_VERBOSE_V3(api,level,...) \
 206         afb_api_x3_verbose(api,level,NULL,0,NULL,__VA_ARGS__)
 207
 208 # define AFB_REQ_VERBOSE_V3(req,level,...) \
 209         afb_req_x2_verbose(req,level,NULL,0,NULL,__VA_ARGS__)
 210
 211 #else
 212
 213 # define AFB_API_VERBOSE_V3(api,level,...) \
 214         afb_api_x3_verbose(api,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
 215
 216 # define AFB_REQ_VERBOSE_V3(req,level,...) \
 217         afb_req_x2_verbose(req,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
 218
 219 #endif
 220
 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)
 225
 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__)
 231
 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__)
 237
 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__)
 243
 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))
 247
 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__)
 259
 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__)
 264