summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGuillaume Friloux <guillaume.friloux@gmail.com>2014-01-02 11:03:55 +0100
committerGuillaume Friloux <guillaume.friloux@gmail.com>2014-01-02 11:03:55 +0100
commit9f805a152e0d77646b962e83c3d17cc0113477c7 (patch)
treef678b38d98ddc8c53d3333dbd95eddad292344b1
parent91c142dd2efc4c66916c5ce849d2ddfa6f3b7073 (diff)
Improve documentation.
-rw-r--r--doc/smman.dox.in163
-rw-r--r--src/lib/spy/spy_line.c13
2 files changed, 162 insertions, 14 deletions
diff --git a/doc/smman.dox.in b/doc/smman.dox.in
index 9f74bce..2c80cd3 100644
--- a/doc/smman.dox.in
+++ b/doc/smman.dox.in
@@ -32,10 +32,10 @@
32 * 32 *
33 * Exemple of configuration file : <br /> 33 * Exemple of configuration file : <br />
34 * @code 34 * @code
35server = http://localhost:9200/logstash/logs/ 35 * server = http://localhost:9200/logstash/logs/
36host = BlackStar 36 * host = BlackStar
37type = syslog 37 * type = syslog
38@endcode 38 * @endcode
39 * 39 *
40 * <br /> 40 * <br />
41 * @section RULES Writing rules 41 * @section RULES Writing rules
@@ -70,6 +70,21 @@ type = syslog
70 * <br /> 70 * <br />
71 * Each configuration line will be stored in an hash table. 71 * Each configuration line will be stored in an hash table.
72 * 72 *
73 * @section Lib-Conf-Algorithm Algorithm
74 * Here is a simplified sequence chart to understand how it works.
75 * @msc
76 * MainLoop,Thread1;
77 * MainLoop=>MainLoop [ label = "conf_load()" ];
78 * MainLoop=>MainLoop [ label = "eio_file_map_all()" ];
79 * --- [ label = "Begin loop" ];
80 * MainLoop=>Thread1 [ label = "conf_load_map_filter()" ];
81 * Thread1=>Thread1 [ label = "conf_load_line_parse()" ];
82 * --- [ label = "End loop" ];
83 * Thread1=>MainLoop [ label = "conf_callback()" ];
84 * MainLoop=>MainLoop [ label = "app_callback()" ];
85 * @endmsc
86 * As you can see, loading of the file, and parsing of it is done
87 * in a separate thread to not block the main loop.
73 * 88 *
74 * @section Lib-Conf-Code Code documentation 89 * @section Lib-Conf-Code Code documentation
75 * @li @ref Lib-Conf-Functions 90 * @li @ref Lib-Conf-Functions
@@ -77,6 +92,9 @@ type = syslog
77 * @defgroup Lib-Conf-Functions API functions 92 * @defgroup Lib-Conf-Functions API functions
78 * 93 *
79 * @defgroup Lib-Conf-Example Basic Example 94 * @defgroup Lib-Conf-Example Basic Example
95 * @section Lib-Conf-Example-Sample-App Sample program
96 * Here is an example program using libconf to load and parse a given
97 * configuration file :
80 * @code 98 * @code
81 * #include <Conf.h> 99 * #include <Conf.h>
82 * 100 *
@@ -85,8 +103,8 @@ type = syslog
85 * Conf *conf) 103 * Conf *conf)
86 * { 104 * {
87 * Eina_Iterator *it; 105 * Eina_Iterator *it;
88 * printf("done!"); 106 * printf("done!\n");
89 * 107 *
90 * printf("Results :\n"); 108 * printf("Results :\n");
91 * it = eina_hash_iterator_tuple_new(conf_variables_get(conf)); 109 * it = eina_hash_iterator_tuple_new(conf_variables_get(conf));
92 * while (eina_iterator_next(it, &data)) 110 * while (eina_iterator_next(it, &data))
@@ -94,11 +112,12 @@ type = syslog
94 * Eina_Hash_Tuple *t = data; 112 * Eina_Hash_Tuple *t = data;
95 * const char *variable = t->key; 113 * const char *variable = t->key;
96 * const char *value = t->data; 114 * const char *value = t->data;
97 * printf("%s: %s\n", variable, value); 115 * printf("\t%s: %s\n", variable, value);
98 * } 116 * }
99 * eina_iterator_free(it); 117 * eina_iterator_free(it);
118 * ecore_main_loop_quit();
100 * } 119 * }
101 * 120 *
102 * void 121 * void
103 * _conf_error(void *data EINA_UNUSED, 122 * _conf_error(void *data EINA_UNUSED,
104 * Conf *conf EINA_UNUSED, 123 * Conf *conf EINA_UNUSED,
@@ -106,19 +125,42 @@ type = syslog
106 * { 125 * {
107 * printf("error : %s\n", errstr); 126 * printf("error : %s\n", errstr);
108 * } 127 * }
109 * 128 *
110 * int main(int argc EINA_UNUSED, char **argv EINA_UNUSED) 129 * int main(int argc, char **argv)
111 * { 130 * {
112 * conf_init(); 131 * conf_init();
113 * 132 *
114 * conf_load("./toto.conf", _conf_done, _conf_error, NULL); 133 * if (argc != 2)
115 * 134 * {
135 * fprintf(stderr, "You need to provide the conf file to load\n");
136 * return 1;
137 * }
138 *
139 * conf_load(argv[1], _conf_done, _conf_error, NULL);
140 *
116 * ecore_main_loop_begin(); 141 * ecore_main_loop_begin();
117 * 142 *
118 * conf_shutdown(); 143 * conf_shutdown();
119 * return 0; 144 * return 0;
120 * } 145 * }
121 * @endcode 146 * @endcode
147 * <br /><br />
148 * @section Lib-Conf-Example-Sample-Conf Sample configuration file
149 * You can try the configuration file below :
150 * @code
151 * # This rule will match any log message from /var/log/auth.log that
152 * # is about a connection using a valid public key for user root, and that
153 * # is not from normally authorized IPs.
154 * # These logs will be tagged with 'alert' word
155 * filename = /var/log/auth.log
156 * message = .*Accepted publickey for root.*
157 * message_unmatch = .*192\.168\.2\.84.*
158 * message_unmatch = .*192\.168\.2\.82.*
159 * message_unmatch = .*192\.168\.2\.94.*
160 *
161 *
162 * tags = alert
163 * @endcode
122 */ 164 */
123 165
124/** 166/**
@@ -132,9 +174,82 @@ type = syslog
132 * @b SPY_EVENT_LINE event to ecore that your application will need to 174 * @b SPY_EVENT_LINE event to ecore that your application will need to
133 * listen for. 175 * listen for.
134 * 176 *
177 * @section Lib-Spy-Algorithm Algorithm
178 * Here is a simplified sequence chart to understand how it works.
179 * @msc
180 * MainLoop,Thread1;
181 * MainLoop=>MainLoop [ label = "spy_file_new()" ];
182 * --- [ label = "Loop until file changes" ];
183 * MainLoop=>MainLoop [ label = "spy_file_poll()" ];
184 * --- [ label = "File changed" ];
185 * MainLoop=>Thread1 [ label = "_spy_file_cb()" ];
186 * Thread1=>Thread1 [ label = "_spy_file_line_extract()" ];
187 * Thread1=>MainLoop [ label = "_spy_file_event()" ];
188 * MainLoop=>MainLoop [ label = "ecore_event_add()" ];
189 * --- [ label = "Return to loop on spy_file_poll()" ];
190 * @endmsc
191 * For each call to spy_file_new(), an ecore timer is created to
192 * periodically call spy_file_poll(). <br />
193 * Once a changed is observed on the file, a thread is created to get
194 * lines added to the file, and create the ecore events.
195 *
135 * @section Lib-Spy-Code Code documentation 196 * @section Lib-Spy-Code Code documentation
136 * @li @ref Lib-Spy-Functions 197 * @li @ref Lib-Spy-Functions
198 * @li @ref Lib-Spy-Example
137 * @defgroup Lib-Spy-Functions API functions 199 * @defgroup Lib-Spy-Functions API functions
200 *
201 * @defgroup Lib-Spy-Example Basic Example
202 * @section Lib-Spy-Example-Sample-App Sample program
203 * Here is a sample program that uses lib spy to get new line events
204 * about the spied file :
205 * @code
206 * #include <Spy.h>
207 * #include <stdio.h>
208 *
209 * Eina_Bool
210 * _line_event(void *data,
211 * int type EINA_UNUSED,
212 * void *event)
213 * {
214 * Spy *spy = data;
215 * Spy_Line *sl = event;
216 *
217 * printf("spy[%p] sl[%p]\n", spy, sl);
218 * printf("line = %s\n", (char *)spy_line_get(sl));
219 * return EINA_TRUE;
220 * }
221 *
222 * int main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
223 * {
224 * Spy *spy;
225 * Ecore_Event_Handler *eeh;
226 *
227 * if (argc != 2)
228 * {
229 * fprintf(stderr, "You need to provide a file to spy\n");
230 * return 1;
231 * }
232 *
233 * spy_init();
234 *
235 * spy = spy_new();
236 * spy_file_new(spy, argv[1]);
237 *
238 * eeh = ecore_event_handler_add(SPY_EVENT_LINE, _line_event, spy);
239 *
240 * ecore_main_loop_begin();
241 * ecore_event_handler_del(eeh);
242 *
243 * spy_free(spy);
244 * spy_shutdown();
245 *
246 * return 0;
247 * }
248 * @endcode
249 * Ask it to spy a file on which you will constantly add new lines
250 * to see the events in the @a _line_event() function.<br />
251 * Libspy is also able to detect a truncate, to reset its internals
252 * and go back to begin of file.
138 */ 253 */
139 254
140/** 255/**
@@ -145,6 +260,26 @@ type = syslog
145 * These rules are basic configuration files, that we read using the 260 * These rules are basic configuration files, that we read using the
146 * @ref Lib-Conf.<br /> 261 * @ref Lib-Conf.<br />
147 * 262 *
263 * @section Lib-Rules-Algorithm Algorithm
264 * Here is a simplified sequence chart to understand how it works.
265 * @msc
266 * MainLoop,Thread1,Thread2;
267 * MainLoop=>MainLoop [ label = "rules_load()" ];
268 * MainLoop=>Thread1 [ label = "eio_file_direct_ls()" ];
269 * Thread1=>MainLoop [ label = "rules_load_ls()" ];
270 * --- [ label = "Loop for every rule found" ];
271 * MainLoop=>Thread2 [ label = "conf_load()" ];
272 * Thread2=>MainLoop [ label = "rules_load_rule()" ];
273 * MainLoop=>MainLoop [ label = "app_callback()" ];
274 * --- [ label = "End of loop" ];
275 * Thread1=>MainLoop [ label = "rules_load_ls_done()" ];
276 * MainLoop=>MainLoop [ label = "app_callback()" ];
277 * @endmsc
278 * For each call to spy_file_new(), an ecore timer is created to
279 * periodically call spy_file_poll(). <br />
280 * Once a changed is observed on the file, a thread is created to get
281 * lines added to the file, and create the ecore events.
282 *
148 * @section Lib-Rules-Code Code documentation 283 * @section Lib-Rules-Code Code documentation
149 * @li @ref Lib-Rules-Functions 284 * @li @ref Lib-Rules-Functions
150 * @defgroup Lib-Rules-Functions API functions 285 * @defgroup Lib-Rules-Functions API functions
diff --git a/src/lib/spy/spy_line.c b/src/lib/spy/spy_line.c
index b9c076b..6f1b800 100644
--- a/src/lib/spy/spy_line.c
+++ b/src/lib/spy/spy_line.c
@@ -5,12 +5,25 @@
5 * @{ 5 * @{
6 */ 6 */
7 7
8/**
9 * @brief Returns the line parsed by spy.
10 * @param sl Spy_Line structure.
11 * @return Pointer to parsed line.
12 *
13 * The pointer returned is the internal pointer of the Spy_Line,
14 * so, do not free it!
15 */
8const char * 16const char *
9spy_line_get(Spy_Line *sl) 17spy_line_get(Spy_Line *sl)
10{ 18{
11 return sl->line; 19 return sl->line;
12} 20}
13 21
22/**
23 * @brief Return the Spy_File of a Spy_Line.
24 * @param sl Spy_Line structure.
25 * @return Pointer to the Spy_File structure.
26 */
14Spy_File * 27Spy_File *
15spy_line_spyfile_get(Spy_Line *sl) 28spy_line_spyfile_get(Spy_Line *sl)
16{ 29{