X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=src%2Finclude%2Fcore%2Fplugin.h;h=e6ea7573cf15a0514c939c754eed48ae16c10964;hp=ac8656ab3b36c8a76a10c1abac91feb96fe15d92;hb=56b97a180a53aecbfe9f7162b8ece3faae973cf9;hpb=8d86f8d17b71234e55633fbbdbcaee6f3d365d36 diff --git a/src/include/core/plugin.h b/src/include/core/plugin.h index ac8656a..e6ea757 100644 --- a/src/include/core/plugin.h +++ b/src/include/core/plugin.h @@ -34,6 +34,8 @@ #include "liboconfig/oconfig.h" +#include + #ifdef __cplusplus extern "C" { #endif @@ -43,14 +45,28 @@ typedef struct { } sdb_plugin_ctx_t; #define SDB_PLUGIN_CTX_INIT { 0 } -struct sdb_plugin_info; -typedef struct sdb_plugin_info sdb_plugin_info_t; +typedef struct { + char *plugin_name; + char *filename; + + /* public attributes */ + char *description; + char *copyright; + char *license; + + 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 SDB_PLUGIN_MAGIC \ - int sdb_module_init(sdb_plugin_info_t *info); + int sdb_module_init(sdb_plugin_info_t *info) typedef struct { _Bool do_loop; @@ -61,10 +77,13 @@ typedef struct { /* * sdb_plugin_load: * Load (any type of) plugin by loading the shared object file and calling the - * sdb_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 -sdb_plugin_load(const char *name); +sdb_plugin_load(const char *basedir, const char *name, + const sdb_plugin_ctx_t *plugin_ctx); /* * sdb_plugin_set_info: @@ -73,7 +92,6 @@ sdb_plugin_load(const char *name); * and also to provide additional information to the user. */ enum { - SDB_PLUGIN_INFO_NAME, /* plugin name: string */ SDB_PLUGIN_INFO_DESC, /* plugin description: string */ SDB_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */ SDB_PLUGIN_INFO_LICENSE, /* plugin license: string */ @@ -85,13 +103,22 @@ int 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 (*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); /* * sdb_plugin_register_config: @@ -105,7 +132,7 @@ typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data); * - a negative value else */ int -sdb_plugin_register_config(const char *name, sdb_plugin_config_cb callback); +sdb_plugin_register_config(sdb_plugin_config_cb callback); /* * sdb_plugin_register_init: @@ -157,6 +184,25 @@ 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); + /* * sdb_plugin_register_shutdown: * Register a "shutdown" function to be called after stopping all update @@ -173,22 +219,39 @@ sdb_plugin_register_shutdown(const char *name, sdb_plugin_shutdown_cb callback, sdb_object_t *user_data); +/* + * 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); -sdb_plugin_ctx_t -sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx); +int +sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old); /* * sdb_plugin_configure: - * Configure the plugin called 'name' (according to the registered config - * callback) using the config tree 'ci'. + * 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 @@ -197,13 +260,47 @@ sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx); int sdb_plugin_configure(const char *name, oconfig_item_t *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 +sdb_plugin_reconfigure_init(void); +int +sdb_plugin_reconfigure_finish(void); + /* * sdb_plugin_init_all: * Initialize all plugins using their registered "init" function. + * + * Returns: + * The number of failed initializations. */ int sdb_plugin_init_all(void); +/* + * 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 @@ -216,6 +313,33 @@ sdb_plugin_init_all(void); int 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