include/afb/afb-binding-v1.h

   1 /*
   2  * Copyright (C) 2016-2019 "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 #pragma once
  19
  20 /******************************************************************************/
  21
  22 #include "afb-verbosity.h"
  23 #include "afb-req-x1.h"
  24 #include "afb-event-x1.h"
  25 #include "afb-service-itf-x1.h"
  26 #include "afb-daemon-itf-x1.h"
  27
  28 #include "afb-req-v1.h"
  29 #include "afb-session-x1.h"
  30 #include "afb-service-v1.h"
  31 #include "afb-daemon-v1.h"
  32
  33 struct afb_binding_v1;
  34 struct afb_binding_interface_v1;
  35
  36 /******************************************************************************/
  37
  38 /**
  39  * @deprecated use bindings version 3
  40  *
  41  * Function for registering the binding
  42  *
  43  * A binding V1 MUST have an exported function of name
  44  *
  45  *              afbBindingV1Register
  46  *
  47  * This function is called during loading of the binding. It
  48  * receives an 'interface' that should be recorded for later access to
  49  * functions provided by the framework.
  50  *
  51  * This function MUST return the address of a structure that describes
  52  * the binding and its implemented verbs.
  53  *
  54  * In case of initialisation error, NULL must be returned.
  55  *
  56  * Be aware that the given 'interface' is not fully functionnal
  57  * because no provision is given to the name and description
  58  * of the binding. Check the function 'afbBindingV1ServiceInit'
  59  * defined in the file <afb/afb-service-v1.h> because when
  60  * the function 'afbBindingV1ServiceInit' is called, the 'interface'
  61  * is fully functionnal.
  62  */
  63 extern const struct afb_binding_v1 *afbBindingV1Register (const struct afb_binding_interface_v1 *interface);
  64
  65 /**
  66  * @deprecated use bindings version 3
  67  *
  68  * When a binding have an exported implementation of the
  69  * function 'afbBindingV1ServiceInit', defined below,
  70  * the framework calls it for initialising the service after
  71  * registration of all bindings.
  72  *
  73  * The object 'service' should be recorded. It has functions that
  74  * allows the binding to call features with its own personality.
  75  *
  76  * The function should return 0 in case of success or, else, should return
  77  * a negative value.
  78  */
  79 extern int afbBindingV1ServiceInit(struct afb_service_x1 service);
  80
  81 /**
  82  * @deprecated use bindings version 3
  83  *
  84  * When a binding have an implementation of the function 'afbBindingV1ServiceEvent',
  85  * defined below, the framework calls that function for any broadcasted event or for
  86  * events that the service subscribed to in its name.
  87  *
  88  * It receive the 'event' name and its related data in 'object' (be aware that 'object'
  89  * might be NULL).
  90  */
  91 extern void afbBindingV1ServiceEvent(const char *event, struct json_object *object);
  92
  93
  94 /**
  95  * @deprecated use bindings version 3
  96  *
  97  * Description of one verb of the API provided by the binding
  98  * This enumeration is valid for bindings of type version 1
  99  */
 100 struct afb_verb_desc_v1
 101 {
 102        const char *name;                       /**< name of the verb */
 103        enum afb_session_flags_x1 session;      /**< authorisation and session requirements of the verb */
 104        void (*callback)(struct afb_req_x1 req);/**< callback function implementing the verb */
 105        const char *info;                       /**< textual description of the verb */
 106 };
 107
 108 /**
 109  * @deprecated use bindings version 3
 110  *
 111  * Description of the bindings of type version 1
 112  */
 113 struct afb_binding_desc_v1
 114 {
 115        const char *info;                       /**< textual information about the binding */
 116        const char *prefix;                     /**< required prefix name for the binding */
 117        const struct afb_verb_desc_v1 *verbs;   /**< array of descriptions of verbs terminated by a NULL name */
 118 };
 119
 120 /**
 121  * @deprecated use bindings version 3
 122  *
 123  * Definition of the type+versions of the binding version 1.
 124  * The definition uses hashes.
 125  */
 126 enum  afb_binding_type_v1
 127 {
 128        AFB_BINDING_VERSION_1 = 123456789
 129 };
 130
 131 /**
 132  * @deprecated use bindings version 3
 133  *
 134  * Description of a binding version 1
 135  */
 136 struct afb_binding_v1
 137 {
 138        enum afb_binding_type_v1 type; /**< type of the binding */
 139        union {
 140                struct afb_binding_desc_v1 v1;   /**< description of the binding of type 1 */
 141        };
 142 };
 143
 144 /**
 145  * @deprecated use bindings version 3
 146  *
 147  * config mode for bindings version 1
 148  */
 149 enum afb_mode_v1
 150 {
 151         AFB_MODE_LOCAL = 0,     /**< run locally */
 152         AFB_MODE_REMOTE,        /**< run remotely */
 153         AFB_MODE_GLOBAL         /**< run either remotely or locally (DONT USE! reserved for future) */
 154 };
 155
 156 /**
 157  * @deprecated use bindings version 3
 158  *
 159  * Interface between the daemon and the binding version 1.
 160  */
 161 struct afb_binding_interface_v1
 162 {
 163         struct afb_daemon_x1 daemon;    /**< access to the daemon facilies */
 164         int verbosity;                  /**< level of verbosity */
 165         enum afb_mode_v1 mode;          /**< run mode (local or remote) */
 166 };
 167
 168 /******************************************************************************/
 169 /*
 170  * Macros for logging messages
 171  */
 172 #if defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DATA)
 173
 174 # define AFB_VERBOSE_V1(itf,level,...) \
 175                 do { if(level <= AFB_VERBOSITY_LEVEL_ERROR) \
 176                         afb_daemon_verbose2_v1(itf->daemon,level,__FILE__,__LINE__,NULL,__VA_ARGS__); \
 177                 else afb_daemon_verbose2_v1(itf->daemon,level,__FILE__,__LINE__,NULL); } while(0)
 178
 179 # define AFB_REQ_VERBOSE_V1(req,level,...) \
 180                 do { if(level <= AFB_VERBOSITY_LEVEL_ERROR) \
 181                         afb_req_x1_verbose(req,level,__FILE__,__LINE__,NULL,__VA_ARGS__); \
 182                 else afb_req_x1_verbose(req,level,__FILE__,__LINE__,NULL); } while(0)
 183
 184 #elif defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS)
 185
 186 # define AFB_VERBOSE_V1(itf,level,...) \
 187                 afb_daemon_verbose2_v1(itf->daemon,level,NULL,0,NULL,__VA_ARGS__)
 188
 189 # define AFB_REQ_VERBOSE_V1(req,level,...) \
 190                 afb_req_x1_verbose(req,level,NULL,0,NULL,__VA_ARGS__)
 191
 192 #else
 193
 194 # define AFB_VERBOSE_V1(itf,level,...) \
 195                 afb_daemon_verbose2_v1(itf->daemon,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
 196
 197 # define AFB_REQ_VERBOSE_V1(req,level,...) \
 198                 afb_req_x1_verbose(req,level,__FILE__,__LINE__,__func__,__VA_ARGS__)
 199
 200 #endif
 201
 202 #define _AFB_LOGGING_V1_(itf,vlevel,llevel,...) \
 203         do{ if(itf->verbosity>=vlevel) AFB_VERBOSE_V1(itf,llevel,__VA_ARGS__); }while(0)
 204 #define _AFB_REQ_LOGGING_V1_(itf,vlevel,llevel,req,...) \
 205         do{ if(itf->verbosity>=vlevel) AFB_REQ_VERBOSE_V1(itf,llevel,__VA_ARGS__); }while(0)
 206
 207 # define AFB_ERROR_V1(itf,...)       _AFB_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_ERROR,AFB_SYSLOG_LEVEL_ERROR,__VA_ARGS__)
 208 # define AFB_WARNING_V1(itf,...)     _AFB_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_WARNING,AFB_SYSLOG_LEVEL_WARNING,__VA_ARGS__)
 209 # define AFB_NOTICE_V1(itf,...)      _AFB_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_NOTICE,AFB_SYSLOG_LEVEL_NOTICE,__VA_ARGS__)
 210 # define AFB_INFO_V1(itf,...)        _AFB_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_INFO,AFB_SYSLOG_LEVEL_INFO,__VA_ARGS__)
 211 # define AFB_DEBUG_V1(itf,...)       _AFB_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_DEBUG,AFB_SYSLOG_LEVEL_DEBUG,__VA_ARGS__)
 212
 213 # define AFB_REQ_ERROR_V1(itf,...)   _AFB_REQ_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_ERROR,AFB_SYSLOG_LEVEL_ERROR,__VA_ARGS__)
 214 # define AFB_REQ_WARNING_V1(itf,...) _AFB_REQ_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_WARNING,AFB_SYSLOG_LEVEL_WARNING,__VA_ARGS__)
 215 # define AFB_REQ_NOTICE_V1(itf,...)  _AFB_REQ_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_NOTICE,AFB_SYSLOG_LEVEL_NOTICE,__VA_ARGS__)
 216 # define AFB_REQ_INFO_V1(itf,...)    _AFB_REQ_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_INFO,AFB_SYSLOG_LEVEL_INFO,__VA_ARGS__)
 217 # define AFB_REQ_DEBUG_V1(itf,...)   _AFB_REQ_LOGGING_V1_(itf,AFB_VERBOSITY_LEVEL_DEBUG,AFB_SYSLOG_LEVEL_DEBUG,__VA_ARGS__)
 218
 219 /******************************************************************************/
 220
 221 #if  AFB_BINDING_VERSION == 1 && defined(AFB_BINDING_PRAGMA_KEEP_VERBOSE_UNPREFIX)
 222 # define ERROR                  AFB_ERROR
 223 # define WARNING                AFB_WARNING
 224 # define NOTICE                 AFB_NOTICE
 225 # define INFO                   AFB_INFO
 226 # define DEBUG                  AFB_DEBUG
 227
 228 # define REQ_ERROR              AFB_REQ_ERROR
 229 # define REQ_WARNING            AFB_REQ_WARNING
 230 # define REQ_NOTICE             AFB_REQ_NOTICE
 231 # define REQ_INFO               AFB_REQ_INFO
 232 # define REQ_DEBUG              AFB_REQ_DEBUG
 233 #endif
 234