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