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