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 */
28 #ifndef SDB_CORE_PLUGIN_H
29 #define SDB_CORE_PLUGIN_H 1
31 #include "sysdb.h"
32 #include "core/object.h"
33 #include "core/time.h"
34 #include "core/timeseries.h"
36 #include "liboconfig/oconfig.h"
38 #include <stdarg.h>
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
44 typedef struct {
45 sdb_time_t interval;
46 } sdb_plugin_ctx_t;
47 #define SDB_PLUGIN_CTX_INIT { 0 }
49 typedef struct {
50 char *plugin_name;
51 char *filename;
53 /* public attributes */
54 char *description;
55 char *copyright;
56 char *license;
58 int version;
59 int plugin_version;
60 } sdb_plugin_info_t;
61 #define SDB_PLUGIN_INFO_INIT { \
62 /* plugin_name */ NULL, /* filename */ NULL, /* desc */ NULL, \
63 /* copyright */ NULL, /* license */ NULL, \
64 /* version */ -1, /* plugin_version */ -1 }
66 /* this should be used in the header of a plugin to avoid
67 * missing prototype warnings/errors for the plugin init
68 * function */
69 #define SDB_PLUGIN_MAGIC \
70 int sdb_module_init(sdb_plugin_info_t *info)
72 typedef struct {
73 _Bool do_loop;
74 sdb_time_t default_interval;
75 } sdb_plugin_loop_t;
76 #define SDB_PLUGIN_LOOP_INIT { 1, 0 }
78 /*
79 * sdb_plugin_load:
80 * Load (any type of) plugin by loading the shared object file and calling the
81 * sdb_module_init function. If specified, 'plugin_ctx' fine-tunes the
82 * behavior of the plugin. If specified, the plugin will be looked up in
83 * 'basedir', else it defaults to the package libdir.
84 */
85 int
86 sdb_plugin_load(const char *basedir, const char *name,
87 const sdb_plugin_ctx_t *plugin_ctx);
89 /*
90 * sdb_plugin_set_info:
91 * Fill in the fields of the sdb_plugin_info_t object passed to the
92 * sdb_module_init function. This information is used to identify the plugin
93 * and also to provide additional information to the user.
94 */
95 enum {
96 SDB_PLUGIN_INFO_DESC, /* plugin description: string */
97 SDB_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */
98 SDB_PLUGIN_INFO_LICENSE, /* plugin license: string */
99 SDB_PLUGIN_INFO_VERSION, /* libsysdb version: integer */
100 SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
101 };
103 int
104 sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
106 /*
107 * plugin callback functions:
108 * See the description of the respective register function for what arguments
109 * the callbacks expect.
110 *
111 * The specified name of callback functions is prepended with the plugin name
112 * before being registered with the core.
113 */
115 typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci);
116 typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data);
117 typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data);
118 typedef char *(*sdb_plugin_cname_cb)(const char *name,
119 sdb_object_t *user_data);
120 typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data);
121 typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
122 sdb_object_t *user_data);
124 typedef sdb_timeseries_t *(*sdb_plugin_fetch_ts_cb)(const char *id,
125 sdb_timeseries_opts_t *opts, sdb_object_t *user_data);
127 /*
128 * sdb_plugin_register_config:
129 * Register a "config" function. This will be used to pass on the
130 * configuration for a plugin. The plugin has to make sure that the function
131 * can be called multiple times in order to process multiple <Plugin> blocks
132 * specified in the configuration file(s).
133 *
134 * Returns:
135 * - 0 on success
136 * - a negative value else
137 */
138 int
139 sdb_plugin_register_config(sdb_plugin_config_cb callback);
141 /*
142 * sdb_plugin_register_init:
143 * Register an "init" function. All "init" functions will be called after
144 * finishing the config parsing and before starting any other work. The
145 * functions will be called in the same order as they have been registered,
146 * that is, functions of different plugins will be called in the same order as
147 * the appropriate "Load" statements in the config file.
148 *
149 * If the "init" function returns a non-zero value, *all* callbacks of the
150 * plugin will be unloaded.
151 *
152 * Arguments:
153 * - user_data: If specified, this will be passed on to each call of the
154 * callback. The function will take ownership of the object, that is,
155 * increment the reference count by one. In case the caller does not longer
156 * use the object for other purposes, it should thus deref it.
157 *
158 * Returns:
159 * - 0 on success
160 * - a negative value else
161 */
162 int
163 sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback,
164 sdb_object_t *user_data);
166 /*
167 * sdb_plugin_register_collector:
168 * Register a "collector" function. This is where a backend is doing its main
169 * work. This function will be called whenever an update of a backend has been
170 * requested (either by regular interval or by user request). The backend
171 * should then query the appropriate data-source and submit all values to the
172 * core.
173 *
174 * Arguments:
175 * - interval: Specifies the regular interval at which to update the backend.
176 * If this is NULL, global settings will be used.
177 * - user_data: If specified, this will be passed on to each call of the
178 * callback. The function will take ownership of the object, that is,
179 * increment the reference count by one. In case the caller does not longer
180 * use the object for other purposes, it should thus deref it.
181 *
182 * Returns:
183 * - 0 on success
184 * - a negative value else
185 */
186 int
187 sdb_plugin_register_collector(const char *name,
188 sdb_plugin_collector_cb callback,
189 const sdb_time_t *interval, sdb_object_t *user_data);
191 /*
192 * sdb_plugin_register_cname:
193 * Register a "cname" (canonicalize name) function. This type of function is
194 * called whenever a host is stored. It accepts the hostname and returns a
195 * canonicalized hostname which will then be used to actually store the host.
196 * If multiple such callbacks are registered, each one of them will be called
197 * in the order they have been registered, each one receiving the result of
198 * the previous callback. If the function returns NULL, the original hostname
199 * is not changed. Any other value has to be dynamically allocated. It will be
200 * freed later on by the core.
201 *
202 * Returns:
203 * - 0 on success
204 * - a negative value else
205 */
206 int
207 sdb_plugin_register_cname(const char *name, sdb_plugin_cname_cb callback,
208 sdb_object_t *user_data);
210 /*
211 * sdb_plugin_register_shutdown:
212 * Register a "shutdown" function to be called after stopping all update
213 * processes and before shutting down the daemon.
214 *
215 * Arguments:
216 * - user_data: If specified, this will be passed on to each call of the
217 * callback. The function will take ownership of the object, that is,
218 * increment the reference count by one. In case the caller does not longer
219 * use the object for other purposes, it should thus deref it.
220 */
221 int
222 sdb_plugin_register_shutdown(const char *name,
223 sdb_plugin_shutdown_cb callback,
224 sdb_object_t *user_data);
226 /*
227 * sdb_plugin_register_log:
228 * Register a "log" function to be called whenever logging is to be done.
229 *
230 * Arguments:
231 * - user_data: If specified, this will be passed on to each call of the
232 * callback. The function will take ownership of the object, that is,
233 * increment the reference count by one. In case the caller does not longer
234 * use the object for other purposes, it should thus deref it.
235 */
236 int
237 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
238 sdb_object_t *user_data);
240 /*
241 * sdb_plugin_register_ts_fetcher:
242 * Register a "time-series fetcher" function to be called whenever retrieving
243 * a time-series from a data-store. The callback will receive an identifier
244 * describing where to retrieve the data from (e.g. a filename or some kind of
245 * URL) and options which further describe the query.
246 *
247 * The name is used literally (without prepending the plugin name) to look up
248 * the appropriate fetcher callback.
249 *
250 * Arguments:
251 * - user_data: If specified, this will be passed on to each call of the
252 * callback. The function will take ownership of the object, that is,
253 * increment the reference count by one. In case the caller does not longer
254 * use the object for other purposes, it should thus deref it.
255 */
256 int
257 sdb_plugin_register_ts_fetcher(const char *name,
258 sdb_plugin_fetch_ts_cb callback, sdb_object_t *user_data);
260 /*
261 * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
262 * The plugin context defines a set of settings that are available whenever a
263 * plugin has been called. It may be used to pass around various information
264 * between the different component of the library without having each and
265 * every plugin care about it.
266 *
267 * If non-NULL, sdb_plugin_set_ctx stores the previous context in the location
268 * pointed to by 'old'.
269 */
270 sdb_plugin_ctx_t
271 sdb_plugin_get_ctx(void);
272 int
273 sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx, sdb_plugin_ctx_t *old);
275 /*
276 * sdb_plugin_current:
277 * Retrieve information about the plugin (if any) from which the current call
278 * into the core originated. The return value may not be modified.
279 *
280 * Returns:
281 * - information about the current plugin if we were called from some
282 * plugin's callback function
283 * - NULL else
284 */
285 const sdb_plugin_info_t *
286 sdb_plugin_current(void);
288 /*
289 * sdb_plugin_configure:
290 * Configure the plugin called 'name' using the config tree 'ci'. The plugin
291 * name is the same as the one used when loading the plugin.
292 *
293 * Returns:
294 * - 0 on success
295 * - a negative value else
296 */
297 int
298 sdb_plugin_configure(const char *name, oconfig_item_t *ci);
300 /*
301 * sdb_plugin_reconfigure_init, sdb_plugin_reconfigure_finish:
302 * Reconfigure all plugins. This happens in multiple steps: first, call
303 * sdb_plugin_reconfigure_init to deconfigure all plugins by calling their
304 * config callbacks with a NULL config tree and unregistering all callbacks.
305 * Then, sdb_plugin_configure and other functions may be used to provide the
306 * new configuration or load new plugins. For all plugins which were already
307 * loaded before, sdb_module_init will be called with a NULL argument when
308 * reloading them.
309 * Finally, sdb_plugin_reconfigure_finish will clean up leftover pieces, like
310 * unloading plugins which are no longer in use.
311 *
312 * Returns:
313 * - 0 on success
314 * - a negative value else
315 */
316 int
317 sdb_plugin_reconfigure_init(void);
318 int
319 sdb_plugin_reconfigure_finish(void);
321 /*
322 * sdb_plugin_init_all:
323 * Initialize all plugins using their registered "init" function.
324 *
325 * Returns:
326 * The number of failed initializations.
327 */
328 int
329 sdb_plugin_init_all(void);
331 /*
332 * sdb_plugin_shutdown_all:
333 * Shutdown all plugins using their registered "shutdown" function.
334 *
335 * Returns:
336 * The number of failed shutdowns.
337 */
338 int
339 sdb_plugin_shutdown_all(void);
341 /*
342 * sdb_plugin_collector_loop:
343 * Loop until loop->do_loop is false, calling the next collector function on
344 * each iteration and once its next update interval is passed.
345 *
346 * Returns:
347 * - 0 on success
348 * - a negative value else
349 */
350 int
351 sdb_plugin_collector_loop(sdb_plugin_loop_t *loop);
353 /*
354 * sdb_plugin_cname:
355 * Returns the canonicalized hostname. The given hostname argument has to
356 * point to dynamically allocated memory and might be freed by the function.
357 * The return value will also be dynamically allocated (but it might be
358 * unchanged) and has to be freed by the caller.
359 */
360 char *
361 sdb_plugin_cname(char *hostname);
363 /*
364 * sdb_plugin_log:
365 * Log the specified message using all registered log callbacks. The message
366 * will be logged with the specified priority.
367 */
368 int
369 sdb_plugin_log(int prio, const char *msg);
371 /*
372 * sdb_plugin_logf:
373 * Log a formatted message. See sdb_plugin_log for more information.
374 */
375 int
376 sdb_plugin_vlogf(int prio, const char *fmt, va_list ap);
377 int
378 sdb_plugin_logf(int prio, const char *fmt, ...);
380 #ifdef __cplusplus
381 } /* extern "C" */
382 #endif
384 #endif /* ! SDB_CORE_PLUGIN_H */
386 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */