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 dynapi (is NULL for bindings v1 and v2) */
  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
  62 /*
  63  * Interface for handling requests.
  64  * It records the functions to be called for the request.
  65  * Don't use this structure directly.
  66  * Use the helper functions
  67  */
  68 struct afb_request_itf
  69 {
  70         /* CAUTION: respect the order, add at the end */
  71
  72         struct json_object *(*json)(
  73                         struct afb_request *request);
  74
  75         struct afb_arg (*get)(
  76                         struct afb_request *request,
  77                         const char *name);
  78
  79         void (*success)(
  80                         struct afb_request *request,
  81                         struct json_object *obj,
  82                         const char *info);
  83
  84         void (*fail)(
  85                         struct afb_request *request,
  86                         const char *status,
  87                         const char *info);
  88
  89         void (*vsuccess)(
  90                         struct afb_request *request,
  91                         struct json_object *obj,
  92                         const char *fmt,
  93                         va_list args);
  94
  95         void (*vfail)(
  96                         struct afb_request *request,
  97                         const char *status,
  98                         const char *fmt,
  99                         va_list args);
 100
 101         void *(*context_get)(
 102                         struct afb_request *request);
 103
 104         void (*context_set)(
 105                         struct afb_request *request,
 106                         void *value,
 107                         void (*free_value)(void*));
 108
 109         struct afb_request *(*addref)(
 110                         struct afb_request *request);
 111
 112         void (*unref)(
 113                         struct afb_request *request);
 114
 115         void (*session_close)(
 116                         struct afb_request *request);
 117
 118         int (*session_set_LOA)(
 119                         struct afb_request *request,
 120                         unsigned level);
 121
 122         int (*subscribe)(
 123                         struct afb_request *request,
 124                         struct afb_event event);
 125
 126         int (*unsubscribe)(
 127                         struct afb_request *request,
 128                         struct afb_event event);
 129
 130         void (*subcall)(
 131                         struct afb_request *request,
 132                         const char *api,
 133                         const char *verb,
 134                         struct json_object *args,
 135                         void (*callback)(void*, int, struct json_object*),
 136                         void *cb_closure);
 137
 138         int (*subcallsync)(
 139                         struct afb_request *request,
 140                         const char *api,
 141                         const char *verb,
 142                         struct json_object *args,
 143                         struct json_object **result);
 144
 145         void (*vverbose)(
 146                         struct afb_request *request,
 147                         int level,
 148                         const char *file,
 149                         int line,
 150                         const char * func,
 151                         const char *fmt,
 152                         va_list args);
 153
 154         struct afb_stored_req *(*store)(
 155                         struct afb_request *request);
 156
 157         void (*subcall_req)(
 158                         struct afb_request *request,
 159                         const char *api,
 160                         const char *verb,
 161                         struct json_object *args,
 162                         void (*callback)(void*, int, struct json_object*, struct afb_req),
 163                         void *cb_closure);
 164
 165         int (*has_permission)(
 166                         struct afb_request *request,
 167                         const char *permission);
 168
 169         char *(*get_application_id)(
 170                         struct afb_request *request);
 171
 172         void *(*context_make)(
 173                         struct afb_request *request,
 174                         int replace,
 175                         void *(*create_value)(void *creation_closure),
 176                         void (*free_value)(void*),
 177                         void *creation_closure);
 178
 179         int (*subscribe_eventid)(
 180                         struct afb_request *request,
 181                         struct afb_eventid *eventid);
 182
 183         int (*unsubscribe_eventid)(
 184                         struct afb_request *request,
 185                         struct afb_eventid *eventid);
 186
 187         void (*subcall_request)(
 188                         struct afb_request *request,
 189                         const char *api,
 190                         const char *verb,
 191                         struct json_object *args,
 192                         void (*callback)(void*, int, struct json_object*, struct afb_request *request),
 193                         void *cb_closure);
 194
 195 };
 196