X-Git-Url: https://git.tokkee.org/?p=sysdb.git;a=blobdiff_plain;f=src%2Finclude%2Fcore%2Fplugin.h;h=6c4a2e16cfdf674c2884f560ac158ef7836733d3;hp=6a679ce8a17baa5900573ee38cf0deb3e22882cb;hb=9a96acd759c31211aa512e174339a9c178c4eb83;hpb=336bcee462f82f33c8f9d8612959208b047ea93a

diff --git a/src/include/core/plugin.h b/src/include/core/plugin.h
index 6a679ce..6c4a2e1 100644
--- a/src/include/core/plugin.h
+++ b/src/include/core/plugin.h
@@ -30,11 +30,14 @@
 
 #include "sysdb.h"
 #include "core/object.h"
+#include "core/store.h"
 #include "core/time.h"
+#include "core/timeseries.h"
 
 #include "liboconfig/oconfig.h"
 
 #include <stdarg.h>
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -45,17 +48,31 @@ 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;
+	bool do_loop;
 	sdb_time_t default_interval;
 } sdb_plugin_loop_t;
 #define SDB_PLUGIN_LOOP_INIT { 1, 0 }
@@ -64,10 +81,12 @@ typedef struct {
  * sdb_plugin_load:
  * Load (any type of) plugin by loading the shared object file and calling the
  * sdb_module_init function. If specified, 'plugin_ctx' fine-tunes the
- * behavior of the plugin.
+ * 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, const sdb_plugin_ctx_t *plugin_ctx);
+sdb_plugin_load(const char *basedir, const char *name,
+		const sdb_plugin_ctx_t *plugin_ctx);
 
 /*
  * sdb_plugin_set_info:
@@ -76,7 +95,6 @@ sdb_plugin_load(const char *name, const sdb_plugin_ctx_t *plugin_ctx);
  * 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 */
@@ -91,6 +109,9 @@ sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
  * 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);
@@ -102,6 +123,9 @@ 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);
 
+typedef sdb_timeseries_t *(*sdb_plugin_fetch_ts_cb)(const char *id,
+		sdb_timeseries_opts_t *opts, sdb_object_t *user_data);
+
 /*
  * sdb_plugin_register_config:
  * Register a "config" function. This will be used to pass on the
@@ -114,7 +138,7 @@ typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
  *  - 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:
@@ -215,6 +239,65 @@ int
 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
 		sdb_object_t *user_data);
 
+/*
+ * sdb_plugin_register_ts_fetcher:
+ * Register a "time-series fetcher" function to be called whenever retrieving
+ * a time-series from a data-store. The callback will receive an identifier
+ * describing where to retrieve the data from (e.g. a filename or some kind of
+ * URL) and options which further describe the query.
+ *
+ * The name is used literally (without prepending the plugin name) to look up
+ * the appropriate fetcher callback.
+ *
+ * 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_ts_fetcher(const char *name,
+		sdb_plugin_fetch_ts_cb callback, sdb_object_t *user_data);
+
+/*
+ * sdb_plugin_register_writer:
+ * Register a "writer" implementation to be used when adding an object to the
+ * store. It is invalid to register an incomplete writer which does not
+ * implement all of the writer interface.
+ *
+ * Arguments:
+ *  - user_data: If specified, this will be passed on to each call of the
+ *    callbacks. 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_writer(const char *name,
+		sdb_store_writer_t *writer, sdb_object_t *user_data);
+
+/*
+ * sdb_plugin_register_reader:
+ * Register a "reader" implementation for querying the store. It is invalid to
+ * register an incomplete reader which does not implement all of the reader
+ * interface.
+ *
+ * Arguments:
+ *  - user_data: If specified, this will be passed on to each call of the
+ *    callbacks. 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_reader(const char *name,
+		sdb_store_reader_t *reader, sdb_object_t *user_data);
+
+/*
+ * sdb_plugin_unregister_all:
+ * Unregister all registered plugins and destruct their user-data objects.
+ */
+void
+sdb_plugin_unregister_all(void);
+
 /*
  * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
  * The plugin context defines a set of settings that are available whenever a
@@ -223,17 +306,30 @@ sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
  * every plugin care about it.
  *
  * If non-NULL, sdb_plugin_set_ctx stores the previous context in the location
- * pointed to be 'old'.
+ * 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_current:
+ * Retrieve information about the plugin (if any) from which the current call
+ * into the core originated. The return value may not be modified.
+ *
+ * Returns:
+ *  - information about the current plugin if we were called from some
+ *    plugin's callback function
+ *  - NULL else
+ */
+const sdb_plugin_info_t *
+sdb_plugin_current(void);
+
 /*
  * 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
@@ -242,13 +338,47 @@ sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old);
 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
@@ -284,9 +414,69 @@ sdb_plugin_log(int prio, const char *msg);
  * Log a formatted message. See sdb_plugin_log for more information.
  */
 int
-sdb_plugin_vlogf(int prio, const char *fmt, va_list ap);
+sdb_plugin_vlogf(int prio, const char *fmt, va_list ap)
+		__attribute__((format(printf, 2, 0)));
+int
+sdb_plugin_logf(int prio, const char *fmt, ...)
+		__attribute__((format(printf, 2, 3)));
+
+/*
+ * sdb_plugin_fetch_timeseries:
+ * Fetch the time-series identified by 'id' from a backend data-store of the
+ * specified 'type'. The type has to match an existing time-series fetcher
+ * callback's name. The identifier is passed through to the callback which
+ * then needs to make sense of it. The time-series option specify which data
+ * to fetch.
+ *
+ * Returns:
+ *  - a time-series on success
+ *  - NULL else
+ */
+sdb_timeseries_t *
+sdb_plugin_fetch_timeseries(const char *type, const char *id,
+		sdb_timeseries_opts_t *opts);
+
+/*
+ * sdb_plugin_query:
+ * Query the store using the query specified by 'ast'. The result will be
+ * written to 'buf' and any errors will be written to 'errbuf'.
+ *
+ * Returns:
+ *  - 0 on success
+ *  - a negative value else
+ */
+int
+sdb_plugin_query(sdb_ast_node_t *ast,
+		sdb_store_writer_t *w, sdb_object_t *wd, sdb_strbuf_t *errbuf);
+
+/*
+ * sdb_plugin_store_host, sdb_plugin_store_service, sdb_plugin_store_metric,
+ * sdb_plugin_store_attribute, sdb_plugin_store_service_attribute,
+ * sdb_plugin_store_metric_attribute:
+ * Store an object in the database by sending it to all registered store
+ * writer plugins.
+ *
+ * Returns:
+ *  - 0 on success
+ *  - a negative value else
+ */
+int
+sdb_plugin_store_host(const char *name, sdb_time_t last_update);
+int
+sdb_plugin_store_service(const char *hostname, const char *name,
+		sdb_time_t last_update);
+int
+sdb_plugin_store_metric(const char *hostname, const char *name,
+		sdb_metric_store_t *store, sdb_time_t last_update);
+int
+sdb_plugin_store_attribute(const char *hostname, const char *key,
+		const sdb_data_t *value, sdb_time_t last_update);
+int
+sdb_plugin_store_service_attribute(const char *hostname, const char *service,
+		const char *key, const sdb_data_t *value, sdb_time_t last_update);
 int
-sdb_plugin_logf(int prio, const char *fmt, ...);
+sdb_plugin_store_metric_attribute(const char *hostname, const char *metric,
+		const char *key, const sdb_data_t *value, sdb_time_t last_update);
 
 #ifdef __cplusplus
 } /* extern "C" */