include/afb/afb-req-x2-itf.h

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