src/include/core/plugin.h

   1 /*
   2  * SysDB - src/include/core/plugin.h
   3  * Copyright (C) 2012 Sebastian 'tokkee' Harl <sh@tokkee.org>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  19  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef SDB_CORE_PLUGIN_H
  29 #define SDB_CORE_PLUGIN_H 1
  30
  31 #include "sysdb.h"
  32 #include "core/object.h"
  33 #include "core/time.h"
  34
  35 #include "liboconfig/oconfig.h"
  36
  37 #include <stdarg.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 typedef struct {
  44         sdb_time_t interval;
  45 } sdb_plugin_ctx_t;
  46 #define SDB_PLUGIN_CTX_INIT { 0 }
  47
  48 typedef struct {
  49         char *plugin_name;
  50         char *filename;
  51
  52         /* public attributes */
  53         char *description;
  54         char *copyright;
  55         char *license;
  56
  57         int   version;
  58         int   plugin_version;
  59 } sdb_plugin_info_t;
  60 #define SDB_PLUGIN_INFO_INIT { \
  61         /* plugin_name */ NULL, /* filename */ NULL, /* desc */ NULL, \
  62         /* copyright */ NULL, /* license */ NULL, \
  63         /* version */ -1, /* plugin_version */ -1 }
  64
  65 /* this should be used in the header of a plugin to avoid
  66  * missing prototype warnings/errors for the plugin init
  67  * function */
  68 #define SDB_PLUGIN_MAGIC \
  69         int sdb_module_init(sdb_plugin_info_t *info)
  70
  71 typedef struct {
  72         _Bool do_loop;
  73         sdb_time_t default_interval;
  74 } sdb_plugin_loop_t;
  75 #define SDB_PLUGIN_LOOP_INIT { 1, 0 }
  76
  77 /*
  78  * sdb_plugin_load:
  79  * Load (any type of) plugin by loading the shared object file and calling the
  80  * sdb_module_init function. If specified, 'plugin_ctx' fine-tunes the
  81  * behavior of the plugin. If specified, the plugin will be looked up in
  82  * 'basedir', else it defaults to the package libdir.
  83  */
  84 int
  85 sdb_plugin_load(const char *basedir, const char *name,
  86                 const sdb_plugin_ctx_t *plugin_ctx);
  87
  88 /*
  89  * sdb_plugin_set_info:
  90  * Fill in the fields of the sdb_plugin_info_t object passed to the
  91  * sdb_module_init function. This information is used to identify the plugin
  92  * and also to provide additional information to the user.
  93  */
  94 enum {
  95         SDB_PLUGIN_INFO_DESC,          /* plugin description: string */
  96         SDB_PLUGIN_INFO_COPYRIGHT,     /* plugin copyright: string */
  97         SDB_PLUGIN_INFO_LICENSE,       /* plugin license: string */
  98         SDB_PLUGIN_INFO_VERSION,       /* libsysdb version: integer */
  99         SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
 100 };
 101
 102 int
 103 sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
 104
 105 /*
 106  * plugin callback functions:
 107  * See the description of the respective register function for what arguments
 108  * the callbacks expect.
 109  *
 110  * The specified name of callback functions is prepended with the plugin name
 111  * before being registered with the core.
 112  */
 113
 114 typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci);
 115 typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data);
 116 typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data);
 117 typedef char *(*sdb_plugin_cname_cb)(const char *name,
 118                 sdb_object_t *user_data);
 119 typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data);
 120 typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
 121                 sdb_object_t *user_data);
 122
 123 /*
 124  * sdb_plugin_register_config:
 125  * Register a "config" function. This will be used to pass on the
 126  * configuration for a plugin. The plugin has to make sure that the function
 127  * can be called multiple times in order to process multiple <Plugin> blocks
 128  * specified in the configuration file(s).
 129  *
 130  * Returns:
 131  *  - 0 on success
 132  *  - a negative value else
 133  */
 134 int
 135 sdb_plugin_register_config(sdb_plugin_config_cb callback);
 136
 137 /*
 138  * sdb_plugin_register_init:
 139  * Register an "init" function. All "init" functions will be called after
 140  * finishing the config parsing and before starting any other work. The
 141  * functions will be called in the same order as they have been registered,
 142  * that is, functions of different plugins will be called in the same order as
 143  * the appropriate "Load" statements in the config file.
 144  *
 145  * If the "init" function returns a non-zero value, *all* callbacks of the
 146  * plugin will be unloaded.
 147  *
 148  * Arguments:
 149  *  - user_data: If specified, this will be passed on to each call of the
 150  *    callback. The function will take ownership of the object, that is,
 151  *    increment the reference count by one. In case the caller does not longer
 152  *    use the object for other purposes, it should thus deref it.
 153  *
 154  * Returns:
 155  *  - 0 on success
 156  *  - a negative value else
 157  */
 158 int
 159 sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback,
 160                 sdb_object_t *user_data);
 161
 162 /*
 163  * sdb_plugin_register_collector:
 164  * Register a "collector" function. This is where a backend is doing its main
 165  * work. This function will be called whenever an update of a backend has been
 166  * requested (either by regular interval or by user request). The backend
 167  * should then query the appropriate data-source and submit all values to the
 168  * core.
 169  *
 170  * Arguments:
 171  *  - interval: Specifies the regular interval at which to update the backend.
 172  *    If this is NULL, global settings will be used.
 173  *  - user_data: If specified, this will be passed on to each call of the
 174  *    callback. The function will take ownership of the object, that is,
 175  *    increment the reference count by one. In case the caller does not longer
 176  *    use the object for other purposes, it should thus deref it.
 177  *
 178  * Returns:
 179  *  - 0 on success
 180  *  - a negative value else
 181  */
 182 int
 183 sdb_plugin_register_collector(const char *name,
 184                 sdb_plugin_collector_cb callback,
 185                 const sdb_time_t *interval, sdb_object_t *user_data);
 186
 187 /*
 188  * sdb_plugin_register_cname:
 189  * Register a "cname" (canonicalize name) function. This type of function is
 190  * called whenever a host is stored. It accepts the hostname and returns a
 191  * canonicalized hostname which will then be used to actually store the host.
 192  * If multiple such callbacks are registered, each one of them will be called
 193  * in the order they have been registered, each one receiving the result of
 194  * the previous callback. If the function returns NULL, the original hostname
 195  * is not changed. Any other value has to be dynamically allocated. It will be
 196  * freed later on by the core.
 197  *
 198  * Returns:
 199  *  - 0 on success
 200  *  - a negative value else
 201  */
 202 int
 203 sdb_plugin_register_cname(const char *name, sdb_plugin_cname_cb callback,
 204                 sdb_object_t *user_data);
 205
 206 /*
 207  * sdb_plugin_register_shutdown:
 208  * Register a "shutdown" function to be called after stopping all update
 209  * processes and before shutting down the daemon.
 210  *
 211  * Arguments:
 212  *  - user_data: If specified, this will be passed on to each call of the
 213  *    callback. The function will take ownership of the object, that is,
 214  *    increment the reference count by one. In case the caller does not longer
 215  *    use the object for other purposes, it should thus deref it.
 216  */
 217 int
 218 sdb_plugin_register_shutdown(const char *name,
 219                 sdb_plugin_shutdown_cb callback,
 220                 sdb_object_t *user_data);
 221
 222 /*
 223  * sdb_plugin_register_log:
 224  * Register a "log" function to be called whenever logging is to be done.
 225  *
 226  * Arguments:
 227  *  - user_data: If specified, this will be passed on to each call of the
 228  *    callback. The function will take ownership of the object, that is,
 229  *    increment the reference count by one. In case the caller does not longer
 230  *    use the object for other purposes, it should thus deref it.
 231  */
 232 int
 233 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
 234                 sdb_object_t *user_data);
 235
 236 /*
 237  * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
 238  * The plugin context defines a set of settings that are available whenever a
 239  * plugin has been called. It may be used to pass around various information
 240  * between the different component of the library without having each and
 241  * every plugin care about it.
 242  *
 243  * If non-NULL, sdb_plugin_set_ctx stores the previous context in the location
 244  * pointed to by 'old'.
 245  */
 246 sdb_plugin_ctx_t
 247 sdb_plugin_get_ctx(void);
 248 int
 249 sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old);
 250
 251 /*
 252  * sdb_plugin_configure:
 253  * Configure the plugin called 'name' using the config tree 'ci'. The plugin
 254  * name is the same as the one used when loading the plugin.
 255  *
 256  * Returns:
 257  *  - 0 on success
 258  *  - a negative value else
 259  */
 260 int
 261 sdb_plugin_configure(const char *name, oconfig_item_t *ci);
 262
 263 /*
 264  * sdb_plugin_reconfigure_init, sdb_plugin_reconfigure_finish:
 265  * Reconfigure all plugins. This happens in multiple steps: first, call
 266  * sdb_plugin_reconfigure_init to deconfigure all plugins by calling their
 267  * config callbacks with a NULL config tree and unregistering all callbacks.
 268  * Then, sdb_plugin_configure and other functions may be used to provide the
 269  * new configuration or load new plugins. For all plugins which were already
 270  * loaded before, sdb_module_init will be called with a NULL argument when
 271  * reloading them.
 272  * Finally, sdb_plugin_reconfigure_finish will clean up leftover pieces, like
 273  * unloading plugins which are no longer in use.
 274  *
 275  * Returns:
 276  *  - 0 on success
 277  *  - a negative value else
 278  */
 279 int
 280 sdb_plugin_reconfigure_init(void);
 281 int
 282 sdb_plugin_reconfigure_finish(void);
 283
 284 /*
 285  * sdb_plugin_init_all:
 286  * Initialize all plugins using their registered "init" function.
 287  *
 288  * Returns:
 289  * The number of failed initializations.
 290  */
 291 int
 292 sdb_plugin_init_all(void);
 293
 294 /*
 295  * sdb_plugin_shutdown_all:
 296  * Shutdown all plugins using their registered "shutdown" function.
 297  *
 298  * Returns:
 299  * The number of failed shutdowns.
 300  */
 301 int
 302 sdb_plugin_shutdown_all(void);
 303
 304 /*
 305  * sdb_plugin_collector_loop:
 306  * Loop until loop->do_loop is false, calling the next collector function on
 307  * each iteration and once its next update interval is passed.
 308  *
 309  * Returns:
 310  *  - 0 on success
 311  *  - a negative value else
 312  */
 313 int
 314 sdb_plugin_collector_loop(sdb_plugin_loop_t *loop);
 315
 316 /*
 317  * sdb_plugin_cname:
 318  * Returns the canonicalized hostname. The given hostname argument has to
 319  * point to dynamically allocated memory and might be freed by the function.
 320  * The return value will also be dynamically allocated (but it might be
 321  * unchanged) and has to be freed by the caller.
 322  */
 323 char *
 324 sdb_plugin_cname(char *hostname);
 325
 326 /*
 327  * sdb_plugin_log:
 328  * Log the specified message using all registered log callbacks. The message
 329  * will be logged with the specified priority.
 330  */
 331 int
 332 sdb_plugin_log(int prio, const char *msg);
 333
 334 /*
 335  * sdb_plugin_logf:
 336  * Log a formatted message. See sdb_plugin_log for more information.
 337  */
 338 int
 339 sdb_plugin_vlogf(int prio, const char *fmt, va_list ap);
 340 int
 341 sdb_plugin_logf(int prio, const char *fmt, ...);
 342
 343 #ifdef __cplusplus
 344 } /* extern "C" */
 345 #endif
 346
 347 #endif /* ! SDB_CORE_PLUGIN_H */
 348
 349 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 350