include/afb/afb-api-x3-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 /* declared here */
  21 struct afb_api_x3;
  22 struct afb_api_x3_itf;
  23
  24 /* referenced here */
  25 struct sd_event;
  26 struct sd_bus;
  27 struct afb_req_x2;
  28 struct afb_event_x2;
  29 struct afb_auth;
  30 struct afb_verb_v2;
  31 struct afb_verb_v3;
  32
  33 /**
  34  * Structure for the APIv3
  35  */
  36 struct afb_api_x3
  37 {
  38         /**
  39          * Interface functions
  40          *
  41          * Don't use it directly, prefer helper functions.
  42          */
  43         const struct afb_api_x3_itf *itf;
  44
  45         /**
  46          * The name of the api
  47          *
  48          * @see afb_api_x3_name
  49          */
  50         const char *apiname;
  51
  52         /**
  53          * User defined data
  54          *
  55          * @see afb_api_x3_set_userdata
  56          * @see afb_api_x3_get_userdata
  57          */
  58         void *userdata;
  59
  60         /**
  61          * Current verbosity mask
  62          *
  63          * The bits tells what verbosity is required for the api.
  64          * It is related to the syslog levels.
  65          *
  66          *      EMERGENCY         0        System is unusable
  67          *      ALERT             1        Action must be taken immediately
  68          *      CRITICAL          2        Critical conditions
  69          *      ERROR             3        Error conditions
  70          *      WARNING           4        Warning conditions
  71          *      NOTICE            5        Normal but significant condition
  72          *      INFO              6        Informational
  73          *      DEBUG             7        Debug-level messages
  74          */
  75         int logmask;
  76 };
  77
  78 /**
  79  * Definition of the function's interface for the APIv3
  80  */
  81 struct afb_api_x3_itf
  82 {
  83         /* CAUTION: respect the order, add at the end */
  84
  85         /** sending log messages */
  86         void (*vverbose)(
  87                 struct afb_api_x3 *api,
  88                 int level,
  89                 const char *file,
  90                 int line,
  91                 const char * func,
  92                 const char *fmt,
  93                 va_list args);
  94
  95         /** gets the common systemd's event loop */
  96         struct sd_event *(*get_event_loop)(
  97                 struct afb_api_x3 *api);
  98
  99         /** gets the common systemd's user d-bus */
 100         struct sd_bus *(*get_user_bus)(
 101                 struct afb_api_x3 *api);
 102
 103         /** gets the common systemd's system d-bus */
 104         struct sd_bus *(*get_system_bus)(
 105                 struct afb_api_x3 *api);
 106
 107         /** get the file descriptor for the root directory */
 108         int (*rootdir_get_fd)(
 109                 struct afb_api_x3 *api);
 110
 111         /** get a file using locale setting */
 112         int (*rootdir_open_locale)(
 113                 struct afb_api_x3 *api,
 114                 const char *filename,
 115                 int flags,
 116                 const char *locale);
 117
 118         /** queue a job */
 119         int (*queue_job)(
 120                 struct afb_api_x3 *api,
 121                 void (*callback)(int signum, void *arg),
 122                 void *argument,
 123                 void *group,
 124                 int timeout);
 125
 126         /** requires an api initialized or not */
 127         int (*require_api)(
 128                 struct afb_api_x3 *api,
 129                 const char *name,
 130                 int initialized);
 131
 132         /** add an alias */
 133         int (*add_alias)(
 134                 struct afb_api_x3 *api,
 135                 const char *name,
 136                 const char *as_name);
 137
 138         /** broadcasts event 'name' with 'object' */
 139         int (*event_broadcast)(
 140                 struct afb_api_x3 *api,
 141                 const char *name,
 142                 struct json_object *object);
 143
 144         /** creates an event of 'name' */
 145         struct afb_event_x2 *(*event_make)(
 146                 struct afb_api_x3 *api,
 147                 const char *name);
 148
 149         /** legacy asynchronous invocation */
 150         void (*legacy_call)(
 151                 struct afb_api_x3 *api,
 152                 const char *apiname,
 153                 const char *verb,
 154                 struct json_object *args,
 155                 void (*callback)(void*, int, struct json_object*, struct afb_api_x3 *),
 156                 void *closure);
 157
 158         /** legacy synchronous invocation */
 159         int (*legacy_call_sync)(
 160                 struct afb_api_x3 *api,
 161                 const char *apiname,
 162                 const char *verb,
 163                 struct json_object *args,
 164                 struct json_object **result);
 165
 166         /** creation of a new api*/
 167         struct afb_api_x3 *(*api_new_api)(
 168                 struct afb_api_x3 *api,
 169                 const char *apiname,
 170                 const char *info,
 171                 int noconcurrency,
 172                 int (*preinit)(void*, struct afb_api_x3 *),
 173                 void *closure);
 174
 175         /** set verbs of the api using v2 description */
 176         int (*api_set_verbs_v2)(
 177                 struct afb_api_x3 *api,
 178                 const struct afb_verb_v2 *verbs);
 179
 180         /** add one verb to the api */
 181         int (*api_add_verb)(
 182                 struct afb_api_x3 *api,
 183                 const char *verb,
 184                 const char *info,
 185                 void (*callback)(struct afb_req_x2 *req),
 186                 void *vcbdata,
 187                 const struct afb_auth *auth,
 188                 uint32_t session,
 189                 int glob);
 190
 191         /** delete one verb of the api */
 192         int (*api_del_verb)(
 193                 struct afb_api_x3 *api,
 194                 const char *verb,
 195                 void **vcbdata);
 196
 197         /** set the api's callback for processing events */
 198         int (*api_set_on_event)(
 199                 struct afb_api_x3 *api,
 200                 void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object));
 201
 202         /** set the api's callback for initialisation */
 203         int (*api_set_on_init)(
 204                 struct afb_api_x3 *api,
 205                 int (*oninit)(struct afb_api_x3 *api));
 206
 207         /** seal the api */
 208         void (*api_seal)(
 209                 struct afb_api_x3 *api);
 210
 211         /** set verbs of the api using v3 description */
 212         int (*api_set_verbs_v3)(
 213                 struct afb_api_x3 *api,
 214                 const struct afb_verb_v3 *verbs);
 215
 216         /** add an event handler for the api */
 217         int (*event_handler_add)(
 218                 struct afb_api_x3 *api,
 219                 const char *pattern,
 220                 void (*callback)(void *, const char*, struct json_object*, struct afb_api_x3*),
 221                 void *closure);
 222
 223         /** delete an event handler of the api */
 224         int (*event_handler_del)(
 225                 struct afb_api_x3 *api,
 226                 const char *pattern,
 227                 void **closure);
 228
 229         /** asynchronous call for the api */
 230         void (*call)(
 231                 struct afb_api_x3 *api,
 232                 const char *apiname,
 233                 const char *verb,
 234                 struct json_object *args,
 235                 void (*callback)(void*, struct json_object*, const char*, const char*, struct afb_api_x3 *),
 236                 void *closure);
 237
 238         /** synchronous call for the api */
 239         int (*call_sync)(
 240                 struct afb_api_x3 *api,
 241                 const char *apiname,
 242                 const char *verb,
 243                 struct json_object *args,
 244                 struct json_object **result,
 245                 char **error,
 246                 char **info);
 247
 248         /** indicate provided classes of the api */
 249         int (*class_provide)(
 250                 struct afb_api_x3 *api,
 251                 const char *name);
 252
 253         /** indicate required classes of the api */
 254         int (*class_require)(
 255                 struct afb_api_x3 *api,
 256                 const char *name);
 257
 258         /** delete the api */
 259         int (*delete_api)(
 260                 struct afb_api_x3 *api);
 261 };
 262