include/afb/afb-request-itf.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 /* defined here */
  21 struct afb_arg;
  22 struct afb_request;
  23 struct afb_request_itf;
  24
  25 /* referenced here */
  26 #include <stdarg.h>
  27 struct json_object;
  28 struct afb_req;
  29 struct afb_event;
  30 struct afb_eventid;
  31 struct afb_dynapi;
  32 struct afb_stored_req;
  33
  34 /*
  35  * Describes an argument (or parameter) of a request
  36  */
  37 struct afb_arg
  38 {
  39         const char *name;       /* name of the argument or NULL if invalid */
  40         const char *value;      /* string representation of the value of the argument */
  41                                 /* original filename of the argument if path != NULL */
  42         const char *path;       /* if not NULL, path of the received file for the argument */
  43                                 /* when the request is finalized this file is removed */
  44 };
  45
  46 /*
  47  * structure for the request
  48  */
  49 struct afb_request
  50 {
  51         /* interface for the request */
  52         const struct afb_request_itf *itf;
  53
  54         /* current dynapi (if any) */
  55         struct afb_dynapi *dynapi;
  56
  57         /* closure associated with the callback processing the verb of the request
  58          * as given at its declaration */
  59         void *vcbdata;
  60
  61         /* the name of the called verb */
  62         const char *api;
  63
  64         /* the name of the called verb */
  65         const char *verb;
  66 };
  67
  68 /*
  69  * Interface for handling requests.
  70  * It records the functions to be called for the request.
  71  * Don't use this structure directly.
  72  * Use the helper functions
  73  */
  74 struct afb_request_itf
  75 {
  76         /* CAUTION: respect the order, add at the end */
  77
  78         struct json_object *(*json)(
  79                         struct afb_request *request);
  80
  81         struct afb_arg (*get)(
  82                         struct afb_request *request,
  83                         const char *name);
  84
  85         void (*success)(
  86                         struct afb_request *request,
  87                         struct json_object *obj,
  88                         const char *info);
  89
  90         void (*fail)(
  91                         struct afb_request *request,
  92                         const char *status,
  93                         const char *info);
  94
  95         void (*vsuccess)(
  96                         struct afb_request *request,
  97                         struct json_object *obj,
  98                         const char *fmt,
  99                         va_list args);
 100
 101         void (*vfail)(
 102                         struct afb_request *request,
 103                         const char *status,
 104                         const char *fmt,
 105                         va_list args);
 106
 107         void *(*context_get)(
 108                         struct afb_request *request);
 109
 110         void (*context_set)(
 111                         struct afb_request *request,
 112                         void *value,
 113                         void (*free_value)(void*));
 114
 115         struct afb_request *(*addref)(
 116                         struct afb_request *request);
 117
 118         void (*unref)(
 119                         struct afb_request *request);
 120
 121         void (*session_close)(
 122                         struct afb_request *request);
 123
 124         int (*session_set_LOA)(
 125                         struct afb_request *request,
 126                         unsigned level);
 127
 128         int (*subscribe)(
 129                         struct afb_request *request,
 130                         struct afb_event event);
 131
 132         int (*unsubscribe)(
 133                         struct afb_request *request,
 134                         struct afb_event event);
 135
 136         void (*subcall)(
 137                         struct afb_request *request,
 138                         const char *api,
 139                         const char *verb,
 140                         struct json_object *args,
 141                         void (*callback)(void*, int, struct json_object*),
 142                         void *cb_closure);
 143
 144         int (*subcallsync)(
 145                         struct afb_request *request,
 146                         const char *api,
 147                         const char *verb,
 148                         struct json_object *args,
 149                         struct json_object **result);
 150
 151         void (*vverbose)(
 152                         struct afb_request *request,
 153                         int level,
 154                         const char *file,
 155                         int line,
 156                         const char * func,
 157                         const char *fmt,
 158                         va_list args);
 159
 160         struct afb_stored_req *(*store)(
 161                         struct afb_request *request);
 162
 163         void (*subcall_req)(
 164                         struct afb_request *request,
 165                         const char *api,
 166                         const char *verb,
 167                         struct json_object *args,
 168                         void (*callback)(void*, int, struct json_object*, struct afb_req),
 169                         void *cb_closure);
 170
 171         int (*has_permission)(
 172                         struct afb_request *request,
 173                         const char *permission);
 174
 175         char *(*get_application_id)(
 176                         struct afb_request *request);
 177
 178         void *(*context_make)(
 179                         struct afb_request *request,
 180                         int replace,
 181                         void *(*create_value)(void *creation_closure),
 182                         void (*free_value)(void*),
 183                         void *creation_closure);
 184
 185         int (*subscribe_eventid)(
 186                         struct afb_request *request,
 187                         struct afb_eventid *eventid);
 188
 189         int (*unsubscribe_eventid)(
 190                         struct afb_request *request,
 191                         struct afb_eventid *eventid);
 192
 193         void (*subcall_request)(
 194                         struct afb_request *request,
 195                         const char *api,
 196                         const char *verb,
 197                         struct json_object *args,
 198                         void (*callback)(void*, int, struct json_object*, struct afb_request *request),
 199                         void *cb_closure);
 200
 201 };
 202