bump version number for next development cycle
[liblognorm.git] / src / liblognorm.h
1 /**
2  * @file liblognorm.h
3  * @brief The public liblognorm API.
4  *
5  * <b>Functions other than those defined here MUST not be called by
6  * a liblognorm "user" application.</b>
7  *
8  * This file is meant to be included by applications using liblognorm.
9  * For lognorm library files themselves, include "lognorm.h".
10  *//**
11  * @mainpage
12  * Liblognorm is an easy to use and fast samples-based log normalization 
13  * library.
14  * 
15  * It can be passed a stream of arbitrary log messages, one at a time, and for
16  * each message it will output well-defined name-value pairs and a set of
17  * tags describing the message.
18  *
19  * For further details, see it's initial announcement available at
20  *    http://blog.gerhards.net/2010/10/introducing-liblognorm.html
21  *
22  * The public interface of this library is describe in liblognorm.h.
23  *//*
24  *
25  * liblognorm - a fast samples-based log normalization library
26  * Copyright 2010 by Rainer Gerhards and Adiscon GmbH.
27  *
28  * This file is part of liblognorm.
29  *
30  * This library is free software; you can redistribute it and/or
31  * modify it under the terms of the GNU Lesser General Public
32  * License as published by the Free Software Foundation; either
33  * version 2.1 of the License, or (at your option) any later version.
34  *
35  * This library is distributed in the hope that it will be useful,
36  * but WITHOUT ANY WARRANTY; without even the implied warranty of
37  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
38  * Lesser General Public License for more details.
39  *
40  * You should have received a copy of the GNU Lesser General Public
41  * License along with this library; if not, write to the Free Software
42  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
43  *
44  * A copy of the LGPL v2.1 can be found in the file "COPYING" in this distribution.
45  */
46 #ifndef LIBLOGNORM_H_INCLUDED
47 #define LIBLOGNORM_H_INCLUDED
48 #include <stdlib.h>     /* we need size_t */
49
50 /* event_t needs to come from libcee, or whatever it will be called. We
51  * provide a dummy to be able to compile the initial skeletons.
52  */
53 typedef void * event_t;
54
55 /**
56  * The library context descriptor.
57  * This is used to permit multiple independednt instances of the
58  * library to be called within a single program. This is most 
59  * useful for plugin-based architectures.
60  */
61 typedef struct ln_ctx_s* ln_ctx;
62
63 /* API */
64 /**
65  * Return library version string.
66  *
67  * Returns the version of the currently used library.
68  *
69  * @return Zero-Terminated library version string.
70  */
71 /* Note: this MUST NOT be inline to make sure the actual library
72  * has the right version, not just what was used to compile!
73  */
74 char *ln_version(void);
75
76 /**
77  * Initialize a library context.
78  *
79  * To prevent memory leaks, ln_exitCtx() must be called on a library
80  * context that is no longer needed.
81  *
82  * @return new library context or NULL if an error occured
83  */
84 ln_ctx ln_initCtx(void);
85
86 /**
87  * Discard a library context.
88  *
89  * Free's the ressources associated with the given library context. It
90  * MUST NOT be accessed after calling this function.
91  *
92  * @param ctx The context to be discarded.
93  *
94  * @return Returns zero on success, something else otherwise.
95  */
96 int ln_exitCtx(ln_ctx ctx);
97
98 /**
99  * Set a debug message handler (callback).
100  *
101  * Liblognorm can provide helpful information for debugging
102  * - it's internal processing
103  * - the way a log message is being normalized
104  *
105  * It does so by emiting "interesting" information about its processing
106  * at various stages. A caller can obtain this information by registering
107  * an entry point. When done so, liblognorm will call the entry point
108  * whenever it has something to emit. Note that debugging can be rather
109  * verbose.
110  *
111  * The callback will be called with the following three parameters in that order:
112  * - the caller-provided cookie
113  * - a zero-terminated string buffer
114  * - the length of the string buffer, without the trailing NUL byte
115  *
116  * @note
117  * The provided callback function <b>must not</b> call any liblognorm
118  * APIs except when specifically flagged as safe for calling by a debug
119  * callback handler.
120  *
121  * @param[in] ctx The library context to apply callback to.
122  * @param[in] cb The function to be called for debugging
123  * @param[in] cookie Opaque cookie to be passed down to debug handler. Can be
124  *                   used for some state tracking by the caller. This is defined as
125  *                   void* to support pointers. To play it safe, a pointer should be
126  *                   passed (but advantorous folks may also use an unsigned).
127  *
128  * @return Returns zero on success, something else otherwise.
129  */
130 int ln_setDebugCB(ln_ctx ctx, void (*cb)(void*, char*, size_t), void *cookie);
131
132
133 /**
134  * Load a (log) sample file.
135  *
136  * The file must contain log samples in syntactically correct format. Samples are added
137  * to set already loaded in the current context. If there is a sample with duplicate
138  * semantics, this sample will be ignored. Most importantly, this can \b not be used
139  * to change tag assignments for a given sample.
140  *
141  * @param[in] ctx The library context to apply callback to.
142  * @param[in] file Name of file to be loaded.
143  *
144  * @return Returns zero on success, something else otherwise.
145  */
146 int ln_loadSamples(ln_ctx ctx, char *file);
147
148 /**
149  * Normalize a message.
150  *
151  * This is the main library entry point. It is called with a message
152  * to normalize and will return a normalized in-memory representation
153  * of it.
154  *
155  * If an error occurs, the function returns -1. In that case, an 
156  * in-memory event representation has been generated if event is
157  * non-NULL. In that case, the event contains further error details in
158  * normalized form.
159  *
160  * @note
161  * This function works on byte-counted strings and as such is able to
162  * process NUL bytes if they occur inside the message. On the other hand,
163  * this means the the correct messages size, \b excluding the NUL byte,
164  * must be provided.
165  *
166  * @param[in] ctx The library context to use.
167  * @param[in] msg The message string (see note above).
168  * @param[in] lenmsg The length of the message in bytes.
169  * @param[out] event A new event record or NULL if an error occured. <b>Must be 
170  *                   destructed if no longer needed.</b>
171  *
172  * @return Returns zero on success, something else otherwise.
173  */
174 int ln_normalizeMsg(ln_ctx ctx, char *msg, size_t lenmsg, event_t *event);
175
176 #endif /* #ifndef LOGNORM_H_INCLUDED */