1 /*
2 * syscollector - 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 SC_CORE_PLUGIN_H
29 #define SC_CORE_PLUGIN_H 1
31 #include "syscollector.h"
32 #include "core/object.h"
33 #include "utils/time.h"
35 #include "liboconfig/oconfig.h"
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
41 typedef struct {
42 sc_time_t interval;
43 } sc_plugin_ctx_t;
44 #define SC_PLUGIN_CTX_INIT { 0 }
46 struct sc_plugin_info;
47 typedef struct sc_plugin_info sc_plugin_info_t;
49 /* this should be used in the header of a plugin to avoid
50 * missing prototype warnings/errors for the plugin init
51 * function */
52 #define SC_PLUGIN_MAGIC \
53 int sc_module_init(sc_plugin_info_t *info);
55 typedef struct {
56 _Bool do_loop;
57 sc_time_t default_interval;
58 } sc_plugin_loop_t;
59 #define SC_PLUGIN_LOOP_INIT { 1, 0 }
61 /*
62 * sc_plugin_load:
63 * Load (any type of) plugin by loading the shared object file and calling the
64 * sc_module_init function.
65 */
66 int
67 sc_plugin_load(const char *name);
69 /*
70 * sc_plugin_set_info:
71 * Fill in the fields of the sc_plugin_info_t object passed to the
72 * sc_module_init function. This information is used to identify the plugin
73 * and also to provide additional information to the user.
74 */
75 enum {
76 SC_PLUGIN_INFO_NAME, /* plugin name: string */
77 SC_PLUGIN_INFO_DESC, /* plugin description: string */
78 SC_PLUGIN_INFO_COPYRIGHT, /* plugin copyright: string */
79 SC_PLUGIN_INFO_LICENSE, /* plugin license: string */
80 SC_PLUGIN_INFO_VERSION, /* libsyscollector version: integer */
81 SC_PLUGIN_INFO_PLUGIN_VERSION /* plugin version: integer */
82 };
84 int
85 sc_plugin_set_info(sc_plugin_info_t *info, int type, ...);
87 /*
88 * plugin callback functions
89 */
91 typedef int (*sc_plugin_config_cb)(oconfig_item_t *ci);
92 typedef int (*sc_plugin_init_cb)(sc_object_t *user_data);
93 typedef int (*sc_plugin_collector_cb)(sc_object_t *user_data);
94 typedef int (*sc_plugin_shutdown_cb)(sc_object_t *user_data);
96 /*
97 * sc_plugin_register_config:
98 * Register a "config" function. This will be used to pass on the
99 * configuration for a plugin. The plugin has to make sure that the function
100 * can be called multiple times in order to process multiple <Plugin> blocks
101 * specified in the configuration file(s).
102 *
103 * Returns:
104 * - 0 on success
105 * - a negative value else
106 */
107 int
108 sc_plugin_register_config(const char *name, sc_plugin_config_cb callback);
110 /*
111 * sc_plugin_register_init:
112 * Register an "init" function. All "init" functions will be called after
113 * finishing the config parsing and before starting any other work. The
114 * functions will be called in the same order as they have been registered,
115 * that is, functions of different plugins will be called in the same order as
116 * the appropriate "Load" statements in the config file.
117 *
118 * If the "init" function returns a non-zero value, *all* callbacks of the
119 * plugin will be unloaded.
120 *
121 * Arguments:
122 * - user_data: If specified, this will be passed on to each call of the
123 * callback. The function will take ownership of the object, that is,
124 * increment the reference count by one. In case the caller does not longer
125 * use the object for other purposes, it should thus deref it.
126 *
127 * Returns:
128 * - 0 on success
129 * - a negative value else
130 */
131 int
132 sc_plugin_register_init(const char *name, sc_plugin_init_cb callback,
133 sc_object_t *user_data);
135 /*
136 * sc_plugin_register_collector:
137 * Register a "collector" function. This is where a backend is doing its main
138 * work. This function will be called whenever an update of a backend has been
139 * requested (either by regular interval or by user request). The backend
140 * should then query the appropriate data-source and submit all values to the
141 * core.
142 *
143 * Arguments:
144 * - interval: Specifies the regular interval at which to update the backend.
145 * If this is NULL, global settings will be used.
146 * - user_data: If specified, this will be passed on to each call of the
147 * callback. The function will take ownership of the object, that is,
148 * increment the reference count by one. In case the caller does not longer
149 * use the object for other purposes, it should thus deref it.
150 *
151 * Returns:
152 * - 0 on success
153 * - a negative value else
154 */
155 int
156 sc_plugin_register_collector(const char *name, sc_plugin_collector_cb callback,
157 const sc_time_t *interval, sc_object_t *user_data);
159 /*
160 * sc_plugin_register_shutdown:
161 * Register a "shutdown" function to be called after stopping all update
162 * processes and before shutting down the daemon.
163 *
164 * Arguments:
165 * - user_data: If specified, this will be passed on to each call of the
166 * callback. The function will take ownership of the object, that is,
167 * increment the reference count by one. In case the caller does not longer
168 * use the object for other purposes, it should thus deref it.
169 */
170 int
171 sc_plugin_register_shutdown(const char *name, sc_plugin_shutdown_cb callback,
172 sc_object_t *user_data);
174 /*
175 * sc_plugin_get_ctx, sc_plugin_set_ctx:
176 * The plugin context defines a set of settings that are available whenever a
177 * plugin has been called. It may be used to pass around various information
178 * between the different component of the library without having each and
179 * every plugin care about it.
180 */
181 sc_plugin_ctx_t
182 sc_plugin_get_ctx(void);
183 sc_plugin_ctx_t
184 sc_plugin_set_ctx(sc_plugin_ctx_t ctx);
186 /*
187 * sc_plugin_configure:
188 * Configure the plugin called 'name' (according to the registered config
189 * callback) using the config tree 'ci'.
190 *
191 * Returns:
192 * - 0 on success
193 * - a negative value else
194 */
195 int
196 sc_plugin_configure(const char *name, oconfig_item_t *ci);
198 /*
199 * sc_plugin_init_all:
200 * Initialize all plugins using their registered "init" function.
201 */
202 int
203 sc_plugin_init_all(void);
205 /*
206 * sc_plugin_collector_loop:
207 * Loop until loop->do_loop is false, calling the next collector function on
208 * each iteration and once its next update interval is passed.
209 *
210 * Returns:
211 * - 0 on success
212 * - a negative value else
213 */
214 int
215 sc_plugin_collector_loop(sc_plugin_loop_t *loop);
217 #ifdef __cplusplus
218 } /* extern "C" */
219 #endif
221 #endif /* ! SC_CORE_PLUGIN_H */
223 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */