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 struct sdb_plugin_info;
  49 typedef struct sdb_plugin_info sdb_plugin_info_t;
  50
  51 /* this should be used in the header of a plugin to avoid
  52  * missing prototype warnings/errors for the plugin init
  53  * function */
  54 #define SDB_PLUGIN_MAGIC \
  55         int sdb_module_init(sdb_plugin_info_t *info);
  56
  57 typedef struct {
  58         _Bool do_loop;
  59         sdb_time_t default_interval;
  60 } sdb_plugin_loop_t;
  61 #define SDB_PLUGIN_LOOP_INIT { 1, 0 }
  62
  63 /*
  64  * sdb_plugin_load:
  65  * Load (any type of) plugin by loading the shared object file and calling the
  66  * sdb_module_init function.
  67  */
  68 int
  69 sdb_plugin_load(const char *name);
  70
  71 /*
  72  * sdb_plugin_set_info:
  73  * Fill in the fields of the sdb_plugin_info_t object passed to the
  74  * sdb_module_init function. This information is used to identify the plugin
  75  * and also to provide additional information to the user.
  76  */
  77 enum {
  78         SDB_PLUGIN_INFO_NAME,          /* plugin name: string */
  79         SDB_PLUGIN_INFO_DESC,          /* plugin description: string */
  80         SDB_PLUGIN_INFO_COPYRIGHT,     /* plugin copyright: string */
  81         SDB_PLUGIN_INFO_LICENSE,       /* plugin license: string */
  82         SDB_PLUGIN_INFO_VERSION,       /* libsysdb version: integer */
  83         SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
  84 };
  85
  86 int
  87 sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
  88
  89 /*
  90  * plugin callback functions
  91  */
  92
  93 typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci);
  94 typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data);
  95 typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data);
  96 typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data);
  97 typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
  98                 sdb_object_t *user_data);
  99
 100 /*
 101  * sdb_plugin_register_config:
 102  * Register a "config" function. This will be used to pass on the
 103  * configuration for a plugin. The plugin has to make sure that the function
 104  * can be called multiple times in order to process multiple <Plugin> blocks
 105  * specified in the configuration file(s).
 106  *
 107  * Returns:
 108  *  - 0 on success
 109  *  - a negative value else
 110  */
 111 int
 112 sdb_plugin_register_config(const char *name, sdb_plugin_config_cb callback);
 113
 114 /*
 115  * sdb_plugin_register_init:
 116  * Register an "init" function. All "init" functions will be called after
 117  * finishing the config parsing and before starting any other work. The
 118  * functions will be called in the same order as they have been registered,
 119  * that is, functions of different plugins will be called in the same order as
 120  * the appropriate "Load" statements in the config file.
 121  *
 122  * If the "init" function returns a non-zero value, *all* callbacks of the
 123  * plugin will be unloaded.
 124  *
 125  * Arguments:
 126  *  - user_data: If specified, this will be passed on to each call of the
 127  *    callback. The function will take ownership of the object, that is,
 128  *    increment the reference count by one. In case the caller does not longer
 129  *    use the object for other purposes, it should thus deref it.
 130  *
 131  * Returns:
 132  *  - 0 on success
 133  *  - a negative value else
 134  */
 135 int
 136 sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback,
 137                 sdb_object_t *user_data);
 138
 139 /*
 140  * sdb_plugin_register_collector:
 141  * Register a "collector" function. This is where a backend is doing its main
 142  * work. This function will be called whenever an update of a backend has been
 143  * requested (either by regular interval or by user request). The backend
 144  * should then query the appropriate data-source and submit all values to the
 145  * core.
 146  *
 147  * Arguments:
 148  *  - interval: Specifies the regular interval at which to update the backend.
 149  *    If this is NULL, global settings will be used.
 150  *  - user_data: If specified, this will be passed on to each call of the
 151  *    callback. The function will take ownership of the object, that is,
 152  *    increment the reference count by one. In case the caller does not longer
 153  *    use the object for other purposes, it should thus deref it.
 154  *
 155  * Returns:
 156  *  - 0 on success
 157  *  - a negative value else
 158  */
 159 int
 160 sdb_plugin_register_collector(const char *name,
 161                 sdb_plugin_collector_cb callback,
 162                 const sdb_time_t *interval, sdb_object_t *user_data);
 163
 164 /*
 165  * sdb_plugin_register_shutdown:
 166  * Register a "shutdown" function to be called after stopping all update
 167  * processes and before shutting down the daemon.
 168  *
 169  * Arguments:
 170  *  - user_data: If specified, this will be passed on to each call of the
 171  *    callback. The function will take ownership of the object, that is,
 172  *    increment the reference count by one. In case the caller does not longer
 173  *    use the object for other purposes, it should thus deref it.
 174  */
 175 int
 176 sdb_plugin_register_shutdown(const char *name,
 177                 sdb_plugin_shutdown_cb callback,
 178                 sdb_object_t *user_data);
 179
 180 /*
 181  * sdb_plugin_register_log:
 182  * Register a "log" function to be called whenever logging is to be done.
 183  *
 184  * Arguments:
 185  *  - user_data: If specified, this will be passed on to each call of the
 186  *    callback. The function will take ownership of the object, that is,
 187  *    increment the reference count by one. In case the caller does not longer
 188  *    use the object for other purposes, it should thus deref it.
 189  */
 190 int
 191 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
 192                 sdb_object_t *user_data);
 193
 194 /*
 195  * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
 196  * The plugin context defines a set of settings that are available whenever a
 197  * plugin has been called. It may be used to pass around various information
 198  * between the different component of the library without having each and
 199  * every plugin care about it.
 200  */
 201 sdb_plugin_ctx_t
 202 sdb_plugin_get_ctx(void);
 203 sdb_plugin_ctx_t
 204 sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx);
 205
 206 /*
 207  * sdb_plugin_configure:
 208  * Configure the plugin called 'name' (according to the registered config
 209  * callback) using the config tree 'ci'.
 210  *
 211  * Returns:
 212  *  - 0 on success
 213  *  - a negative value else
 214  */
 215 int
 216 sdb_plugin_configure(const char *name, oconfig_item_t *ci);
 217
 218 /*
 219  * sdb_plugin_init_all:
 220  * Initialize all plugins using their registered "init" function.
 221  */
 222 int
 223 sdb_plugin_init_all(void);
 224
 225 /*
 226  * sdb_plugin_collector_loop:
 227  * Loop until loop->do_loop is false, calling the next collector function on
 228  * each iteration and once its next update interval is passed.
 229  *
 230  * Returns:
 231  *  - 0 on success
 232  *  - a negative value else
 233  */
 234 int
 235 sdb_plugin_collector_loop(sdb_plugin_loop_t *loop);
 236
 237 /*
 238  * sdb_plugin_log:
 239  * Log the specified message using all registered log callbacks. The message
 240  * will be logged with the specified priority.
 241  */
 242 int
 243 sdb_plugin_log(int prio, const char *msg);
 244
 245 /*
 246  * sdb_plugin_logf:
 247  * Log a formatted message. See sdb_plugin_log for more information.
 248  */
 249 int
 250 sdb_plugin_vlogf(int prio, const char *fmt, va_list ap);
 251 int
 252 sdb_plugin_logf(int prio, const char *fmt, ...);
 253
 254 #ifdef __cplusplus
 255 } /* extern "C" */
 256 #endif
 257
 258 #endif /* ! SDB_CORE_PLUGIN_H */
 259
 260 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */
 261