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