2 * Copyright (C) 2016, 2017, 2018 "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.
22 struct afb_req_x2_itf;
30 struct afb_stored_req;
33 * structure for the request
38 * interface for the request
40 const struct afb_req_x2_itf *itf;
43 * current api (if any)
45 struct afb_api_x3 *api;
48 * closure associated with the callback processing the verb of the request
49 * as given at its declaration
54 * the name of the called api
56 const char *called_api;
59 * the name of the called verb
61 const char *called_verb;
67 * When making subcalls, it is now possible to explicitely set the subcall
68 * mode to a combination of the following mode using binary OR.
70 * In particular, the following combination of modes are to be known:
72 * - for **subcall** having a similar behaviour to the subcalls of bindings
73 * version 1 and 2: afb_req_x2_subcall_pass_events|afb_req_x2_subcall_on_behalf
74 * - for **subcall** having the behaviour of the **call**:
75 * afb_req_x2_subcall_catch_events|afb_req_x2_subcall_api_session
77 * Be aware that if none of mode afb_req_x2_subcall_catch_events or
78 * afb_req_x2_subcall_pass_events is set, subscrption to events will be ignored.
80 enum afb_req_x2_subcall_flags
83 * the calling API wants to receive the events from subscription
85 afb_req_x2_subcall_catch_events = 1,
88 * the original request will receive the events from subscription
90 afb_req_x2_subcall_pass_events = 2,
93 * the calling API wants to use the credentials of the original request
95 afb_req_x2_subcall_on_behalf = 4,
98 * the calling API wants to use its session instead of the one of the
101 afb_req_x2_subcall_api_session = 8,
105 * Interface for handling requests.
107 * It records the functions to be called for the request.
108 * Don't use this structure directly, Use the helper functions instead.
110 struct afb_req_x2_itf
112 /* CAUTION: respect the order, add at the end */
115 struct json_object *(*json)(
116 struct afb_req_x2 *req);
118 /** get an argument */
119 struct afb_arg (*get)(
120 struct afb_req_x2 *req,
123 /** reply a success @deprecated use @ref reply */
124 void (*legacy_success)(
125 struct afb_req_x2 *req,
126 struct json_object *obj,
129 /** reply a failure @deprecated use @ref reply */
131 struct afb_req_x2 *req,
135 /** reply a success @deprecated use @ref vreply */
136 void (*legacy_vsuccess)(
137 struct afb_req_x2 *req,
138 struct json_object *obj,
142 /** reply a failure @deprecated use @ref vreply */
143 void (*legacy_vfail)(
144 struct afb_req_x2 *req,
149 /** get a client context @deprecated use @ref context_make */
150 void *(*legacy_context_get)(
151 struct afb_req_x2 *req);
153 /** set a client context @deprecated use @ref context_make */
154 void (*legacy_context_set)(
155 struct afb_req_x2 *req,
157 void (*free_value)(void*));
159 /** increase reference count of the request */
160 struct afb_req_x2 *(*addref)(
161 struct afb_req_x2 *req);
163 /** decrease reference count of the request */
165 struct afb_req_x2 *req);
167 /** close the client session related to the api of the request */
168 void (*session_close)(
169 struct afb_req_x2 *req);
171 /** set the levele of assurancy related to the api of the request */
172 int (*session_set_LOA)(
173 struct afb_req_x2 *req,
176 /** make subscription of the client of the request to the event @deprecated use @ref subscribe_event_x2 */
177 int (*legacy_subscribe_event_x1)(
178 struct afb_req_x2 *req,
179 struct afb_event_x1 event);
181 /** remove subscription of the client of the request to the event @deprecated use @ref unsubscribe_event_x2 */
182 int (*legacy_unsubscribe_event_x1)(
183 struct afb_req_x2 *req,
184 struct afb_event_x1 event);
186 /** asynchronous subcall @deprecated use @ref subcall */
187 void (*legacy_subcall)(
188 struct afb_req_x2 *req,
191 struct json_object *args,
192 void (*callback)(void*, int, struct json_object*),
195 /** synchronous subcall @deprecated use @ref subcallsync */
196 int (*legacy_subcallsync)(
197 struct afb_req_x2 *req,
200 struct json_object *args,
201 struct json_object **result);
203 /** log a message for the request */
205 struct afb_req_x2 *req,
213 /** store the request @deprecated no more needed */
214 struct afb_stored_req *(*legacy_store_req)(
215 struct afb_req_x2 *req);
217 /** asynchronous subcall with request @deprecated use @ref subcall */
218 void (*legacy_subcall_req)(
219 struct afb_req_x2 *req,
222 struct json_object *args,
223 void (*callback)(void*, int, struct json_object*, struct afb_req_x1),
226 /** store the request @deprecated no more needed */
227 int (*has_permission)(
228 struct afb_req_x2 *req,
229 const char *permission);
231 /** get the application id of the client of the request */
232 char *(*get_application_id)(
233 struct afb_req_x2 *req);
235 /** handle client context of the api getting the request */
236 void *(*context_make)(
237 struct afb_req_x2 *req,
239 void *(*create_value)(void *creation_closure),
240 void (*free_value)(void*),
241 void *creation_closure);
243 /** make subscription of the client of the request to the event */
244 int (*subscribe_event_x2)(
245 struct afb_req_x2 *req,
246 struct afb_event_x2 *event);
248 /** remove subscription of the client of the request to the event */
249 int (*unsubscribe_event_x2)(
250 struct afb_req_x2 *req,
251 struct afb_event_x2 *event);
253 /** asynchronous subcall with request @deprecated use @ref subcall */
254 void (*legacy_subcall_request)(
255 struct afb_req_x2 *req,
258 struct json_object *args,
259 void (*callback)(void*, int, struct json_object*, struct afb_req_x2 *req),
262 /** get the user id (unix) of the client of the request */
264 struct afb_req_x2 *req);
266 /** reply to the request */
268 struct afb_req_x2 *req,
269 struct json_object *obj,
273 /** reply to the request with formating of info */
275 struct afb_req_x2 *req,
276 struct json_object *obj,
281 /** get description of the client of the request */
282 struct json_object *(*get_client_info)(
283 struct afb_req_x2 *req);
285 /** asynchronous subcall */
287 struct afb_req_x2 *req,
290 struct json_object *args,
292 void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_req_x2 *req),
295 /** synchronous subcall */
297 struct afb_req_x2 *req,
300 struct json_object *args,
302 struct json_object **object,