include/afb/afb-dynapi.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 #include "afb-dynapi-itf.h"
  21
  22 static inline const char *afb_dynapi_name(struct afb_dynapi *dynapi)
  23 {
  24         return dynapi->apiname;
  25 }
  26
  27 static inline void *afb_dynapi_get_userdata(struct afb_dynapi *dynapi)
  28 {
  29         return dynapi->userdata;
  30 }
  31
  32 static inline void afb_dynapi_set_userdata(struct afb_dynapi *dynapi, void *userdata)
  33 {
  34         dynapi->userdata = userdata;
  35 }
  36
  37 /*
  38  * Send a message described by 'fmt' and following parameters
  39  * to the journal for the verbosity 'level'.
  40  *
  41  * 'file', 'line' and 'func' are indicators of position of the code in source files
  42  * (see macros __FILE__, __LINE__ and __func__).
  43  *
  44  *
  45  * 'level' is defined by syslog standard:
  46  *      EMERGENCY         0        System is unusable
  47  *      ALERT             1        Action must be taken immediately
  48  *      CRITICAL          2        Critical conditions
  49  *      ERROR             3        Error conditions
  50  *      WARNING           4        Warning conditions
  51  *      NOTICE            5        Normal but significant condition
  52  *      INFO              6        Informational
  53  *      DEBUG             7        Debug-level messages
  54  */
  55 static inline void afb_dynapi_verbose(struct afb_dynapi *dynapi, int level, const char *file, int line, const char *func, const char *fmt, ...) __attribute__((format(printf, 6, 7)));
  56 static inline void afb_dynapi_verbose(struct afb_dynapi *dynapi, int level, const char *file, int line, const char *func, const char *fmt, ...)
  57 {
  58         va_list args;
  59         va_start(args, fmt);
  60         dynapi->itf->vverbose(dynapi, level, file, line, func, fmt, args);
  61         va_end(args);
  62 }
  63 static inline void afb_dynapi_vverbose(struct afb_dynapi *dynapi, int level, const char *file, int line, const char *func, const char *fmt, va_list args)
  64 {
  65         dynapi->itf->vverbose(dynapi, level, file, line, func, fmt, args);
  66 }
  67
  68 /*
  69  * Retrieves the common systemd's event loop of AFB
  70  */
  71 static inline struct sd_event *afb_dynapi_get_event_loop(struct afb_dynapi *dynapi)
  72 {
  73         return dynapi->itf->get_event_loop(dynapi);
  74 }
  75
  76 /*
  77  * Retrieves the common systemd's user/session d-bus of AFB
  78  */
  79 static inline struct sd_bus *afb_dynapi_get_user_bus(struct afb_dynapi *dynapi)
  80 {
  81         return dynapi->itf->get_user_bus(dynapi);
  82 }
  83
  84 /*
  85  * Retrieves the common systemd's system d-bus of AFB
  86  */
  87 static inline struct sd_bus *afb_dynapi_get_system_bus(struct afb_dynapi *dynapi)
  88 {
  89         return dynapi->itf->get_system_bus(dynapi);
  90 }
  91
  92 /*
  93  * Get the root directory file descriptor. This file descriptor can
  94  * be used with functions 'openat', 'fstatat', ...
  95  */
  96 static inline int afb_dynapi_rootdir_get_fd(struct afb_dynapi *dynapi)
  97 {
  98         return dynapi->itf->rootdir_get_fd(dynapi);
  99 }
 100
 101 /*
 102  * Opens 'filename' within the root directory with 'flags' (see function openat)
 103  * using the 'locale' definition (example: "jp,en-US") that can be NULL.
 104  * Returns the file descriptor or -1 in case of error.
 105  */
 106 static inline int afb_dynapi_rootdir_open_locale(struct afb_dynapi *dynapi, const char *filename, int flags, const char *locale)
 107 {
 108         return dynapi->itf->rootdir_open_locale(dynapi, filename, flags, locale);
 109 }
 110
 111 /*
 112  * Queue the job defined by 'callback' and 'argument' for being executed asynchronously
 113  * in this thread (later) or in an other thread.
 114  * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group')
 115  * are executed in sequence in the order of there submission.
 116  * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds.
 117  * At first, the job is called with 0 as signum and the given argument.
 118  * The job is executed with the monitoring of its time and some signals like SIGSEGV and
 119  * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with
 120  * signum being the signal number (SIGALRM when timeout expired).
 121  *
 122  * Returns 0 in case of success or -1 in case of error.
 123  */
 124 static inline int afb_dynapi_queue_job(struct afb_dynapi *dynapi, void (*callback)(int signum, void *arg), void *argument, void *group, int timeout)
 125 {
 126         return dynapi->itf->queue_job(dynapi, callback, argument, group, timeout);
 127 }
 128
 129 /*
 130  * Tells that it requires the API of "name" to exist
 131  * and if 'initialized' is not null to be initialized.
 132  * Calling this function is only allowed within init.
 133  * Returns 0 in case of success or -1 in case of error.
 134  */
 135 static inline int afb_dynapi_require_api(struct afb_dynapi *dynapi, const char *name, int initialized)
 136 {
 137         return dynapi->itf->require_api(dynapi, name, initialized);
 138 }
 139
 140 /*
 141  * Set the name of the API to 'name'.
 142  * Calling this function is only allowed within preinit.
 143  * Returns 0 in case of success or -1 in case of error.
 144  */
 145 static inline int afb_dynapi_rename_api(struct afb_dynapi *dynapi, const char *name)
 146 {
 147         return dynapi->itf->rename_api(dynapi, name);
 148 }
 149
 150 /*
 151  * Broadcasts widely the event of 'name' with the data 'object'.
 152  * 'object' can be NULL.
 153  *
 154  * For convenience, the function calls 'json_object_put' for 'object'.
 155  * Thus, in the case where 'object' should remain available after
 156  * the function returns, the function 'json_object_get' shall be used.
 157  *
 158  * Calling this function is only forbidden during preinit.
 159  *
 160  * Returns the count of clients that received the event.
 161  */
 162 static inline int afb_dynapi_broadcast_event(struct afb_dynapi *dynapi, const char *name, struct json_object *object)
 163 {
 164         return dynapi->itf->event_broadcast(dynapi, name, object);
 165 }
 166
 167 /*
 168  * Creates an event of 'name' and returns it.
 169  *
 170  * Calling this function is only forbidden during preinit.
 171  *
 172  * See afb_event_is_valid to check if there is an error.
 173  */
 174 static inline struct afb_eventid *afb_dynapi_make_eventid(struct afb_dynapi *dynapi, const char *name)
 175 {
 176         return dynapi->itf->eventid_make(dynapi, name);
 177 }
 178
 179 /**
 180  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 181  * The result of the call is delivered to the 'callback' function with the 'callback_closure'.
 182  *
 183  * For convenience, the function calls 'json_object_put' for 'args'.
 184  * Thus, in the case where 'args' should remain available after
 185  * the function returns, the function 'json_object_get' shall be used.
 186  *
 187  * The 'callback' receives 3 arguments:
 188  *  1. 'closure' the user defined closure pointer 'callback_closure',
 189  *  2. 'status' a status being 0 on success or negative when an error occured,
 190  *  2. 'result' the resulting data as a JSON object.
 191  *
 192  * @param dynapi   The dynapi
 193  * @param api      The api name of the method to call
 194  * @param verb     The verb name of the method to call
 195  * @param args     The arguments to pass to the method
 196  * @param callback The to call on completion
 197  * @param callback_closure The closure to pass to the callback
 198  *
 199  * @see also 'afb_req_subcall'
 200  */
 201 static inline void afb_dynapi_call(
 202         struct afb_dynapi *dynapi,
 203         const char *api,
 204         const char *verb,
 205         struct json_object *args,
 206         void (*callback)(void *closure, int status, struct json_object *result, struct afb_dynapi *dynapi),
 207         void *callback_closure)
 208 {
 209         dynapi->itf->call(dynapi, api, verb, args, callback, callback_closure);
 210 }
 211
 212 /**
 213  * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding.
 214  * 'result' will receive the response.
 215  *
 216  * For convenience, the function calls 'json_object_put' for 'args'.
 217  * Thus, in the case where 'args' should remain available after
 218  * the function returns, the function 'json_object_get' shall be used.
 219  *
 220  * @param dynapi   The dynapi
 221  * @param api      The api name of the method to call
 222  * @param verb     The verb name of the method to call
 223  * @param args     The arguments to pass to the method
 224  * @param result   Where to store the result - should call json_object_put on it -
 225  *
 226  * @returns 0 in case of success or a negative value in case of error.
 227  *
 228  * @see also 'afb_req_subcall'
 229  */
 230 static inline int afb_dynapi_call_sync(
 231         struct afb_dynapi *dynapi,
 232         const char *api,
 233         const char *verb,
 234         struct json_object *args,
 235         struct json_object **result)
 236 {
 237         return dynapi->itf->call_sync(dynapi, api, verb, args, result);
 238 }
 239
 240
 241 static inline int afb_dynapi_new_api(
 242         struct afb_dynapi *dynapi,
 243         const char *api,
 244         const char *info,
 245         int (*preinit)(void*, struct afb_dynapi *),
 246         void *closure)
 247 {
 248         return dynapi->itf->api_new_api(dynapi, api, info, preinit, closure);
 249 }
 250
 251 static inline int afb_dynapi_set_verbs_v2(
 252         struct afb_dynapi *dynapi,
 253         const struct afb_verb_v2 *verbs)
 254 {
 255         return dynapi->itf->api_set_verbs_v2(dynapi, verbs);
 256 }
 257
 258 static inline int afb_dynapi_add_verb(
 259         struct afb_dynapi *dynapi,
 260         const char *verb,
 261         const char *info,
 262         void (*callback)(struct afb_request *request),
 263         void *vcbdata,
 264         const struct afb_auth *auth,
 265         uint32_t session)
 266 {
 267         return dynapi->itf->api_add_verb(dynapi, verb, info, callback, vcbdata, auth, session);
 268 }
 269
 270
 271 static inline int afb_dynapi_sub_verb(
 272                 struct afb_dynapi *dynapi,
 273                 const char *verb)
 274 {
 275         return dynapi->itf->api_sub_verb(dynapi, verb);
 276 }
 277
 278
 279 static inline int afb_dynapi_on_event(
 280                 struct afb_dynapi *dynapi,
 281                 void (*onevent)(struct afb_dynapi *dynapi, const char *event, struct json_object *object))
 282 {
 283         return dynapi->itf->api_set_on_event(dynapi, onevent);
 284 }
 285
 286
 287 static inline int afb_dynapi_on_init(
 288                 struct afb_dynapi *dynapi,
 289                 int (*oninit)(struct afb_dynapi *dynapi))
 290 {
 291         return dynapi->itf->api_set_on_init(dynapi, oninit);
 292 }
 293
 294
 295 static inline void afb_dynapi_seal(
 296                 struct afb_dynapi *dynapi)
 297 {
 298         dynapi->itf->api_seal(dynapi);
 299 }
 300
 301