include/afb/afb-binding-v1.h

   1 /*
   2  * Copyright (C) 2016, 2017 "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 #include "afb-session-v1.h"
  21
  22 struct json_object;
  23 struct afb_service;
  24 struct afb_binding_v1;
  25 struct afb_binding_interface_v1;
  26
  27 /*
  28  * Function for registering the binding
  29  *
  30  * A binding V1 MUST have an exported function of name
  31  *
  32  *              afbBindingV1Register
  33  *
  34  * This function is called during loading of the binding. It
  35  * receives an 'interface' that should be recorded for later access to
  36  * functions provided by the framework.
  37  *
  38  * This function MUST return the address of a structure that describes
  39  * the binding and its implemented verbs.
  40  *
  41  * In case of initialisation error, NULL must be returned.
  42  *
  43  * Be aware that the given 'interface' is not fully functionnal
  44  * because no provision is given to the name and description
  45  * of the binding. Check the function 'afbBindingV1ServiceInit'
  46  * defined in the file <afb/afb-service-itf.h> because when
  47  * the function 'afbBindingV1ServiceInit' is called, the 'interface'
  48  * is fully functionnal.
  49  */
  50 extern const struct afb_binding_v1 *afbBindingV1Register (const struct afb_binding_interface_v1 *interface);
  51
  52 /*
  53  * When a binding have an exported implementation of the
  54  * function 'afbBindingV1ServiceInit', defined below,
  55  * the framework calls it for initialising the service after
  56  * registration of all bindings.
  57  *
  58  * The object 'service' should be recorded. It has functions that
  59  * allows the binding to call features with its own personality.
  60  *
  61  * The function should return 0 in case of success or, else, should return
  62  * a negative value.
  63  */
  64 extern int afbBindingV1ServiceInit(struct afb_service service);
  65
  66 /*
  67  * When a binding have an implementation of the function 'afbBindingV1ServiceEvent',
  68  * defined below, the framework calls that function for any broadcasted event or for
  69  * events that the service subscribed to in its name.
  70  *
  71  * It receive the 'event' name and its related data in 'object' (be aware that 'object'
  72  * might be NULL).
  73  */
  74 extern void afbBindingV1ServiceEvent(const char *event, struct json_object *object);
  75
  76
  77 /*
  78  * Description of one verb of the API provided by the binding
  79  * This enumeration is valid for bindings of type version 1
  80  */
  81 struct afb_verb_desc_v1
  82 {
  83        const char *name;                       /* name of the verb */
  84        enum afb_session_flags_v1 session;      /* authorisation and session requirements of the verb */
  85        void (*callback)(struct afb_req req);   /* callback function implementing the verb */
  86        const char *info;                       /* textual description of the verb */
  87 };
  88
  89 /*
  90  * Description of the bindings of type version 1
  91  */
  92 struct afb_binding_desc_v1
  93 {
  94        const char *info;                       /* textual information about the binding */
  95        const char *prefix;                     /* required prefix name for the binding */
  96        const struct afb_verb_desc_v1 *verbs;   /* array of descriptions of verbs terminated by a NULL name */
  97 };
  98
  99 /*
 100  * Definition of the type+versions of the binding.
 101  * The definition uses hashes.
 102  */
 103 enum  afb_binding_type_v1
 104 {
 105        AFB_BINDING_VERSION_1 = 123456789
 106 };
 107
 108 /*
 109  * Description of a binding
 110  */
 111 struct afb_binding_v1
 112 {
 113        enum afb_binding_type_v1 type; /* type of the binding */
 114        union {
 115                struct afb_binding_desc_v1 v1;   /* description of the binding of type 1 */
 116        };
 117 };
 118
 119 /*
 120  * config mode
 121  */
 122 enum afb_mode_v1 {
 123         AFB_MODE_LOCAL = 0,     /* run locally */
 124         AFB_MODE_REMOTE,        /* run remotely */
 125         AFB_MODE_GLOBAL         /* run either remotely or locally (DONT USE! reserved for future) */
 126 };
 127
 128 /*
 129  * Interface between the daemon and the binding.
 130  */
 131 struct afb_binding_interface_v1
 132 {
 133         struct afb_daemon daemon;       /* access to the daemon facilies */
 134         int verbosity;                  /* level of verbosity */
 135         enum afb_mode_v1 mode;          /* run mode (local or remote) */
 136 };
 137
 138 /*
 139  * Macros for logging messages
 140  */
 141 #if !defined(AFB_BINDING_PRAGMA_NO_VERBOSE_MACRO)
 142 # if !defined(AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS)
 143 #  define AFB_ERROR_V1(itf,...)   do{if(itf->verbosity>=0)afb_daemon_verbose(itf->daemon,3,__FILE__,__LINE__,__VA_ARGS__);}while(0)
 144 #  define AFB_WARNING_V1(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,4,__FILE__,__LINE__,__VA_ARGS__);}while(0)
 145 #  define AFB_NOTICE_V1(itf,...)  do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,5,__FILE__,__LINE__,__VA_ARGS__);}while(0)
 146 #  define AFB_INFO_V1(itf,...)    do{if(itf->verbosity>=2)afb_daemon_verbose(itf->daemon,6,__FILE__,__LINE__,__VA_ARGS__);}while(0)
 147 #  define AFB_DEBUG_V1(itf,...)   do{if(itf->verbosity>=3)afb_daemon_verbose(itf->daemon,7,__FILE__,__LINE__,__VA_ARGS__);}while(0)
 148 # else
 149 #  define AFB_ERROR_V1(itf,...)   do{if(itf->verbosity>=0)afb_daemon_verbose(itf->daemon,3,NULL,0,__VA_ARGS__);}while(0)
 150 #  define AFB_WARNING_V1(itf,...) do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,4,NULL,0,__VA_ARGS__);}while(0)
 151 #  define AFB_NOTICE_V1(itf,...)  do{if(itf->verbosity>=1)afb_daemon_verbose(itf->daemon,5,NULL,0,__VA_ARGS__);}while(0)
 152 #  define AFB_INFO_V1(itf,...)    do{if(itf->verbosity>=2)afb_daemon_verbose(itf->daemon,6,NULL,0,__VA_ARGS__);}while(0)
 153 #  define AFB_DEBUG_V1(itf,...)   do{if(itf->verbosity>=3)afb_daemon_verbose(itf->daemon,7,NULL,0,__VA_ARGS__);}while(0)
 154 # endif
 155 #endif
 156
 157
 158 /***************************************************************************************************/
 159
 160 #if AFB_BINDING_VERSION == 1
 161
 162 # define afb_binding            afb_binding_v1
 163 # define afb_binding_interface  afb_binding_interface_v1
 164
 165 # define AFB_SESSION_NONE       AFB_SESSION_NONE_V1
 166 # define AFB_SESSION_CREATE     AFB_SESSION_CREATE_V1
 167 # define AFB_SESSION_CLOSE      AFB_SESSION_CLOSE_V1
 168 # define AFB_SESSION_RENEW      AFB_SESSION_RENEW_V1
 169 # define AFB_SESSION_CHECK      AFB_SESSION_CHECK_V1
 170
 171 # define AFB_SESSION_LOA_GE     AFB_SESSION_LOA_GE_V1
 172 # define AFB_SESSION_LOA_LE     AFB_SESSION_LOA_LE_V1
 173 # define AFB_SESSION_LOA_EQ     AFB_SESSION_LOA_EQ_V1
 174
 175 # define AFB_SESSION_LOA_SHIFT  AFB_SESSION_LOA_SHIFT_V1
 176 # define AFB_SESSION_LOA_MASK   AFB_SESSION_LOA_MASK_V1
 177
 178 # define AFB_SESSION_LOA_0      AFB_SESSION_LOA_0_V1
 179 # define AFB_SESSION_LOA_1      AFB_SESSION_LOA_1_V1
 180 # define AFB_SESSION_LOA_2      AFB_SESSION_LOA_2_V1
 181 # define AFB_SESSION_LOA_3      AFB_SESSION_LOA_3_V1
 182 # define AFB_SESSION_LOA_4      AFB_SESSION_LOA_4_V1
 183
 184 # define AFB_SESSION_LOA_LE_0   AFB_SESSION_LOA_LE_0_V1
 185 # define AFB_SESSION_LOA_LE_1   AFB_SESSION_LOA_LE_1_V1
 186 # define AFB_SESSION_LOA_LE_2   AFB_SESSION_LOA_LE_2_V1
 187 # define AFB_SESSION_LOA_LE_3   AFB_SESSION_LOA_LE_3_V1
 188
 189 # define AFB_SESSION_LOA_EQ_0   AFB_SESSION_LOA_EQ_0_V1
 190 # define AFB_SESSION_LOA_EQ_1   AFB_SESSION_LOA_EQ_1_V1
 191 # define AFB_SESSION_LOA_EQ_2   AFB_SESSION_LOA_EQ_2_V1
 192 # define AFB_SESSION_LOA_EQ_3   AFB_SESSION_LOA_EQ_3_V1
 193
 194 # define AFB_SESSION_LOA_GE_0   AFB_SESSION_LOA_GE_0_V1
 195 # define AFB_SESSION_LOA_GE_1   AFB_SESSION_LOA_GE_1_V1
 196 # define AFB_SESSION_LOA_GE_2   AFB_SESSION_LOA_GE_2_V1
 197 # define AFB_SESSION_LOA_GE_3   AFB_SESSION_LOA_GE_3_V1
 198
 199 # if !defined(AFB_BINDING_PRAGMA_NO_VERBOSE_MACRO)
 200
 201 #  define ERROR                 AFB_ERROR_V1
 202 #  define WARNING               AFB_WARNING_V1
 203 #  define NOTICE                AFB_NOTICE_V1
 204 #  define INFO                  AFB_INFO_V1
 205 #  define DEBUG                 AFB_DEBUG_V1
 206
 207 # endif
 208
 209 #endif
 210
 211
 212