include/afb/afb-api-x3-itf.h

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