/
fltmod_plugin.h
256 lines (238 loc) · 8.45 KB
/
fltmod_plugin.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
/*
* Copyright (c) 2015 by Farsight Security, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef NMSG_FLTMOD_PLUGIN_H
#define NMSG_FLTMOD_PLUGIN_H
/*! \file nmsg/fltmod_plugin.h
* \brief Implementing message filter modules.
*
* This file defines the interface that developers of message filter modules
* must implement. For the interface for loading and calling filter modules,
* see nmsg/fltmod.h.
*
* Filter modules are dynamically loaded shared objects that must export a
* symbol called <tt>nmsg_fltmod_plugin_export</tt>. This is a structure of
* type #nmsg_fltmod_plugin and is the sole entry point into the module.
*
* The first field of the nmsg_fltmod_plugin structure is the version of the
* API/ABI between libnmsg and the filter module. Module developers should
* assign this field the value #NMSG_FLTMOD_VERSION, or they can add
* <tt>NMSG_FLTMOD_REQUIRED_INIT,</tt> to the initializer, which is a
* convenience macro that initializes required fields.
*
* A filter module needs to provide at least one function, the core message
* filtering function <tt>filter_message</tt>. This function must be
* thread-safe, since it may be called simultaneously from multiple threads.
*
* Optionally, up to four more functions may be provided: a global module
* initializer and finalizer (<tt>module_init</tt> and <tt>module_fini</tt>),
* and a per-thread initializer and finalizer (<tt>thread_init</tt> and
* <tt>thread_fini</tt>). These functions can be used to acquire and release
* resources, generate debug messages, etc. The module and thread initializers
* may provide opaque data pointers. These pointers will be provided as
* parameters to the message filtering function.
*
* The <tt>module_init</tt> function will only be called once, immediately
* after the plugin module has been loaded. It will be called before all other
* module functions. Therefore, it does not need to be thread-safe.
*
* The <tt>module_fini</tt> function will only be called once, immediately
* before the plugin module will be unloaded from the process. It will be
* called after all other module functions. Therefore, it does not need to be
* thread-safe, either.
*
* The <tt>thread_init</tt> and <tt>thread_fini</tt> functions may be called by
* a processing thread after the thread has started and before the thread
* exits. They need to be thread-safe, since they be called by independently
* executing threads. A thread may not call a module's <tt>filter_message</tt>
* function before it has called <tt>thread_init</tt>, and it may not call
* <tt>filter_message</tt> after it has called <tt>thread_fini</tt>.
*
* For an example of a simple message filtering module, see the "sample" filter
* module in the fltmod/ directory of the nmsg distribution. The "sample"
* filter performs either systematic count-based or uniform probabilistic
* sampling of the message stream.
*/
#include <nmsg.h>
/** Version number of the nmsg fltmod ABI. */
#define NMSG_FLTMOD_VERSION 1
/**
* Initialize the filter module.
*
* Data with module-defined meaning may be passed in via the 'param' and
* 'len_param' parameters. This can be used to, for example, configure
* module-specific filtering parameters.
*
* \param[in] param
* Module-defined data needed for the initialization of the module.
*
* \param[in] len_param
* Length of 'param'.
*
* \param[out] mod_data
* Module-defined, module-wide state, passed to other module functions
* that take a 'mod_data' parameter.
*
* \return #nmsg_res_success
* If the module was successfully initialized.
* \return
* Any other result to indicate a fatal error.
*/
typedef nmsg_res
(*nmsg_fltmod_module_init_fp)(const void *param,
const size_t len_param,
void **mod_data);
/**
* Destroy the filter module. Any module-wide resources acquired by the module
* must be released.
*
* \param[in] mod_data
* Module-defined, module-wide state.
*/
typedef void
(*nmsg_fltmod_module_fini_fp)(void *mod_data);
/**
* Initialize module-defined, thread-wide state.
*
* \param[in] mod_data
* Module-defined, module-wide state.
*
* \param[out] thr_data
* Module-defined, thread-wide state.
*
* \return #nmsg_res_success
* If the thread-wide state was successfully initialized.
* \return
* Any other result to indicate a fatal error.
*/
typedef nmsg_res
(*nmsg_fltmod_thread_init_fp)(void *mod_data, void **thr_data);
/**
* Destroy thread-wide state. Any thread-wide resources corresponding to the
* passed in 'thr_data' value that have been acquired by the module must be
* released.
*
* \param[in] mod_data
* Module-defined, module-wide state.
*
* \param[in] thr_data
* Module-defined, thread-wide state.
*
* \return #nmsg_res_success
* If the thread-wide state was successfully destroyed.
* \return
* Any other result to indicate a fatal error.
*/
typedef nmsg_res
(*nmsg_fltmod_thread_fini_fp)(void *mod_data, void *thr_data);
/**
* Filter a message object and return the filter verdict.
*
* The filter function may alter the message object, or it may replace the
* message object with an entirely new message. If the filter function replaces
* the message object, it is responsible for disposing of the old message, for
* instance by calling nmsg_message_destroy().
*
* \param[in,out] msg
* Pointer to the message object to be filtered. The message object may
* optionally be altered, or it may be replaced with an entirely new
* message object.
*
* \param[in] mod_data
* Module-defined, module-wide state.
*
* \param[in] thr_data
* Module-defined, thread-wide state.
*
* \param[out] vres
* The filter verdict. \see #nmsg_filter_message_verdict for the possible
* verdict results and meanings.
*
* \return #nmsg_res_success
* The filtering completed and returned a verdict in 'vres'.
* \return
* Any other result to indicate a fatal error.
*/
typedef nmsg_res
(*nmsg_fltmod_filter_message_fp)(nmsg_message_t *msg,
void *mod_data,
void *thr_data,
nmsg_filter_message_verdict *vres);
/** Convenience macro. */
#define NMSG_FLTMOD_REQUIRED_INIT \
.fltmod_version = NMSG_FLTMOD_VERSION
/**
* Structure exported by filter modules.
*/
struct nmsg_fltmod_plugin {
/**
* Module interface version.
* Must be set to #NMSG_FLTMOD_VERSION or the module will be rejected
* at load time.
*/
long fltmod_version;
/**
* Module-wide initialization function. Optional, may be NULL. If this
* function exists, it will be called once at module startup by
* nmsg_fltmod_init().
*/
nmsg_fltmod_module_init_fp module_init;
/**
* Module-wide finalization function. Optional, may be NULL. If this
* function exists, it will be called once at module shutdown by
* nmsg_fltmod_destroy(). This function should clean up any resources
* acquired by 'module_init'.
*/
nmsg_fltmod_module_fini_fp module_fini;
/**
* Per-thread initialization function. Optional, may be NULL. If this
* function exists, it will be called by each thread that wants to
* perform message filtering via nmsg_fltmod_thread_init().
*/
nmsg_fltmod_thread_init_fp thread_init;
/**
* Per-thread finalization function. Optional, may be NULL. If this
* function exists, it will be called by each thread that has called
* 'thread_init' before the thread exits by nmsg_fltmod_thread_fini().
* This function should clean up any resources acquired by
* 'thread_init'.
*/
nmsg_fltmod_thread_fini_fp thread_fini;
/**
* Message filter function. Required, must not be NULL. This function
* is called by nmsg_fltmod_filter_message().
*/
nmsg_fltmod_filter_message_fp filter_message;
/**
* \private Reserved fields.
*/
void *_reserved15;
void *_reserved14;
void *_reserved13;
void *_reserved12;
void *_reserved11;
void *_reserved10;
void *_reserved9;
void *_reserved8;
void *_reserved7;
void *_reserved6;
void *_reserved5;
void *_reserved4;
void *_reserved3;
void *_reserved2;
void *_reserved1;
void *_reserved0;
};
#endif /* NMSG_FLTMOD_PLUGIN_H */