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