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.
67 */
68 int
69 sdb_plugin_load(const char *name);
71 /*
72 * sdb_plugin_set_info:
73 * Fill in the fields of the sdb_plugin_info_t object passed to the
74 * sdb_module_init function. This information is used to identify the plugin
75 * and also to provide additional information to the user.
76 */
77 enum {
78 SDB_PLUGIN_INFO_NAME, /* plugin name: string */
79 SDB_PLUGIN_INFO_DESC, /* plugin description: string */
80 SDB_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */
81 SDB_PLUGIN_INFO_LICENSE, /* plugin license: string */
82 SDB_PLUGIN_INFO_VERSION, /* libsysdb version: integer */
83 SDB_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
84 };
86 int
87 sdb_plugin_set_info(sdb_plugin_info_t *info, int type, ...);
89 /*
90 * plugin callback functions
91 */
93 typedef int (*sdb_plugin_config_cb)(oconfig_item_t *ci);
94 typedef int (*sdb_plugin_init_cb)(sdb_object_t *user_data);
95 typedef int (*sdb_plugin_collector_cb)(sdb_object_t *user_data);
96 typedef int (*sdb_plugin_shutdown_cb)(sdb_object_t *user_data);
97 typedef int (*sdb_plugin_log_cb)(int prio, const char *msg,
98 sdb_object_t *user_data);
100 /*
101 * sdb_plugin_register_config:
102 * Register a "config" function. This will be used to pass on the
103 * configuration for a plugin. The plugin has to make sure that the function
104 * can be called multiple times in order to process multiple <Plugin> blocks
105 * specified in the configuration file(s).
106 *
107 * Returns:
108 * - 0 on success
109 * - a negative value else
110 */
111 int
112 sdb_plugin_register_config(const char *name, sdb_plugin_config_cb callback);
114 /*
115 * sdb_plugin_register_init:
116 * Register an "init" function. All "init" functions will be called after
117 * finishing the config parsing and before starting any other work. The
118 * functions will be called in the same order as they have been registered,
119 * that is, functions of different plugins will be called in the same order as
120 * the appropriate "Load" statements in the config file.
121 *
122 * If the "init" function returns a non-zero value, *all* callbacks of the
123 * plugin will be unloaded.
124 *
125 * Arguments:
126 * - user_data: If specified, this will be passed on to each call of the
127 * callback. The function will take ownership of the object, that is,
128 * increment the reference count by one. In case the caller does not longer
129 * use the object for other purposes, it should thus deref it.
130 *
131 * Returns:
132 * - 0 on success
133 * - a negative value else
134 */
135 int
136 sdb_plugin_register_init(const char *name, sdb_plugin_init_cb callback,
137 sdb_object_t *user_data);
139 /*
140 * sdb_plugin_register_collector:
141 * Register a "collector" function. This is where a backend is doing its main
142 * work. This function will be called whenever an update of a backend has been
143 * requested (either by regular interval or by user request). The backend
144 * should then query the appropriate data-source and submit all values to the
145 * core.
146 *
147 * Arguments:
148 * - interval: Specifies the regular interval at which to update the backend.
149 * If this is NULL, global settings will be used.
150 * - user_data: If specified, this will be passed on to each call of the
151 * callback. The function will take ownership of the object, that is,
152 * increment the reference count by one. In case the caller does not longer
153 * use the object for other purposes, it should thus deref it.
154 *
155 * Returns:
156 * - 0 on success
157 * - a negative value else
158 */
159 int
160 sdb_plugin_register_collector(const char *name,
161 sdb_plugin_collector_cb callback,
162 const sdb_time_t *interval, sdb_object_t *user_data);
164 /*
165 * sdb_plugin_register_shutdown:
166 * Register a "shutdown" function to be called after stopping all update
167 * processes and before shutting down the daemon.
168 *
169 * Arguments:
170 * - user_data: If specified, this will be passed on to each call of the
171 * callback. The function will take ownership of the object, that is,
172 * increment the reference count by one. In case the caller does not longer
173 * use the object for other purposes, it should thus deref it.
174 */
175 int
176 sdb_plugin_register_shutdown(const char *name,
177 sdb_plugin_shutdown_cb callback,
178 sdb_object_t *user_data);
180 /*
181 * sdb_plugin_register_log:
182 * Register a "log" function to be called whenever logging is to be done.
183 *
184 * Arguments:
185 * - user_data: If specified, this will be passed on to each call of the
186 * callback. The function will take ownership of the object, that is,
187 * increment the reference count by one. In case the caller does not longer
188 * use the object for other purposes, it should thus deref it.
189 */
190 int
191 sdb_plugin_register_log(const char *name, sdb_plugin_log_cb callback,
192 sdb_object_t *user_data);
194 /*
195 * sdb_plugin_get_ctx, sdb_plugin_set_ctx:
196 * The plugin context defines a set of settings that are available whenever a
197 * plugin has been called. It may be used to pass around various information
198 * between the different component of the library without having each and
199 * every plugin care about it.
200 */
201 sdb_plugin_ctx_t
202 sdb_plugin_get_ctx(void);
203 sdb_plugin_ctx_t
204 sdb_plugin_set_ctx(sdb_plugin_ctx_t ctx);
206 /*
207 * sdb_plugin_configure:
208 * Configure the plugin called 'name' (according to the registered config
209 * callback) using the config tree 'ci'.
210 *
211 * Returns:
212 * - 0 on success
213 * - a negative value else
214 */
215 int
216 sdb_plugin_configure(const char *name, oconfig_item_t *ci);
218 /*
219 * sdb_plugin_init_all:
220 * Initialize all plugins using their registered "init" function.
221 */
222 int
223 sdb_plugin_init_all(void);
225 /*
226 * sdb_plugin_collector_loop:
227 * Loop until loop->do_loop is false, calling the next collector function on
228 * each iteration and once its next update interval is passed.
229 *
230 * Returns:
231 * - 0 on success
232 * - a negative value else
233 */
234 int
235 sdb_plugin_collector_loop(sdb_plugin_loop_t *loop);
237 /*
238 * sdb_plugin_log:
239 * Log the specified message using all registered log callbacks. The message
240 * will be logged with the specified priority.
241 */
242 int
243 sdb_plugin_log(int prio, const char *msg);
245 /*
246 * sdb_plugin_logf:
247 * Log a formatted message. See sdb_plugin_log for more information.
248 */
249 int
250 sdb_plugin_vlogf(int prio, const char *fmt, va_list ap);
251 int
252 sdb_plugin_logf(int prio, const char *fmt, ...);
254 #ifdef __cplusplus
255 } /* extern "C" */
256 #endif
258 #endif /* ! SDB_CORE_PLUGIN_H */
260 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */