Skip to content

Commit a8fa3de

Browse files
AdamZvarasedmicha
AdamZvara
authored and
sedmicha
committed
Modifier: initial version
1 parent 6380631 commit a8fa3de

File tree

6 files changed

+1443
-0
lines changed

6 files changed

+1443
-0
lines changed

‎include/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ set(SUB_HEADERS
1414
ipfixcol2/message_garbage.h
1515
ipfixcol2/message_ipfix.h
1616
ipfixcol2/message_session.h
17+
ipfixcol2/modifier.h
1718
ipfixcol2/plugins.h
1819
ipfixcol2/session.h
1920
ipfixcol2/utils.h

‎include/ipfixcol2.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
#include <ipfixcol2/message_session.h>
6262
#include <ipfixcol2/message_ipfix.h>
6363

64+
#include <ipfixcol2/modifier.h>
6465
#include <ipfixcol2/plugins.h>
6566
#include <ipfixcol2/session.h>
6667
#include <ipfixcol2/utils.h>

‎include/ipfixcol2/modifier.h‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
/**
2+
* \file modifier.h
3+
* \author Adam Zvara <[email protected]>
4+
* \brief Modifier component (header file)
5+
* \date 2023
6+
*/
7+
8+
#ifndef IPX_MODIFIER_H
9+
#define IPX_MODIFIER_H
10+
11+
#include <ipfixcol2/api.h>
12+
13+
/** Internal declaration of modifier */
14+
typedef struct ipx_modifier ipx_modifier_t;
15+
16+
/**
17+
* \brief IPFIX field specifier declaration for modifier
18+
* \see #fds_ipfix_tmplt_ie_u
19+
*/
20+
struct ipx_modifier_field {
21+
/** Information element ID */
22+
uint16_t id;
23+
/** Length of field */
24+
uint16_t length;
25+
/** Enterprise Number */
26+
uint32_t en;
27+
};
28+
29+
/**
30+
* \brief Output values from callback function
31+
* \warning Maximum size of stored data can be 65535 bytes (UINT16_MAX)
32+
*/
33+
struct ipx_modifier_output {
34+
/** Raw output data */
35+
uint8_t raw[UINT16_MAX];
36+
37+
/** Length of returned data
38+
* If value is not available, length contains negative
39+
* number and represents error code */
40+
int length;
41+
};
42+
43+
/**
44+
* \brief Callback signature for adding new elements data record
45+
* \note output size is equal to number of new fields
46+
* \note Any non-negative value in output[i].length means that
47+
* data in output at given position is valid and will be appended to IPFIX message
48+
* \return #IPX_OK if function was successfull, otherwise any non-zero value
49+
*/
50+
typedef int (*modifier_adder_cb_t)(const struct fds_drec *rec,
51+
struct ipx_modifier_output output[], void *cb_data);
52+
53+
/**
54+
* \brief Callback signature for filtering elements from data record
55+
* \note filter size is equal to field count in record's template
56+
* \note Any non-zero value in filter indicates that given field
57+
* is be filtered from original record (and template)
58+
*/
59+
typedef void (*modifier_filter_cb_t)(const struct fds_drec *rec,
60+
uint8_t *filter, void *cb_data);
61+
62+
/**
63+
* \brief Initialize modifier
64+
*
65+
* \note If \p vlevel is NULL, default collector verbosity is used.
66+
*
67+
* \param[in] fields Array of new fields which will be added to original message
68+
* \param[in] fields_size Number of items in fields array
69+
* \param[in] cb_data Data which can be used in callback function (cb_adder or cb_filter)
70+
* \param[in] iemgr IE element manager
71+
* \param[in] vlevel Verbosity level (can be NULL)
72+
* \param[in] ident Identification string (of parent context)
73+
* \return Pointer to created modifier or NULL (memory allocation error)
74+
*/
75+
IPX_API ipx_modifier_t *
76+
ipx_modifier_create(const struct ipx_modifier_field *fields, size_t fields_size,
77+
void *cb_data, const fds_iemgr_t *iemgr, const enum ipx_verb_level *vlevel, const char *ident);
78+
79+
/**
80+
* \brief Destroy modifier and free its memory
81+
*
82+
* \param[in] modifier Pointer to initialized modifier
83+
* \return Garbage message or NULL, if no garbage was found
84+
*/
85+
IPX_API void
86+
ipx_modifier_destroy(ipx_modifier_t *mod);
87+
88+
/**
89+
* \brief Change verbosity level
90+
*
91+
* If \p v_new is non-NULL, the new level is set from \p v_new.
92+
* If \p v_old is non-NULL, the previous level is saved in \p v_old.
93+
*
94+
* \param[in] mod Modifier component
95+
* \param[in] v_new New verbosity level (can be NULL)
96+
* \param[in] v_old Old verbosity level (can be NULL)
97+
*/
98+
IPX_API void
99+
ipx_modifier_verb(ipx_modifier_t *mod, enum ipx_verb_level *v_new, enum ipx_verb_level *v_old);
100+
101+
/**
102+
* \brief Set modifier's adder callback
103+
*
104+
* Adder callback is function used for setting values of fields, which will
105+
* be added to original record passed to modifier.
106+
*
107+
* \param[in] modifier Initialized modifier
108+
* \param[in] adder Callback for adding new elements
109+
*/
110+
IPX_API void
111+
ipx_modifier_set_adder_cb(ipx_modifier_t *mod, const modifier_adder_cb_t adder);
112+
113+
/**
114+
* \brief Set modifier's filter callback
115+
*
116+
* Filter callback is function used for setting filter array indicating
117+
* which fields and records will be deleted from record.
118+
*
119+
* \param[in] modifier Initialized modifier
120+
* \param[in] filter Callback for adding new elements
121+
*/
122+
IPX_API void
123+
ipx_modifier_set_filter_cb(ipx_modifier_t *mod, const modifier_filter_cb_t filter);
124+
125+
/**
126+
* \brief Return modifier's active template manager
127+
*
128+
* \param[in] mod Modifier
129+
* \return Pointer to template manager (or NULL if not modifier is NULL or manager is not set)
130+
*/
131+
IPX_API const fds_tmgr_t *
132+
ipx_modifier_get_manager(ipx_modifier_t *mod);
133+
134+
/**
135+
* \brief Return modifier's information element manager
136+
*
137+
* \param[in] mod Modifier
138+
* \return Pointer to element manager (or NULL if modifier is NULL)
139+
*/
140+
IPX_API const fds_iemgr_t *
141+
ipx_modifier_get_iemgr(ipx_modifier_t *mod);
142+
143+
/**
144+
* \brief Set modifier's information element manager
145+
*
146+
* \param[in] mod Modifier
147+
* \param[in] iemgr Element manager (can be NULL)
148+
* \return #IPX_OK on success, otherwise #IPX_ERR_ARG when modifier is NULL
149+
*/
150+
IPX_API int
151+
ipx_modifier_set_iemgr(ipx_modifier_t *mod, struct fds_iemgr *iemgr);
152+
153+
/**
154+
* \brief Filter data from parsed IPFIX data record and modify records template
155+
*
156+
* Modified record data is replaced in place and new template is created. Original
157+
* template in record is replaced with new template.
158+
*
159+
* \warning This function removes snapshot from data record, which needs to be set again!
160+
*
161+
* \param[in,out] rec Original/parsed data record
162+
* \param[in] filter Filter array
163+
* \return #IPX_OK on success
164+
* \return #IPX_ERR_ARG if any argument is NULL
165+
* \return #IPX_ERR_NOMEM on memory allocation error
166+
*/
167+
IPX_API int
168+
ipx_modifier_filter(struct fds_drec *rec, uint8_t *filter);
169+
170+
/**
171+
* \brief Append data to parsed IPFIX data record and modify records template
172+
*
173+
* Modified record data is replaced in place and new template is created. Original
174+
* template in record is replaced with new template.
175+
*
176+
* \warning This function removes snapshot from data record, which needs to be set again!
177+
*
178+
* \param[in,out] rec Original/parsed data record
179+
* \param[in] fields Array of new template fields
180+
* \param[in] buffers Output buffers
181+
* \param[in] fields_cnt Number of items in fields (and buffers)
182+
* \return #IPX_OK on success
183+
* \return #IPX_ERR_ARG if any argument is NULL
184+
* \return #IPX_ERR_NOMEM on memory allocation error
185+
*/
186+
IPX_API int
187+
ipx_modifier_append(struct fds_drec *rec, const struct ipx_modifier_field *fields,
188+
const struct ipx_modifier_output *buffers, const size_t fields_cnt);
189+
190+
/**
191+
* \brief Add new session context to modifier
192+
*
193+
* Context of current modified message contains information about transport session
194+
* and ODID, which identifies exporter. For each combination of transport session and ODID
195+
* a unique template manager is used. This function updates list of template
196+
* managers in modifier, creating new ones for previously unseen transport sessions
197+
* and sets export time extracted from message.
198+
*
199+
* \warning This function MUST be used before attempting to modify IPFIX message
200+
*
201+
* \param[in] mod Modifier
202+
* \param[in] ipfix_msg IPFIX message before modification
203+
* \param[out] garbage Potential garbage created by this function (NULL if none)
204+
* \return #IPX_OK if successful
205+
* \return #IPX_ERR_ARG when invalid arguments are passed
206+
* \return #IPX_ERR_FORMAT when trying to set export time in history for TCP session
207+
* \return #IPX_ERR_NOMEM on memory allocation error
208+
* \return #IPX_ERR_DENIED on unexpected error
209+
*/
210+
IPX_API int
211+
ipx_modifier_add_session(struct ipx_modifier *mod, ipx_msg_ipfix_t *ipfix_msg, ipx_msg_garbage_t **garbage);
212+
213+
/**
214+
* \brief Remove transport session context from modifier
215+
*
216+
* \note Transport session is identified by session structure only, NOT ODID
217+
* which means, that removing session also removes every session + ODID pair
218+
* from modifier
219+
*
220+
* \warning If modifier's current session context (modifier->curr_ctx) is from
221+
* removed session, the pointer becomes NULL!
222+
*
223+
* \param[in] mod Modifier
224+
* \param[in] session Transport session to be removed
225+
* \param[out] garbage Garbage message containing removed session or NULL
226+
* \return #IPX_OK on success, #IPX_ERR_NOTFOUND if session was not found in modifier
227+
*/
228+
IPX_API int
229+
ipx_modifier_remove_session(struct ipx_modifier *mod, const struct ipx_session *session,
230+
ipx_msg_garbage_t **garbage);
231+
232+
/**
233+
* \brief Modify given records based on modifier configuration
234+
*
235+
* \warning Snapshot in modified record becomes invalid!
236+
* \warning Function ipx_modifier_set_time() must be called before attempting
237+
* to modify record for first time!
238+
* \note Adding callback or filter callback need to be added before calling
239+
* this function with ipx_modifier_set_adder_cb() or ipx_modifier_set_filter_cb()
240+
* \note Modified templates are stored in modifier template managers
241+
*
242+
* \param[in] modifier Modifier component
243+
* \param[in] record Parsed IPFIX data record
244+
* \param[out] garbage Potential garbage created by this function (NULL if none)
245+
*
246+
* \return Modified data record with added/filtered fields based on modifier configuration
247+
* \return NULL if any error occured
248+
*/
249+
IPX_API struct fds_drec *
250+
ipx_modifier_modify(ipx_modifier_t *mod, const struct fds_drec *record, ipx_msg_garbage_t **garbage);
251+
252+
#endif

‎src/core/CMakeLists.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@ set(CORE_SOURCE
4444
message_session.c
4545
message_terminate.c
4646
message_terminate.h
47+
modifier.c
48+
modifier.h
4749
odid_range.c
4850
odid_range.h
4951
parser.c

0 commit comments

Comments
 (0)