2 * Copyright (C) 2016-2019 "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;
32 /** @addtogroup AFB_REQ
36 * structure for the request
41 * interface for the request
43 const struct afb_req_x2_itf *itf;
46 * current api (if any)
48 struct afb_api_x3 *api;
51 * closure associated with the callback processing the verb of the request
52 * as given at its declaration
57 * the name of the called api
59 const char *called_api;
62 * the name of the called verb
64 const char *called_verb;
70 * When making subcalls, it is now possible to explicitely set the subcall
71 * mode to a combination of the following flags using binary OR.
73 * In particular, the following combination of flags are to be known:
75 * - for **subcall** having a similar behaviour to the subcalls of bindings
76 * version 1 and 2: afb_req_x2_subcall_pass_events|afb_req_x2_subcall_on_behalf
78 * - for **subcall** having the behaviour of the **call**:
79 * afb_req_x2_subcall_catch_events|afb_req_x2_subcall_api_session
81 * Be aware that if none of mode afb_req_x2_subcall_catch_events or
82 * afb_req_x2_subcall_pass_events is set, subscrption to events will be ignored.
84 enum afb_req_x2_subcall_flags
87 * the calling API wants to receive the events from subscription
89 afb_req_x2_subcall_catch_events = 1,
92 * the original request will receive the events from subscription
94 afb_req_x2_subcall_pass_events = 2,
97 * the calling API wants to use the credentials of the original request
99 afb_req_x2_subcall_on_behalf = 4,
102 * the calling API wants to use its session instead of the one of the
105 afb_req_x2_subcall_api_session = 8,
109 * Interface for handling requests.
111 * It records the functions to be called for the request.
112 * Don't use this structure directly, Use the helper functions instead.
114 struct afb_req_x2_itf
116 /* CAUTION: respect the order, add at the end */
119 struct json_object *(*json)(
120 struct afb_req_x2 *req);
122 /** get an argument */
123 struct afb_arg (*get)(
124 struct afb_req_x2 *req,
127 /** reply a success @deprecated use @ref reply */
128 void (*legacy_success)(
129 struct afb_req_x2 *req,
130 struct json_object *obj,
133 /** reply a failure @deprecated use @ref reply */
135 struct afb_req_x2 *req,
139 /** reply a success @deprecated use @ref vreply */
140 void (*legacy_vsuccess)(
141 struct afb_req_x2 *req,
142 struct json_object *obj,
146 /** reply a failure @deprecated use @ref vreply */
147 void (*legacy_vfail)(
148 struct afb_req_x2 *req,
153 /** get a client context @deprecated use @ref context_make */
154 void *(*legacy_context_get)(
155 struct afb_req_x2 *req);
157 /** set a client context @deprecated use @ref context_make */
158 void (*legacy_context_set)(
159 struct afb_req_x2 *req,
161 void (*free_value)(void*));
163 /** increase reference count of the request */
164 struct afb_req_x2 *(*addref)(
165 struct afb_req_x2 *req);
167 /** decrease reference count of the request */
169 struct afb_req_x2 *req);
171 /** close the client session related to the api of the request */
172 void (*session_close)(
173 struct afb_req_x2 *req);
175 /** set the levele of assurancy related to the api of the request */
176 int (*session_set_LOA)(
177 struct afb_req_x2 *req,
180 /** make subscription of the client of the request to the event @deprecated use @ref subscribe_event_x2 */
181 int (*legacy_subscribe_event_x1)(
182 struct afb_req_x2 *req,
183 struct afb_event_x1 event);
185 /** remove subscription of the client of the request to the event @deprecated use @ref unsubscribe_event_x2 */
186 int (*legacy_unsubscribe_event_x1)(
187 struct afb_req_x2 *req,
188 struct afb_event_x1 event);
190 /** asynchronous subcall @deprecated use @ref subcall */
191 void (*legacy_subcall)(
192 struct afb_req_x2 *req,
195 struct json_object *args,
196 void (*callback)(void*, int, struct json_object*),
199 /** synchronous subcall @deprecated use @ref subcallsync */
200 int (*legacy_subcallsync)(
201 struct afb_req_x2 *req,
204 struct json_object *args,
205 struct json_object **result);
207 /** log a message for the request */
209 struct afb_req_x2 *req,
217 /** store the request @deprecated no more needed */
218 struct afb_stored_req *(*legacy_store_req)(
219 struct afb_req_x2 *req);
221 /** asynchronous subcall with request @deprecated use @ref subcall */
222 void (*legacy_subcall_req)(
223 struct afb_req_x2 *req,
226 struct json_object *args,
227 void (*callback)(void*, int, struct json_object*, struct afb_req_x1),
230 /** store the request @deprecated no more needed */
231 int (*has_permission)(
232 struct afb_req_x2 *req,
233 const char *permission);
235 /** get the application id of the client of the request */
236 char *(*get_application_id)(
237 struct afb_req_x2 *req);
239 /** handle client context of the api getting the request */
240 void *(*context_make)(
241 struct afb_req_x2 *req,
243 void *(*create_value)(void *creation_closure),
244 void (*free_value)(void*),
245 void *creation_closure);
247 /** make subscription of the client of the request to the event */
248 int (*subscribe_event_x2)(
249 struct afb_req_x2 *req,
250 struct afb_event_x2 *event);
252 /** remove subscription of the client of the request to the event */
253 int (*unsubscribe_event_x2)(
254 struct afb_req_x2 *req,
255 struct afb_event_x2 *event);
257 /** asynchronous subcall with request @deprecated use @ref subcall */
258 void (*legacy_subcall_request)(
259 struct afb_req_x2 *req,
262 struct json_object *args,
263 void (*callback)(void*, int, struct json_object*, struct afb_req_x2 *req),
266 /** get the user id (unix) of the client of the request */
268 struct afb_req_x2 *req);
270 /** reply to the request */
272 struct afb_req_x2 *req,
273 struct json_object *obj,
277 /** reply to the request with formating of info */
279 struct afb_req_x2 *req,
280 struct json_object *obj,
285 /** get description of the client of the request */
286 struct json_object *(*get_client_info)(
287 struct afb_req_x2 *req);
289 /** asynchronous subcall */
291 struct afb_req_x2 *req,
294 struct json_object *args,
296 void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_req_x2 *req),
299 /** synchronous subcall */
301 struct afb_req_x2 *req,
304 struct json_object *args,
306 struct json_object **object,