3
* @brief The CEE nvfield object.
4
* @class ee_field field.h
8
* Libee - An Event Expression Library inspired by CEE
9
* Copyright 2010 by Rainer Gerhards and Adiscon GmbH.
11
* This file is part of libee.
13
* This library is free software; you can redistribute it and/or
14
* modify it under the terms of the GNU Lesser General Public
15
* License as published by the Free Software Foundation; either
16
* version 2.1 of the License, or (at your option) any later version.
18
* This library is distributed in the hope that it will be useful,
19
* but WITHOUT ANY WARRANTY; without even the implied warranty of
20
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21
* Lesser General Public License for more details.
23
* You should have received a copy of the GNU Lesser General Public
24
* License along with this library; if not, write to the Free Software
25
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
27
* A copy of the LGPL v2.1 can be found in the file "COPYING" in this distribution.
29
#ifndef LIBEE_FIELD_H_INCLUDED
30
#define LIBEE_FIELD_H_INCLUDED
31
#include "libee/valnode.h"
36
* Note that in CEE terms, this is called a "nvfield".
38
* This represents a name-value pair, whereby the name should correspond
39
* to a valid field type. However, depending on compliance level, name
40
* may not point to a valid field. For this reason, we do not require
41
* a pointer to the proper field definition.
43
* Fields may contain a variable number of values. However, the by far
44
* most common case is exactly one value. To support this effciently, we
45
* store the first value directly within the structure and the 2nd+ in
49
unsigned objID; /**< magic number to identify the object */
50
ee_ctx ctx; /**< associated library context */
51
es_str_t *name; /**< the field name */
52
unsigned char nVals; /**< number of values */
53
struct ee_value *val; /**< value assigned to this field */
54
struct ee_valnode *valroot; /**< list for 2nd+ values */
55
struct ee_valnode *valtail; /**< tail of the value list (for fast insert) */
59
* Constructor for the ee_field object.
64
* @param[in] ctx library context
66
* @return pointer to new object or NULL if an error occured
68
struct ee_field* ee_newField(ee_ctx ctx);
72
* Constructor an ee_field object from a name value pair.
73
* TODO: is this legacy or do we need it in the future?
78
* @param[in] ctx library context
79
* @param[in] name field name
80
* @param[in] val value
82
* @return new field or NULL if an error occured
84
struct ee_field* ee_newFieldFromNV(ee_ctx ctx, char *name, struct ee_value *val);
87
* Destructor for the ee_field object.
92
* @param[in] field object to be destructed
94
* @param field The field to be discarded.
96
void ee_deleteField(struct ee_field *field);
101
* Set the field name. This MUST NOT be called if a field name has
102
* already been established. Note that if the library is in validating mode,
103
* it may check the field name against the dictionary.
108
* @param[in] ctx library context
109
* @param[in] str field name
111
* @return 0 on success, something else otherwise
113
int ee_nameField(struct ee_field *field, es_str_t *name);
117
* Add a value to a field.
118
* Add the provided value to the list of field values. The value will
119
* be added as the \b last member of the field list (so calling sequence
120
* is important!). In validating mode, the library will check value
121
* cardinality against the dictionary.
126
* @param[in] ctx library context
127
* @param[in] val value to add to field
129
* @return 0 on success, something else otherwise
131
int ee_addValueToField(struct ee_field *field, struct ee_value *val);
134
* Encode the current field with all its values in syslog format
135
* and append this representation to the provided string.
140
* @param[in] field field to enocde
141
* @param[out] str string to wich the encoded value is to be added.
142
* Must have been allocated by the caller.
143
* @returns 0 on success, something else otherwise
145
int ee_addField_Syslog(struct ee_field *value, es_str_t **str);
149
* Encode the current field with all its values in XML format
150
* and append this representation to the provided string.
155
* @param[in] field field to enocde
156
* @param[out] str string to wich the encoded value is to be added.
157
* Must have been allocated by the caller.
158
* @returns 0 on success, something else otherwise
160
int ee_addField_XML(struct ee_field *value, es_str_t **str);
164
* Get the number of values the field has.
169
* @param[in] field relevant field
170
* @returns number of values
172
int ee_getNumFieldVals(struct ee_field *field);
175
* Get a specific value from this field as a string.
180
* @param[in] field relevant field
181
* @param[in] n number of the field to return, zero-based (like C arrays)
183
* @returns string representation of the n-th field value or NULL in
186
es_str_t* ee_getFieldValueAsStr(struct ee_field *field, unsigned short n);
188
#endif /* #ifndef LIBEE_FIELD_H_INCLUDED */
added
removed
include/libee/field.h
