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