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