include/afb/afb-plugin.h

   1 /*
   2  * Copyright (C) 2016 "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/afb-req-itf.h>
  21 #include <afb/afb-evmgr-itf.h>
  22
  23 /*
  24  * Definition of the versions of the plugin.
  25  * The definition uses hashes.
  26  */
  27 enum  AFB_plugin_version
  28 {
  29        AFB_PLUGIN_VERSION_1 = 123456789        /* version 1 */
  30 };
  31
  32 /*
  33  * Enum for Session/Token/Authentication middleware.
  34  * This enumeration is valid for plugins of type 1
  35  */
  36 enum AFB_session_v1
  37 {
  38        AFB_SESSION_NONE = 0,   /* no session and no authentification required */
  39        AFB_SESSION_CREATE = 1, /* requires authentification and first call of the session */
  40        AFB_SESSION_CLOSE = 2,  /* closes the session after authentification */
  41        AFB_SESSION_RENEW = 4,  /* refreshes the token after authentification */
  42        AFB_SESSION_CHECK = 8,  /* enforce authentification */
  43        AFB_SESSION_MASK = 15   /* convenient mask used internally, bit-or of the previous masks */
  44 };
  45
  46 /*
  47  * Description of one verb of the API provided by the plugin
  48  * This enumeration is valid for plugins of type 1
  49  */
  50 struct AFB_verb_desc_v1
  51 {
  52        const char *name;                       /* name of the verb */
  53        enum AFB_session_v1 session;            /* authorisation and session requirements of the verb */
  54        void (*callback)(struct afb_req req);   /* callback function implementing the verb */
  55        const char *info;                       /* textual description of the verb */
  56 };
  57
  58 /*
  59  * Description of the plugins of type 1
  60  */
  61 struct AFB_plugin_desc_v1
  62 {
  63        const char *info;                       /* textual information about the plugin */
  64        const char *prefix;                     /* required prefix name for the plugin */
  65        const struct AFB_verb_desc_v1 *verbs;   /* array of descriptions of verbs terminated by a NULL name */
  66 };
  67
  68 /*
  69  * Description of a plugin
  70  */
  71 struct AFB_plugin
  72 {
  73        enum AFB_plugin_version type; /* type of the plugin */
  74        union {
  75                struct AFB_plugin_desc_v1 v1;   /* description of the plugin of type 1 */
  76        };
  77 };
  78
  79 /*
  80  * config mode
  81  */
  82 enum AFB_Mode {
  83        AFB_MODE_LOCAL = 0,     /* run locally */
  84        AFB_MODE_REMOTE,        /* run remotely */
  85        AFB_MODE_GLOBAL         /* run either remotely or locally (DONT USE! reserved for future) */
  86 };
  87
  88 /* declaration of features of libsystemd */
  89 struct sd_event;
  90 struct sd_bus;
  91
  92 /*
  93  * Definition of the facilities provided by the daemon.
  94  */
  95 struct afb_daemon_itf {
  96        struct afb_evmgr (*get_evmgr)(void *closure);           /* get the event manager */
  97        struct sd_event *(*get_event_loop)(void *closure);      /* get the common systemd's event loop */
  98        struct sd_bus *(*get_user_bus)(void *closure);          /* get the common systemd's user d-bus */
  99        struct sd_bus *(*get_system_bus)(void *closure);        /* get the common systemd's system d-bus */
 100 };
 101
 102 /*
 103  * Structure for accessing daemon.
 104  * See also: afb_daemon_get_evmgr, afb_daemon_get_event_loop, afb_daemon_get_user_bus, afb_daemon_get_system_bus
 105  */
 106 struct afb_daemon {
 107        const struct afb_daemon_itf *itf;       /* the interfacing functions */
 108        void *closure;                          /* the closure when calling these functions */
 109 };
 110
 111 /*
 112  * Interface between the daemon and the plugin.
 113  */
 114 struct AFB_interface
 115 {
 116        struct afb_daemon daemon;       /* access to the daemon facilies */
 117        int verbosity;                  /* level of verbosity */
 118        enum AFB_Mode mode;             /* run mode (local or remote) */
 119 };
 120
 121 /*
 122  * The function for registering the plugin to AFB
 123  */
 124 extern const struct AFB_plugin *pluginAfbV1Register (const struct AFB_interface *interface);
 125
 126 /*
 127  * Retrieves the event sender of AFB
 128  * 'daemon' MUST be the daemon given in interface when activating the plugin.
 129  */
 130 static inline struct afb_evmgr afb_daemon_get_evmgr(struct afb_daemon daemon)
 131 {
 132         return daemon.itf->get_evmgr(daemon.closure);
 133 }
 134
 135 /*
 136  * Retrieves the common systemd's event loop of AFB
 137  * 'daemon' MUST be the daemon given in interface when activating the plugin.
 138  */
 139 static inline struct sd_event *afb_daemon_get_event_loop(struct afb_daemon daemon)
 140 {
 141         return daemon.itf->get_event_loop(daemon.closure);
 142 }
 143
 144 /*
 145  * Retrieves the common systemd's user/session d-bus of AFB
 146  * 'daemon' MUST be the daemon given in interface when activating the plugin.
 147  */
 148 static inline struct sd_bus *afb_daemon_get_user_bus(struct afb_daemon daemon)
 149 {
 150         return daemon.itf->get_user_bus(daemon.closure);
 151 }
 152
 153 /*
 154  * Retrieves the common systemd's system d-bus of AFB
 155  * 'daemon' MUST be the daemon given in interface when activating the plugin.
 156  */
 157 static inline struct sd_bus *afb_daemon_get_system_bus(struct afb_daemon daemon)
 158 {
 159         return daemon.itf->get_system_bus(daemon.closure);
 160 }
 161
 162