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_stored_req;
  32
  33 /*
  34  * Describes an argument (or parameter) of a request
  35  */
  36 struct afb_arg
  37 {
  38         const char *name;       /* name of the argument or NULL if invalid */
  39         const char *value;      /* string representation of the value of the argument */
  40                                 /* original filename of the argument if path != NULL */
  41         const char *path;       /* if not NULL, path of the received file for the argument */
  42                                 /* when the request is finalized this file is removed */
  43 };
  44
  45 struct afb_request
  46 {
  47         const struct afb_request_itf *itf;
  48 };
  49
  50 /*
  51  * Interface for handling requests.
  52  * It records the functions to be called for the request.
  53  * Don't use this structure directly.
  54  * Use the helper functions
  55  */
  56 struct afb_request_itf
  57 {
  58         /* CAUTION: respect the order, add at the end */
  59
  60         struct json_object *(*json)(
  61                         struct afb_request *request);
  62
  63         struct afb_arg (*get)(
  64                         struct afb_request *request,
  65                         const char *name);
  66
  67         void (*success)(
  68                         struct afb_request *request,
  69                         struct json_object *obj,
  70                         const char *info);
  71
  72         void (*fail)(
  73                         struct afb_request *request,
  74                         const char *status,
  75                         const char *info);
  76
  77         void (*vsuccess)(
  78                         struct afb_request *request,
  79                         struct json_object *obj,
  80                         const char *fmt,
  81                         va_list args);
  82
  83         void (*vfail)(
  84                         struct afb_request *request,
  85                         const char *status,
  86                         const char *fmt,
  87                         va_list args);
  88
  89         void *(*context_get)(
  90                         struct afb_request *request);
  91
  92         void (*context_set)(
  93                         struct afb_request *request,
  94                         void *value,
  95                         void (*free_value)(void*));
  96
  97         void (*addref)(
  98                         struct afb_request *request);
  99
 100         void (*unref)(
 101                         struct afb_request *request);
 102
 103         void (*session_close)(
 104                         struct afb_request *request);
 105
 106         int (*session_set_LOA)(
 107                         struct afb_request *request,
 108                         unsigned level);
 109
 110         int (*subscribe)(
 111                         struct afb_request *request,
 112                         struct afb_event event);
 113
 114         int (*unsubscribe)(
 115                         struct afb_request *request,
 116                         struct afb_event event);
 117
 118         void (*subcall)(
 119                         struct afb_request *request,
 120                         const char *api,
 121                         const char *verb,
 122                         struct json_object *args,
 123                         void (*callback)(void*, int, struct json_object*),
 124                         void *cb_closure);
 125
 126         int (*subcallsync)(
 127                         struct afb_request *request,
 128                         const char *api,
 129                         const char *verb,
 130                         struct json_object *args,
 131                         struct json_object **result);
 132
 133         void (*vverbose)(
 134                         struct afb_request *request,
 135                         int level,
 136                         const char *file,
 137                         int line,
 138                         const char * func,
 139                         const char *fmt,
 140                         va_list args);
 141
 142         struct afb_stored_req *(*store)(
 143                         struct afb_request *request);
 144
 145         void (*subcall_req)(
 146                         struct afb_request *request,
 147                         const char *api,
 148                         const char *verb,
 149                         struct json_object *args,
 150                         void (*callback)(void*, int, struct json_object*, struct afb_req),
 151                         void *cb_closure);
 152
 153         int (*has_permission)(
 154                         struct afb_request *request,
 155                         const char *permission);
 156
 157         char *(*get_application_id)(
 158                         struct afb_request *request);
 159
 160         void *(*context_make)(
 161                         struct afb_request *request,
 162                         int replace,
 163                         void *(*create_value)(void *creation_closure),
 164                         void (*free_value)(void*),
 165                         void *creation_closure);
 166 };
 167