include/afb/afb-req-x2-itf.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 /* defined here */
  21 struct afb_req_x2;
  22 struct afb_req_x2_itf;
  23
  24 /* referenced here */
  25 #include "afb-arg.h"
  26 struct afb_req_x1;
  27 struct afb_event_x1;
  28 struct afb_event_x2;
  29 struct afb_api_x3;
  30 struct afb_stored_req;
  31
  32 /** @addtogroup AFB_REQ
  33  *  @{ */
  34
  35 /**
  36  * structure for the request
  37  */
  38 struct afb_req_x2
  39 {
  40         /**
  41          * interface for the request
  42          */
  43         const struct afb_req_x2_itf *itf;
  44
  45         /**
  46          * current api (if any)
  47          */
  48         struct afb_api_x3 *api;
  49
  50         /**
  51          * closure associated with the callback processing the verb of the request
  52          * as given at its declaration
  53          */
  54         void *vcbdata;
  55
  56         /**
  57          * the name of the called api
  58          */
  59         const char *called_api;
  60
  61         /**
  62          * the name of the called verb
  63          */
  64         const char *called_verb;
  65 };
  66
  67 /**
  68  * subcall flags
  69  *
  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.
  72  *
  73  * In particular, the following combination of flags are to be known:
  74  *
  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
  77  *
  78  *  - for **subcall** having the behaviour of the **call**:
  79  *    afb_req_x2_subcall_catch_events|afb_req_x2_subcall_api_session
  80  *
  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.
  83  */
  84 enum afb_req_x2_subcall_flags
  85 {
  86         /**
  87          * the calling API wants to receive the events from subscription
  88          */
  89         afb_req_x2_subcall_catch_events = 1,
  90
  91         /**
  92          * the original request will receive the events from subscription
  93          */
  94         afb_req_x2_subcall_pass_events = 2,
  95
  96         /**
  97          * the calling API wants to use the credentials of the original request
  98          */
  99         afb_req_x2_subcall_on_behalf = 4,
 100
 101         /**
 102          * the calling API wants to use its session instead of the one of the
 103          * original request
 104          */
 105         afb_req_x2_subcall_api_session = 8,
 106 };
 107
 108 /**
 109  * Interface for handling requests.
 110  *
 111  * It records the functions to be called for the request.
 112  * Don't use this structure directly, Use the helper functions instead.
 113  */
 114 struct afb_req_x2_itf
 115 {
 116         /* CAUTION: respect the order, add at the end */
 117
 118         /** get the json */
 119         struct json_object *(*json)(
 120                         struct afb_req_x2 *req);
 121
 122         /** get an argument */
 123         struct afb_arg (*get)(
 124                         struct afb_req_x2 *req,
 125                         const char *name);
 126
 127         /** reply a success @deprecated use @ref reply */
 128         void (*legacy_success)(
 129                         struct afb_req_x2 *req,
 130                         struct json_object *obj,
 131                         const char *info);
 132
 133         /** reply a failure @deprecated use @ref reply */
 134         void (*legacy_fail)(
 135                         struct afb_req_x2 *req,
 136                         const char *status,
 137                         const char *info);
 138
 139         /** reply a success @deprecated use @ref vreply */
 140         void (*legacy_vsuccess)(
 141                         struct afb_req_x2 *req,
 142                         struct json_object *obj,
 143                         const char *fmt,
 144                         va_list args);
 145
 146         /** reply a failure @deprecated use @ref vreply */
 147         void (*legacy_vfail)(
 148                         struct afb_req_x2 *req,
 149                         const char *status,
 150                         const char *fmt,
 151                         va_list args);
 152
 153         /** get a client context @deprecated use @ref context_make */
 154         void *(*legacy_context_get)(
 155                         struct afb_req_x2 *req);
 156
 157         /** set a client context @deprecated use @ref context_make */
 158         void (*legacy_context_set)(
 159                         struct afb_req_x2 *req,
 160                         void *value,
 161                         void (*free_value)(void*));
 162
 163         /** increase reference count of the request */
 164         struct afb_req_x2 *(*addref)(
 165                         struct afb_req_x2 *req);
 166
 167         /** decrease reference count of the request */
 168         void (*unref)(
 169                         struct afb_req_x2 *req);
 170
 171         /** close the client session related to the api of the request */
 172         void (*session_close)(
 173                         struct afb_req_x2 *req);
 174
 175         /** set the levele of assurancy related to the api of the request */
 176         int (*session_set_LOA)(
 177                         struct afb_req_x2 *req,
 178                         unsigned level);
 179
 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);
 184
 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);
 189
 190         /** asynchronous subcall @deprecated use @ref subcall */
 191         void (*legacy_subcall)(
 192                         struct afb_req_x2 *req,
 193                         const char *api,
 194                         const char *verb,
 195                         struct json_object *args,
 196                         void (*callback)(void*, int, struct json_object*),
 197                         void *cb_closure);
 198
 199         /** synchronous subcall @deprecated use @ref subcallsync */
 200         int (*legacy_subcallsync)(
 201                         struct afb_req_x2 *req,
 202                         const char *api,
 203                         const char *verb,
 204                         struct json_object *args,
 205                         struct json_object **result);
 206
 207         /** log a message for the request */
 208         void (*vverbose)(
 209                         struct afb_req_x2 *req,
 210                         int level,
 211                         const char *file,
 212                         int line,
 213                         const char * func,
 214                         const char *fmt,
 215                         va_list args);
 216
 217         /** store the request @deprecated no more needed */
 218         struct afb_stored_req *(*legacy_store_req)(
 219                         struct afb_req_x2 *req);
 220
 221         /** asynchronous subcall with request @deprecated use @ref subcall */
 222         void (*legacy_subcall_req)(
 223                         struct afb_req_x2 *req,
 224                         const char *api,
 225                         const char *verb,
 226                         struct json_object *args,
 227                         void (*callback)(void*, int, struct json_object*, struct afb_req_x1),
 228                         void *cb_closure);
 229
 230         /** store the request @deprecated no more needed */
 231         int (*has_permission)(
 232                         struct afb_req_x2 *req,
 233                         const char *permission);
 234
 235         /** get the application id of the client of the request */
 236         char *(*get_application_id)(
 237                         struct afb_req_x2 *req);
 238
 239         /** handle client context of the api getting the request */
 240         void *(*context_make)(
 241                         struct afb_req_x2 *req,
 242                         int replace,
 243                         void *(*create_value)(void *creation_closure),
 244                         void (*free_value)(void*),
 245                         void *creation_closure);
 246
 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);
 251
 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);
 256
 257         /** asynchronous subcall with request @deprecated use @ref subcall */
 258         void (*legacy_subcall_request)(
 259                         struct afb_req_x2 *req,
 260                         const char *api,
 261                         const char *verb,
 262                         struct json_object *args,
 263                         void (*callback)(void*, int, struct json_object*, struct afb_req_x2 *req),
 264                         void *cb_closure);
 265
 266         /** get the user id  (unix) of the client of the request */
 267         int (*get_uid)(
 268                         struct afb_req_x2 *req);
 269
 270         /** reply to the request */
 271         void (*reply)(
 272                         struct afb_req_x2 *req,
 273                         struct json_object *obj,
 274                         const char *error,
 275                         const char *info);
 276
 277         /** reply to the request with formating of info */
 278         void (*vreply)(
 279                         struct afb_req_x2 *req,
 280                         struct json_object *obj,
 281                         const char *error,
 282                         const char *fmt,
 283                         va_list args);
 284
 285         /** get description of the client of the request */
 286         struct json_object *(*get_client_info)(
 287                         struct afb_req_x2 *req);
 288
 289         /** asynchronous subcall */
 290         void (*subcall)(
 291                         struct afb_req_x2 *req,
 292                         const char *apiname,
 293                         const char *verb,
 294                         struct json_object *args,
 295                         int flags,
 296                         void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_req_x2 *req),
 297                         void *closure);
 298
 299         /** synchronous subcall */
 300         int (*subcallsync)(
 301                         struct afb_req_x2 *req,
 302                         const char *api,
 303                         const char *verb,
 304                         struct json_object *args,
 305                         int flags,
 306                         struct json_object **object,
 307                         char **error,
 308                         char **info);
 309 };
 310
 311
 312 /** @} */