X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=src%2Finclude%2Fcore%2Fplugin.h;h=e6ea7573cf15a0514c939c754eed48ae16c10964;hp=8d54089ca3e1ac42b98b4a6a4861e855453f32f2;hb=56b97a180a53aecbfe9f7162b8ece3faae973cf9;hpb=bf3b8e60b2fdc493c4e04b05ce67abf69ca9a4ff diff --git a/src/include/core/plugin.h b/src/include/core/plugin.h index 8d54089..e6ea757 100644 --- a/src/include/core/plugin.h +++ b/src/include/core/plugin.h @@ -1,5 +1,5 @@ /* - * syscollector - src/include/core/plugin.h + * SysDB - src/include/core/plugin.h * Copyright (C) 2012 Sebastian 'tokkee' Harl * All rights reserved. * @@ -25,76 +25,103 @@ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -#ifndef SC_CORE_PLUGIN_H -#define SC_CORE_PLUGIN_H 1 +#ifndef SDB_CORE_PLUGIN_H +#define SDB_CORE_PLUGIN_H 1 -#include "syscollector.h" +#include "sysdb.h" #include "core/object.h" -#include "utils/time.h" +#include "core/time.h" #include "liboconfig/oconfig.h" +#include + #ifdef __cplusplus extern "C" { #endif typedef struct { - sc_time_t interval; -} sc_plugin_ctx_t; -#define SC_PLUGIN_CTX_INIT { 0 } + sdb_time_t interval; +} sdb_plugin_ctx_t; +#define SDB_PLUGIN_CTX_INIT { 0 } + +typedef struct { + char *plugin_name; + char *filename; + + /* public attributes */ + char *description; + char *copyright; + char *license; -struct sc_plugin_info; -typedef struct sc_plugin_info sc_plugin_info_t; + int version; + int plugin_version; +} sdb_plugin_info_t; +#define SDB_PLUGIN_INFO_INIT { \ + /* plugin_name */ NULL, /* filename */ NULL, /* desc */ NULL, \ + /* copyright */ NULL, /* license */ NULL, \ + /* version */ -1, /* plugin_version */ -1 } /* this should be used in the header of a plugin to avoid * missing prototype warnings/errors for the plugin init * function */ -#define SC_PLUGIN_MAGIC \ - int sc_module_init(sc_plugin_info_t *info); +#define SDB_PLUGIN_MAGIC \ + int sdb_module_init(sdb_plugin_info_t *info) typedef struct { _Bool do_loop; - sc_time_t default_interval; -} sc_plugin_loop_t; -#define SC_PLUGIN_LOOP_INIT { 1, 0 } + sdb_time_t default_interval; +} sdb_plugin_loop_t; +#define SDB_PLUGIN_LOOP_INIT { 1, 0 } /* - * sc_plugin_load: + * sdb_plugin_load: * Load (any type of) plugin by loading the shared object file and calling the - * sc_module_init function. + * sdb_module_init function. If specified, 'plugin_ctx' fine-tunes the + * behavior of the plugin. If specified, the plugin will be looked up in + * 'basedir', else it defaults to the package libdir. */ int -sc_plugin_load(const char *name); +sdb_plugin_load(const char *basedir, const char *name, + const sdb_plugin_ctx_t *plugin_ctx); /* - * sc_plugin_set_info: - * Fill in the fields of the sc_plugin_info_t object passed to the - * sc_module_init function. This information is used to identify the plugin + * sdb_plugin_set_info: + * Fill in the fields of the sdb_plugin_info_t object passed to the + * sdb_module_init function. This information is used to identify the plugin * and also to provide additional information to the user. */ enum { - SC_PLUGIN_INFO_NAME, /* plugin name: string */ - SC_PLUGIN_INFO_DESC, /* plugin description: string */ - SC_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */ - SC_PLUGIN_INFO_LICENSE, /* plugin license: string */ - SC_PLUGIN_INFO_VERSION, /* libsyscollector version: integer */ - SC_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */ + SDB_PLUGIN_INFO_DESC, /* plugin description: string */ + SDB_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */ + SDB_PLUGIN_INFO_LICENSE, /* plugin license: string */ + SDB_PLUGIN_INFO_VERSION, /* libsysdb version: integer */ + SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */ }; int -sc_plugin_set_info(sc_plugin_info_t *info, int type, ...); +sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...); /* - * plugin callback functions + * plugin callback functions: + * See the description of the respective register function for what arguments + * the callbacks expect. + * + * The specified name of callback functions is prepended with the plugin name + * before being registered with the core. */ -typedef int (*sc_plugin_config_cb)(oconfig_item_t *ci); -typedef int (*sc_plugin_init_cb)(sc_object_t *user_data); -typedef int (*sc_plugin_collector_cb)(sc_object_t *user_data); -typedef int (*sc_plugin_shutdown_cb)(sc_object_t *user_data); +typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci); +typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data); +typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data); +typedef char *(*sdb_plugin_cname_cb)(const char *name, + sdb_object_t *user_data); +typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data); +typedef int (*sdb_plugin_log_cb)(int prio, const char *msg, + sdb_object_t *user_data); /* - * sc_plugin_register_config: + * sdb_plugin_register_config: * Register a "config" function. This will be used to pass on the * configuration for a plugin. The plugin has to make sure that the function * can be called multiple times in order to process multiple blocks @@ -105,10 +132,10 @@ typedef int (*sc_plugin_shutdown_cb)(sc_object_t *user_data); * - a negative value else */ int -sc_plugin_register_config(const char *name, sc_plugin_config_cb callback); +sdb_plugin_register_config(sdb_plugin_config_cb callback); /* - * sc_plugin_register_init: + * sdb_plugin_register_init: * Register an "init" function. All "init" functions will be called after * finishing the config parsing and before starting any other work. The * functions will be called in the same order as they have been registered, @@ -129,11 +156,11 @@ sc_plugin_register_config(const char *name, sc_plugin_config_cb callback); * - a negative value else */ int -sc_plugin_register_init(const char *name, sc_plugin_init_cb callback, - sc_object_t *user_data); +sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback, + sdb_object_t *user_data); /* - * sc_plugin_register_collector: + * sdb_plugin_register_collector: * Register a "collector" function. This is where a backend is doing its main * work. This function will be called whenever an update of a backend has been * requested (either by regular interval or by user request). The backend @@ -153,11 +180,31 @@ sc_plugin_register_init(const char *name, sc_plugin_init_cb callback, * - a negative value else */ int -sc_plugin_register_collector(const char *name, sc_plugin_collector_cb callback, - const sc_time_t *interval, sc_object_t *user_data); +sdb_plugin_register_collector(const char *name, + sdb_plugin_collector_cb callback, + const sdb_time_t *interval, sdb_object_t *user_data); + +/* + * sdb_plugin_register_cname: + * Register a "cname" (canonicalize name) function. This type of function is + * called whenever a host is stored. It accepts the hostname and returns a + * canonicalized hostname which will then be used to actually store the host. + * If multiple such callbacks are registered, each one of them will be called + * in the order they have been registered, each one receiving the result of + * the previous callback. If the function returns NULL, the original hostname + * is not changed. Any other value has to be dynamically allocated. It will be + * freed later on by the core. + * + * Returns: + * - 0 on success + * - a negative value else + */ +int +sdb_plugin_register_cname(const char *name, sdb_plugin_cname_cb callback, + sdb_object_t *user_data); /* - * sc_plugin_register_shutdown: + * sdb_plugin_register_shutdown: * Register a "shutdown" function to be called after stopping all update * processes and before shutting down the daemon. * @@ -168,42 +215,94 @@ sc_plugin_register_collector(const char *name, sc_plugin_collector_cb callback, * use the object for other purposes, it should thus deref it. */ int -sc_plugin_register_shutdown(const char *name, sc_plugin_shutdown_cb callback, - sc_object_t *user_data); +sdb_plugin_register_shutdown(const char *name, + sdb_plugin_shutdown_cb callback, + sdb_object_t *user_data); /* - * sc_plugin_get_ctx, sc_plugin_set_ctx: + * sdb_plugin_register_log: + * Register a "log" function to be called whenever logging is to be done. + * + * Arguments: + * - user_data: If specified, this will be passed on to each call of the + * callback. The function will take ownership of the object, that is, + * increment the reference count by one. In case the caller does not longer + * use the object for other purposes, it should thus deref it. + */ +int +sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback, + sdb_object_t *user_data); + +/* + * sdb_plugin_get_ctx, sdb_plugin_set_ctx: * The plugin context defines a set of settings that are available whenever a * plugin has been called. It may be used to pass around various information * between the different component of the library without having each and * every plugin care about it. + * + * If non-NULL, sdb_plugin_set_ctx stores the previous context in the location + * pointed to by 'old'. + */ +sdb_plugin_ctx_t +sdb_plugin_get_ctx(void); +int +sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old); + +/* + * sdb_plugin_configure: + * Configure the plugin called 'name' using the config tree 'ci'. The plugin + * name is the same as the one used when loading the plugin. + * + * Returns: + * - 0 on success + * - a negative value else */ -sc_plugin_ctx_t -sc_plugin_get_ctx(void); -sc_plugin_ctx_t -sc_plugin_set_ctx(sc_plugin_ctx_t ctx); +int +sdb_plugin_configure(const char *name, oconfig_item_t *ci); /* - * sc_plugin_configure: - * Configure the plugin called 'name' (according to the registered config - * callback) using the config tree 'ci'. + * sdb_plugin_reconfigure_init, sdb_plugin_reconfigure_finish: + * Reconfigure all plugins. This happens in multiple steps: first, call + * sdb_plugin_reconfigure_init to deconfigure all plugins by calling their + * config callbacks with a NULL config tree and unregistering all callbacks. + * Then, sdb_plugin_configure and other functions may be used to provide the + * new configuration or load new plugins. For all plugins which were already + * loaded before, sdb_module_init will be called with a NULL argument when + * reloading them. + * Finally, sdb_plugin_reconfigure_finish will clean up leftover pieces, like + * unloading plugins which are no longer in use. * * Returns: * - 0 on success * - a negative value else */ int -sc_plugin_configure(const char *name, oconfig_item_t *ci); +sdb_plugin_reconfigure_init(void); +int +sdb_plugin_reconfigure_finish(void); /* - * sc_plugin_init_all: + * sdb_plugin_init_all: * Initialize all plugins using their registered "init" function. + * + * Returns: + * The number of failed initializations. */ int -sc_plugin_init_all(void); +sdb_plugin_init_all(void); /* - * sc_plugin_collector_loop: + * sdb_plugin_shutdown_all: + * Shutdown all plugins using their registered "shutdown" function. + * + * Returns: + * The number of failed shutdowns. + */ +int +sdb_plugin_shutdown_all(void); + +/* + * sdb_plugin_collector_loop: * Loop until loop->do_loop is false, calling the next collector function on * each iteration and once its next update interval is passed. * @@ -212,13 +311,40 @@ sc_plugin_init_all(void); * - a negative value else */ int -sc_plugin_collector_loop(sc_plugin_loop_t *loop); +sdb_plugin_collector_loop(sdb_plugin_loop_t *loop); + +/* + * sdb_plugin_cname: + * Returns the canonicalized hostname. The given hostname argument has to + * point to dynamically allocated memory and might be freed by the function. + * The return value will also be dynamically allocated (but it might be + * unchanged) and has to be freed by the caller. + */ +char * +sdb_plugin_cname(char *hostname); + +/* + * sdb_plugin_log: + * Log the specified message using all registered log callbacks. The message + * will be logged with the specified priority. + */ +int +sdb_plugin_log(int prio, const char *msg); + +/* + * sdb_plugin_logf: + * Log a formatted message. See sdb_plugin_log for more information. + */ +int +sdb_plugin_vlogf(int prio, const char *fmt, va_list ap); +int +sdb_plugin_logf(int prio, const char *fmt, ...); #ifdef __cplusplus } /* extern "C" */ #endif -#endif /* ! SC_CORE_PLUGIN_H */ +#endif /* ! SDB_CORE_PLUGIN_H */ /* vim: set tw=78 sw=4 ts=4 noexpandtab : */