summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGuillaume Friloux <guillaume.friloux@gmail.com>2013-12-30 16:07:28 +0100
committerGuillaume Friloux <guillaume.friloux@gmail.com>2013-12-30 16:07:28 +0100
commit73a964e7f7b1bff93a476b92b84ad67c25f80cd0 (patch)
tree843ed502cedcfac8ef41316e093b1c1c096c4fad
parent3c753c9cdb3c4f218ee42dd186fdb793fb092ed2 (diff)
Add some doc.
Diffstat
-rw-r--r--doc/doxygen/data/css/edoxy.css16
-rw-r--r--doc/doxygen/data/head.html5
-rw-r--r--doc/doxygen/data/img/intro.png (renamed from doc/img/intro.png)bin29983 -> 29983 bytes
-rw-r--r--doc/smman.dox.in47
-rw-r--r--src/include/Conf.h9
-rw-r--r--src/include/Rules.h9
-rw-r--r--src/include/Spy.h11
-rw-r--r--src/lib/conf/conf_load.c67
-rw-r--r--src/lib/conf/conf_main.c58
-rw-r--r--src/lib/conf/conf_private.h7
-rw-r--r--src/lib/rules/rules_load.c76
-rw-r--r--src/lib/rules/rules_main.c56
-rw-r--r--src/lib/spy/spy_file.c107
-rw-r--r--src/lib/spy/spy_line.c8
-rw-r--r--src/lib/spy/spy_main.c80
15 files changed, 548 insertions, 8 deletions
diff --git a/doc/doxygen/data/css/edoxy.css b/doc/doxygen/data/css/edoxy.css
index 1fd468c..3feb50a 100644
--- a/doc/doxygen/data/css/edoxy.css
+++ b/doc/doxygen/data/css/edoxy.css
@@ -523,3 +523,19 @@ p
523 margin: 5px; 523 margin: 5px;
524 padding-left: 5px; 524 padding-left: 5px;
525} 525}
526
527dl.params dt
528{
529 font-weight: bold;
530}
531
532table.params td
533{
534 font-size: 80%;
535 padding-left: 5px;
536}
537
538dl.return dt
539{
540 font-weight: bold;
541}
diff --git a/doc/doxygen/data/head.html b/doc/doxygen/data/head.html
index bf9da23..fa4e67b 100644
--- a/doc/doxygen/data/head.html
+++ b/doc/doxygen/data/head.html
@@ -2,7 +2,7 @@
2<head> 2<head>
3 <title>$title</title> 3 <title>$title</title>
4 <meta http-equiv="content-type" content="text/html;charset=UTF-8"> 4 <meta http-equiv="content-type" content="text/html;charset=UTF-8">
5 <script src="jquery-1.8.2.min.js"></script> 5 <script src="data/jquery-1.8.2.min.js"></script>
6 <link rel="icon" href="favicon.png" type="image/x-icon"> 6 <link rel="icon" href="favicon.png" type="image/x-icon">
7 <link rel="shortcut icon" href="favicon.png" type="image/x-icon"> 7 <link rel="shortcut icon" href="favicon.png" type="image/x-icon">
8 <link rel="icon" href="favicon.png" type="image/ico"> 8 <link rel="icon" href="favicon.png" type="image/ico">
@@ -32,6 +32,9 @@
32 <div class="submenu"> 32 <div class="submenu">
33 <ul class="current"> 33 <ul class="current">
34 <li class="current"><a href="index.html">Main Page</a></li> 34 <li class="current"><a href="index.html">Main Page</a></li>
35 <li><a href="group__Lib-Conf.html">Conf Library</a></li>
36 <li><a href="group__Lib-Spy.html">Spy Library</a></li>
37 <li><a href="group__Lib-Rules.html">Rules library</a></li>
35 <li><a href="pages.html">Extra Pages</a></li> 38 <li><a href="pages.html">Extra Pages</a></li>
36 </ul> 39 </ul>
37 </div> 40 </div>
diff --git a/doc/img/intro.png b/doc/doxygen/data/img/intro.png
index 4aea29c..4aea29c 100644
--- a/doc/img/intro.png
+++ b/doc/doxygen/data/img/intro.png
Binary files differ
diff --git a/doc/smman.dox.in b/doc/smman.dox.in
index fbac785..da3ef41 100644
--- a/doc/smman.dox.in
+++ b/doc/smman.dox.in
@@ -15,7 +15,7 @@
15 * (using inotify), and extract every new entry. 15 * (using inotify), and extract every new entry.
16 * to filter it using the rules and then indexing it in the configured 16 * to filter it using the rules and then indexing it in the configured
17 * <a href=http://www.elasticsearch.com>ElasticSearch</a> database. 17 * <a href=http://www.elasticsearch.com>ElasticSearch</a> database.
18 * <img src=intro.png> 18 * <img src=data/img/intro.png>
19 * 19 *
20 * <br /> 20 * <br />
21 * @section CONFIGURATION Configuration 21 * @section CONFIGURATION Configuration
@@ -59,3 +59,48 @@ type = syslog
59 * messages properlly with grok. 59 * messages properlly with grok.
60 * 60 *
61 */ 61 */
62
63
64/**
65 * @defgroup Lib-Conf Conf Library
66 *
67 * @section Lib-Conf-Introduction Introduction
68 * Conf is an asynchronous library to help loading/parsing basic configuration
69 * files.
70 * <br />
71 * Each configuration line will be stored in an hash table.
72 *
73 *
74 * @section Lib-Conf-Code Code documentation
75 * @li @ref Lib-Conf-Functions
76 * @defgroup Lib-Conf-Functions API functions
77 */
78
79/**
80 * @defgroup Lib-Spy Spy Library
81 *
82 * @section Lib-Spy-Introduction Introduction
83 * Spy is an asynchronous library to ease the detection of new lines
84 * inside files.
85 * <br />
86 * For every new line detected on a spied file, it will generate a
87 * @b SPY_EVENT_LINE event to ecore that your application will need to
88 * listen for.
89 *
90 * @section Lib-Spy-Code Code documentation
91 * @li @ref Lib-Spy-Functions
92 * @defgroup Lib-Spy-Functions API functions
93 */
94
95/**
96 * @defgroup Lib-Rules Rules Library
97 *
98 * @section Lib-Rules-Introduction Introduction
99 * Rules is an asynchronous library for the loading of smman rules.<br />
100 * These rules are basic configuration files, that we read using the
101 * @ref Lib-Conf.<br />
102 *
103 * @section Lib-Rules-Code Code documentation
104 * @li @ref Lib-Rules-Functions
105 * @defgroup Lib-Rules-Functions API functions
106 */
diff --git a/src/include/Conf.h b/src/include/Conf.h
index 6a007b4..c54a039 100644
--- a/src/include/Conf.h
+++ b/src/include/Conf.h
@@ -4,6 +4,11 @@
4#include <Ecore.h> 4#include <Ecore.h>
5#include <Eio.h> 5#include <Eio.h>
6 6
7/**
8 * @addtogroup Lib-Conf-Functions
9 * @{
10 */
11
7typedef struct _Conf Conf; 12typedef struct _Conf Conf;
8 13
9typedef void (*Conf_Done_Cb)(void *data, Conf *conf); 14typedef void (*Conf_Done_Cb)(void *data, Conf *conf);
@@ -14,4 +19,8 @@ Eina_Hash * conf_variables_get(Conf *conf);
14Eina_Bool conf_load(char *file, Conf_Done_Cb done_cb, Conf_Error_Cb error_cb, const void *data); 19Eina_Bool conf_load(char *file, Conf_Done_Cb done_cb, Conf_Error_Cb error_cb, const void *data);
15int conf_init(void); 20int conf_init(void);
16int conf_shutdown(void); 21int conf_shutdown(void);
22
23/**
24 * @}
25 */
17#endif 26#endif
diff --git a/src/include/Rules.h b/src/include/Rules.h
index fc8518d..88f8624 100644
--- a/src/include/Rules.h
+++ b/src/include/Rules.h
@@ -8,6 +8,11 @@
8#include <sys/types.h> 8#include <sys/types.h>
9#include <regex.h> 9#include <regex.h>
10 10
11/**
12 * @addtogroup Lib-Rules-Functions
13 * @{
14 */
15
11typedef struct _Rules Rules; 16typedef struct _Rules Rules;
12typedef struct _Rule Rule; 17typedef struct _Rule Rule;
13 18
@@ -48,4 +53,8 @@ void rules_purge(Rules *rules);
48Eina_Bool rules_load(Rules *rules, Rules_Progress_Cb progress_cb, Rules_Done_Cb done_cb, Rules_Error_Cb error_cb, void *data); 53Eina_Bool rules_load(Rules *rules, Rules_Progress_Cb progress_cb, Rules_Done_Cb done_cb, Rules_Error_Cb error_cb, void *data);
49 54
50void rules_rule_free(Rule *rule); 55void rules_rule_free(Rule *rule);
56
57/**
58 * @}
59 */
51#endif 60#endif
diff --git a/src/include/Spy.h b/src/include/Spy.h
index 3590075..9d2e0f7 100644
--- a/src/include/Spy.h
+++ b/src/include/Spy.h
@@ -4,7 +4,12 @@
4#include <Ecore.h> 4#include <Ecore.h>
5#include <Eio.h> 5#include <Eio.h>
6 6
7extern int SPY_EVENT_LINE; 7/**
8 * @addtogroup Lib-Spy-Functions
9 * @{
10 */
11
12extern int SPY_EVENT_LINE; /*!< Event created when a new line is found */
8 13
9typedef struct _Spy Spy; 14typedef struct _Spy Spy;
10typedef struct _Spy_File Spy_File; 15typedef struct _Spy_File Spy_File;
@@ -27,4 +32,8 @@ void spy_file_resume(Spy_File *sf);
27 32
28const char * spy_line_get(Spy_Line *sl); 33const char * spy_line_get(Spy_Line *sl);
29Spy_File * spy_line_spyfile_get(Spy_Line *sl); 34Spy_File * spy_line_spyfile_get(Spy_Line *sl);
35
36/**
37 * @}
38 */
30#endif 39#endif
diff --git a/src/lib/conf/conf_load.c b/src/lib/conf/conf_load.c
index bd6c82a..e1192fe 100644
--- a/src/lib/conf/conf_load.c
+++ b/src/lib/conf/conf_load.c
@@ -1,11 +1,35 @@
1#include "conf_private.h" 1#include "conf_private.h"
2 2
3/**
4 * @addtogroup Lib-Conf-Functions
5 * @{
6 */
7
8/**
9 * @cond IGNORE
10 */
11
12/**
13 * @brief Frees an allocated configuration value.
14 * @param data Pointer to allocated conf value.
15 *
16 * This function is called by eina_hash_free() when we ask to free
17 * the conf->variables hash table.
18 */
3void 19void
4conf_load_line_free(void *data) 20conf_load_line_free(void *data)
5{ 21{
6 free(data); 22 free(data);
7} 23}
8 24
25/**
26 * @brief Parse a line into a tuple of variable + value.
27 * @param conf Conf structure.
28 * @param line Line to parse.
29 *
30 * This function is called by conf_load_map_filter for any
31 * line found in the configuration file.
32 */
9void 33void
10conf_load_line_parse(Conf *conf, 34conf_load_line_parse(Conf *conf,
11 char *line) 35 char *line)
@@ -59,6 +83,19 @@ conf_load_line_parse(Conf *conf,
59 eina_strbuf_free(buf); 83 eina_strbuf_free(buf);
60} 84}
61 85
86/**
87 * @brief Read configuration file line by line.
88 * @param data Conf_Load structure.
89 * @param handler UNUSED.
90 * @param map Data from configuration file.
91 * @param length Length of data.
92 *
93 * @return EINA_TRUE.
94 *
95 * This function is called by eio_file_map_all(),
96 * <b>from its own thread</b>, when it successfully loaded
97 * the configuration file.
98 */
62Eina_Bool 99Eina_Bool
63conf_load_map_filter(void *data, 100conf_load_map_filter(void *data,
64 Eio_File *handler EINA_UNUSED, 101 Eio_File *handler EINA_UNUSED,
@@ -104,6 +141,18 @@ conf_load_map_filter(void *data,
104 return EINA_TRUE; 141 return EINA_TRUE;
105} 142}
106 143
144/**
145 * @brief Call callback from app to tell we ended to load configuration file.
146 *
147 * @param data Conf_Load structure.
148 * @param handler UNUSED.
149 * @param map UNUSED.
150 * @param length UNUSED.
151 *
152 * This function is called by eio_file_map_all() from the main loop.<br />
153 * It is usefull for us to warn our caller that we ended parsing of file,
154 * from main loop.
155 */
107void 156void
108conf_load_map_main(void *data, 157conf_load_map_main(void *data,
109 Eio_File *handler EINA_UNUSED, 158 Eio_File *handler EINA_UNUSED,
@@ -120,6 +169,16 @@ conf_load_map_main(void *data,
120 free(cl); 169 free(cl);
121} 170}
122 171
172/**
173 * @brief Call callback from app to tell we got an error.
174 *
175 * @param data Conf_Load structure.
176 * @param handler UNUSED.
177 * @param error See errno(3)
178 *
179 * This function gets called by eio_file_map_all() if eio failed to mmap
180 * file. This call is made from the main loop.
181 */
123void 182void
124conf_load_map_error(void *data, 183conf_load_map_error(void *data,
125 Eio_File *handler EINA_UNUSED, 184 Eio_File *handler EINA_UNUSED,
@@ -135,3 +194,11 @@ conf_load_map_error(void *data,
135 conf_free(cl->conf); 194 conf_free(cl->conf);
136 free(cl); 195 free(cl);
137} 196}
197
198/**
199 * @endcond
200 */
201
202/**
203 * @}
204 */
diff --git a/src/lib/conf/conf_main.c b/src/lib/conf/conf_main.c
index b3c7899..c683fd9 100644
--- a/src/lib/conf/conf_main.c
+++ b/src/lib/conf/conf_main.c
@@ -1,8 +1,27 @@
1#include "conf_private.h" 1#include "conf_private.h"
2 2
3/**
4 * @addtogroup Lib-Conf-Functions
5 * @{
6 */
7
8
9/**
10 * @cond IGNORE
11 */
3static int _conf_init_count = 0; 12static int _conf_init_count = 0;
4int _conf_log_dom_global = -1; 13int _conf_log_dom_global = -1;
5 14/**
15 * @endcond
16 */
17
18/**
19 * @brief Returns a pointer to the filename of the conf.
20 *
21 * @param conf Conf structure.
22 * @return Pointer to the filename. Do not free it as it is a pointer to the
23 * internal's buffer.
24 */
6const char * 25const char *
7conf_file_get(Conf *conf) 26conf_file_get(Conf *conf)
8{ 27{
@@ -10,6 +29,12 @@ conf_file_get(Conf *conf)
10 return conf->file; 29 return conf->file;
11} 30}
12 31
32/**
33 * @brief Returns an hash table having the keys/values of the conf.
34 *
35 * @param conf Conf structure.
36 * @return Pointer to the internal Hash table. Do not free it!
37 */
13Eina_Hash * 38Eina_Hash *
14conf_variables_get(Conf *conf) 39conf_variables_get(Conf *conf)
15{ 40{
@@ -17,6 +42,11 @@ conf_variables_get(Conf *conf)
17 return conf->variables; 42 return conf->variables;
18} 43}
19 44
45/**
46 * @brief Frees an allocated Conf structure.
47 *
48 * @param conf Conf structure.
49 */
20void 50void
21conf_free(Conf *conf) 51conf_free(Conf *conf)
22{ 52{
@@ -37,6 +67,17 @@ conf_free(Conf *conf)
37 free(conf); 67 free(conf);
38} 68}
39 69
70/**
71 * @brief Loads the configuration file.
72 *
73 * @param file Configuration file to load.
74 * @param done_cb Callback called in the main loop when the file has been
75 * successfully loaded.
76 * @param error_cb Callback called in the main loop when the file couldn't
77 * be loaded.
78 * @param data Unmodified user data passed to callbacks.
79 * @return EINA_TRUE if successfull, EINA_FALSE otherwise.
80 */
40Eina_Bool 81Eina_Bool
41conf_load(char *file, 82conf_load(char *file,
42 Conf_Done_Cb done_cb, 83 Conf_Done_Cb done_cb,
@@ -100,6 +141,10 @@ free_conf:
100 return EINA_FALSE; 141 return EINA_FALSE;
101} 142}
102 143
144/**
145 * @brief Initialize conf and all it's required submodule.
146 * @return 1 or greater on success, 0 otherwise.
147 */
103int conf_init(void) 148int conf_init(void)
104{ 149{
105 if (++_conf_init_count != 1) 150 if (++_conf_init_count != 1)
@@ -143,6 +188,13 @@ shutdown_eina:
143 return --_conf_init_count; 188 return --_conf_init_count;
144} 189}
145 190
191/**
192 * @brief Shutdown conf and all it's submodule if possible.
193 *
194 * @return 0 if conf shuts down, greater than 0 otherwise.
195 * This function shuts down all things set up in conf_init()
196 * and cleans up its memory.
197 */
146int 198int
147conf_shutdown(void) 199conf_shutdown(void)
148{ 200{
@@ -162,3 +214,7 @@ conf_shutdown(void)
162 eina_shutdown(); 214 eina_shutdown();
163 return _conf_init_count; 215 return _conf_init_count;
164} 216}
217
218/**
219 * @}
220 */
diff --git a/src/lib/conf/conf_private.h b/src/lib/conf/conf_private.h
index 693f36e..8f405f6 100644
--- a/src/lib/conf/conf_private.h
+++ b/src/lib/conf/conf_private.h
@@ -1,5 +1,8 @@
1#include <Conf.h> 1#include <Conf.h>
2 2
3/**
4 * @cond IGNORE
5 */
3extern int _conf_log_dom_global; 6extern int _conf_log_dom_global;
4 7
5#define ERR(...) EINA_LOG_DOM_ERR(_conf_log_dom_global, __VA_ARGS__) 8#define ERR(...) EINA_LOG_DOM_ERR(_conf_log_dom_global, __VA_ARGS__)
@@ -36,3 +39,7 @@ void conf_load_map_main(void *data, Eio_File *handler, void *map, size_t length)
36void conf_load_map_error(void *data, Eio_File *handler, int error); 39void conf_load_map_error(void *data, Eio_File *handler, int error);
37 40
38void conf_load_line_free(void *data); 41void conf_load_line_free(void *data);
42
43/**
44 * @endcond
45 */
diff --git a/src/lib/rules/rules_load.c b/src/lib/rules/rules_load.c
index a4f24af..8584fe4 100644
--- a/src/lib/rules/rules_load.c
+++ b/src/lib/rules/rules_load.c
@@ -1,5 +1,25 @@
1#include "rules_private.h" 1#include "rules_private.h"
2 2
3/**
4 * @addtogroup Lib-Rules-Functions
5 * @{
6 */
7
8/**
9 * @cond IGNORE
10 */
11
12/**
13 * @brief Create a Rule structure from tuple given by @ref Lib-Conf
14 *
15 * @param data Rules_Load structure.
16 * @param conf Conf structure.
17 *
18 * This function is called by conf_load() when the loading of the rule
19 * is over.<br />
20 * Once the rule is allocated, it is added to the rules's list and
21 * given to the progress callback.
22 */
3void 23void
4rules_load_rule(void *data, 24rules_load_rule(void *data,
5 Conf *conf) 25 Conf *conf)
@@ -87,6 +107,16 @@ rules_load_rule(void *data,
87 EINA_INLIST_GET(rule)); 107 EINA_INLIST_GET(rule));
88} 108}
89 109
110/**
111 * @brief Reports an error to the error Callback defined by app.
112 *
113 * @param data Rules_Load structure.
114 * @param conf Conf structure.
115 * @param errstr Error string given by @ref Lib-Conf
116 *
117 * This function is called by conf_load() if it failed to read and parse
118 * a configuration file.
119 */
90void 120void
91rules_load_rule_error(void *data, 121rules_load_rule_error(void *data,
92 Conf *conf, 122 Conf *conf,
@@ -101,6 +131,15 @@ rules_load_rule_error(void *data,
101 free(rl); 131 free(rl);
102} 132}
103 133
134/**
135 * @brief Filter called from eio's thread, we filter directories.
136 *
137 * @param data UNUSED
138 * @param handler UNUSED
139 * @param info Eina_File_Direct_Info structure of file.
140 *
141 * @return EINA_FALSE if passed file is a directory, EINA_TRUE otherwise.
142 */
104Eina_Bool 143Eina_Bool
105rules_load_ls_filter(void *data EINA_UNUSED, 144rules_load_ls_filter(void *data EINA_UNUSED,
106 Eio_File *handler EINA_UNUSED, 145 Eio_File *handler EINA_UNUSED,
@@ -111,6 +150,15 @@ rules_load_ls_filter(void *data EINA_UNUSED,
111 return EINA_TRUE; 150 return EINA_TRUE;
112} 151}
113 152
153/**
154 * @brief Load one found rule.
155 *
156 * @param data Rules_Load structure.
157 * @param handler UNUSED.
158 * @param info Eina_File_Direct_Info structure of file.
159 *
160 * This function is called by eio_file_direct_ls() for every file listed.
161 */
114void 162void
115rules_load_ls(void *data, 163rules_load_ls(void *data,
116 Eio_File *handler EINA_UNUSED, 164 Eio_File *handler EINA_UNUSED,
@@ -128,6 +176,15 @@ rules_load_ls(void *data,
128 rl); 176 rl);
129} 177}
130 178
179/**
180 * @brief Reports the end of rules loading.
181 *
182 * @param data Rules_Load structure.
183 * @param handler UNUSED.
184 *
185 * This function gets called by eio_file_direct_ls() (from rules_load()) when
186 * listing of files is over.
187 */
131void 188void
132rules_load_ls_done(void *data, 189rules_load_ls_done(void *data,
133 Eio_File *handler EINA_UNUSED) 190 Eio_File *handler EINA_UNUSED)
@@ -138,7 +195,16 @@ rules_load_ls_done(void *data,
138 free(rl); 195 free(rl);
139} 196}
140 197
141 198/**
199 * @brief Reports an error to the error Callback defined by app.
200 *
201 * @param data Rules_Load structure.
202 * @param handler UNUSED.
203 * @param error errno from eio.
204 *
205 * This function gets called by eio_file_direct_ls() when an error occurs
206 * while listing files.
207 */
142void 208void
143rules_load_ls_error(void *data, 209rules_load_ls_error(void *data,
144 Eio_File *handler EINA_UNUSED, 210 Eio_File *handler EINA_UNUSED,
@@ -153,3 +219,11 @@ rules_load_ls_error(void *data,
153 rl->cb.error((void *)rl->cb.data, rl->rules, "Failed to list rules directory"); 219 rl->cb.error((void *)rl->cb.data, rl->rules, "Failed to list rules directory");
154 free(rl); 220 free(rl);
155} 221}
222
223/**
224 * @endcond
225 */
226
227/**
228 * @}
229 */
diff --git a/src/lib/rules/rules_main.c b/src/lib/rules/rules_main.c
index 208dead..7f18ce9 100644
--- a/src/lib/rules/rules_main.c
+++ b/src/lib/rules/rules_main.c
@@ -1,9 +1,26 @@
1#include "rules_private.h" 1#include "rules_private.h"
2 2
3/**
4 * @addtogroup Lib-Rules-Functions
5 * @{
6 */
7
8/**
9 * @cond IGNORE
10 */
11
3static int _rules_init_count = 0; 12static int _rules_init_count = 0;
4int _rules_log_dom_global = -1; 13int _rules_log_dom_global = -1;
5 14
15/**
16 * @endcond
17 */
6 18
19/**
20 * @brief Frees a Rule structure.
21 *
22 * @param rule Rule structure to free.
23 */
7void 24void
8rules_rule_free(Rule *rule) 25rules_rule_free(Rule *rule)
9{ 26{
@@ -29,6 +46,13 @@ rules_rule_free(Rule *rule)
29 free(rule); 46 free(rule);
30} 47}
31 48
49/**
50 * @brief Creates a new Rules structure.
51 *
52 * @param directory Directory to read to load all the rules.
53 *
54 * @return Pointer to new Rules structure.
55 */
32Rules * 56Rules *
33rules_new(const char *directory) 57rules_new(const char *directory)
34{ 58{
@@ -39,6 +63,11 @@ rules_new(const char *directory)
39 return rules; 63 return rules;
40} 64}
41 65
66/**
67 * @brief Unload all the loaded rules.
68 *
69 * @param rules Rules structure to unload.
70 */
42void 71void
43rules_purge(Rules *rules) 72rules_purge(Rules *rules)
44{ 73{
@@ -50,6 +79,17 @@ rules_purge(Rules *rules)
50 } 79 }
51} 80}
52 81
82/**
83 * @brief Initiate the loading of all the rules that can be found.
84 *
85 * @param rules Rules structure to use for loading.
86 * @param progress_cb Callback called in the main loop for each rule loaded.
87 * @param done_cb Callback called in the main loop when loading is over.
88 * @param error_cb Callback called in the main loop when an error occurs.
89 * @param data Unmodified user data passed to callbacks.
90 *
91 * @return EINA_TRUE.
92 */
53Eina_Bool 93Eina_Bool
54rules_load(Rules *rules, 94rules_load(Rules *rules,
55 Rules_Progress_Cb progress_cb, 95 Rules_Progress_Cb progress_cb,
@@ -76,6 +116,11 @@ rules_load(Rules *rules,
76 return EINA_TRUE; 116 return EINA_TRUE;
77} 117}
78 118
119/**
120 * @brief Initialize Rules and all it's required submodules.
121 *
122 * @return 1 or greater on success, 0 otherwise.
123 */
79int 124int
80rules_init(void) 125rules_init(void)
81{ 126{
@@ -127,6 +172,13 @@ shutdown_eina:
127 return --_rules_init_count; 172 return --_rules_init_count;
128} 173}
129 174
175/**
176 * @brief Shutdown conf and all it's submodules if possible.
177 *
178 * @return 0 if rules shuts down, greater than 0 otherwise.
179 * This function shuts down all things set up in rules_init()
180 * and cleans up its memory.
181 */
130int 182int
131rules_shutdown(void) 183rules_shutdown(void)
132{ 184{
@@ -147,3 +199,7 @@ rules_shutdown(void)
147 eina_shutdown(); 199 eina_shutdown();
148 return _rules_init_count; 200 return _rules_init_count;
149} 201}
202
203/**
204 * @}
205 */
diff --git a/src/lib/spy/spy_file.c b/src/lib/spy/spy_file.c
index adef42d..646115a 100644
--- a/src/lib/spy/spy_file.c
+++ b/src/lib/spy/spy_file.c
@@ -5,6 +5,21 @@
5#include <sys/types.h> 5#include <sys/types.h>
6#include <unistd.h> 6#include <unistd.h>
7 7
8/**
9 * @addtogroup Lib-Spy-Functions
10 * @{
11 */
12
13/**
14 * @cond IGNORE
15 */
16
17/**
18 * @brief Frees data associated to SPY_EVENT_LINE event.
19 *
20 * @param d1 Spy_Line structure to free.
21 * @param d2 UNUSED
22 */
8void 23void
9_spy_file_line_free(void *d1, 24_spy_file_line_free(void *d1,
10 void *d2 EINA_UNUSED) 25 void *d2 EINA_UNUSED)
@@ -15,6 +30,14 @@ _spy_file_line_free(void *d1,
15 free(sl); 30 free(sl);
16} 31}
17 32
33/**
34 * @brief Creates a SPY_EVENT_LINE event to ecore.
35 *
36 * @param data Spy_Line structure to associate to event.
37 *
38 * This function is called by _spy_file_line_extract(), but from
39 * the main loop.
40 */
18static void 41static void
19_spy_file_event(void *data) 42_spy_file_event(void *data)
20{ 43{
@@ -24,12 +47,32 @@ _spy_file_event(void *data)
24 ecore_event_add(SPY_EVENT_LINE, sl, _spy_file_line_free, sl); 47 ecore_event_add(SPY_EVENT_LINE, sl, _spy_file_line_free, sl);
25} 48}
26 49
50/**
51 * @brief Immediately launch a poll on given Spy_File structure.
52 *
53 * @param data Spy_File structure.
54 *
55 * This function is called by an ecore_job to start a poll.
56 * It is recommended to do it using an ecore_job instead of a direct
57 * call to avoid constant blocking on the main loop in case of a file
58 * that is getting logs too frequently.
59 */
27static void 60static void
28_spy_file_job(void *data) 61_spy_file_job(void *data)
29{ 62{
30 spy_file_poll(data); 63 spy_file_poll(data);
31} 64}
32 65
66/**
67 * @brief Extract one line from buffered data.
68 *
69 * @param sf Spy_File structure to use for buffered data.
70 *
71 * This function is called by spy_file_cb(), and thus, running from
72 * a thread.<br />
73 * For each line found, this function will initiate a SPY_EVENT_LINE
74 * event from the main loop.
75 */
33void 76void
34_spy_file_line_extract(Spy_File *sf) 77_spy_file_line_extract(Spy_File *sf)
35{ 78{
@@ -69,6 +112,15 @@ _spy_file_line_extract(Spy_File *sf)
69 } 112 }
70} 113}
71 114
115/**
116 * @brief Read new lines from a file.
117 *
118 * @param data Spy_File structure of the file to read.
119 * @param thread UNUSED.
120 *
121 * This function is running in a separate thread to not block the main
122 * loop while reading and parsing file.
123 */
72void 124void
73_spy_file_cb(void *data, 125_spy_file_cb(void *data,
74 Ecore_Thread *thread EINA_UNUSED) 126 Ecore_Thread *thread EINA_UNUSED)
@@ -111,6 +163,15 @@ _spy_file_cb(void *data,
111 sf->poll.size += sf->read.nbr; 163 sf->poll.size += sf->read.nbr;
112} 164}
113 165
166/**
167 * @brief Initiate another poll on the given file.
168 *
169 * @param data Spy_File structure to poll.
170 * @param thread UNUSED.
171 *
172 * This function is called by ecore when thread running _spy_file_cb()
173 * has ended.
174 */
114void 175void
115_spy_file_end_cb(void *data, 176_spy_file_end_cb(void *data,
116 Ecore_Thread *thread EINA_UNUSED) 177 Ecore_Thread *thread EINA_UNUSED)
@@ -125,11 +186,33 @@ _spy_file_end_cb(void *data,
125 ecore_job_add(_spy_file_job, sf); 186 ecore_job_add(_spy_file_job, sf);
126} 187}
127 188
189/**
190 * @brief Unused function, would be called if we cancel our thread,
191 * but we never do it.
192 *
193 * @param data UNUSED.
194 * @param thread UNUSED.
195 */
128void 196void
129_spy_file_cancel_cb(void *data EINA_UNUSED, 197_spy_file_cancel_cb(void *data EINA_UNUSED,
130 Ecore_Thread *thread EINA_UNUSED) 198 Ecore_Thread *thread EINA_UNUSED)
131{} 199{}
132 200
201/**
202 * @endcond
203 */
204
205/**
206 * @brief Verify is a file changed.
207 *
208 * @param data Spy_File structure of the file to check.
209 *
210 * @return EINA_TRUE.
211 *
212 * This function is called by the timer of the Spy_File, and will check
213 * the filesize of the file to detect changes. It will detect the # of bytes
214 * to read and start a thread to take care of it (reading/parsing).
215 */
133Eina_Bool 216Eina_Bool
134spy_file_poll(void *data) 217spy_file_poll(void *data)
135{ 218{
@@ -183,6 +266,13 @@ spy_file_poll(void *data)
183 return EINA_TRUE; 266 return EINA_TRUE;
184} 267}
185 268
269/**
270 * @brief Returns the fullpath of the file being spied.
271 *
272 * @param sf Spy_File structure.
273 *
274 * @return Pointer to internal buffer. DO NOT FREE IT.
275 */
186const char * 276const char *
187spy_file_name_get(Spy_File *sf) 277spy_file_name_get(Spy_File *sf)
188{ 278{
@@ -190,6 +280,12 @@ spy_file_name_get(Spy_File *sf)
190 return sf->name; 280 return sf->name;
191} 281}
192 282
283/**
284 * @brief Attach data to the Spy_File structure.
285 *
286 * @param sf Spy_File structure to attach data to.
287 * @param data Pointer to the data to attach.
288 */
193void 289void
194spy_file_data_set(Spy_File *sf, 290spy_file_data_set(Spy_File *sf,
195 const void *data) 291 const void *data)
@@ -198,9 +294,20 @@ spy_file_data_set(Spy_File *sf,
198 sf->data = (const void *)data; 294 sf->data = (const void *)data;
199} 295}
200 296
297/**
298 * @brief Get the data attached to a Spy_File structure.
299 *
300 * @param sf Spy_File structure whose data is needed.
301 *
302 * @return Pointer to the data attached.
303 */
201void * 304void *
202spy_file_data_get(Spy_File *sf) 305spy_file_data_get(Spy_File *sf)
203{ 306{
204 EINA_SAFETY_ON_NULL_RETURN_VAL(sf, NULL); 307 EINA_SAFETY_ON_NULL_RETURN_VAL(sf, NULL);
205 return (void *)sf->data; 308 return (void *)sf->data;
206} 309}
310
311/**
312 * @}
313 */
diff --git a/src/lib/spy/spy_line.c b/src/lib/spy/spy_line.c
index 0768027..b9c076b 100644
--- a/src/lib/spy/spy_line.c
+++ b/src/lib/spy/spy_line.c
@@ -1,5 +1,10 @@
1#include "spy_private.h" 1#include "spy_private.h"
2 2
3/**
4 * @addtogroup Lib-Spy-Functions
5 * @{
6 */
7
3const char * 8const char *
4spy_line_get(Spy_Line *sl) 9spy_line_get(Spy_Line *sl)
5{ 10{
@@ -12,3 +17,6 @@ spy_line_spyfile_get(Spy_Line *sl)
12 return sl->sf; 17 return sl->sf;
13} 18}
14 19
20/**
21 * @}
22 */
diff --git a/src/lib/spy/spy_main.c b/src/lib/spy/spy_main.c
index 1e512a0..d1beec6 100644
--- a/src/lib/spy/spy_main.c
+++ b/src/lib/spy/spy_main.c
@@ -3,11 +3,26 @@
3#include <fcntl.h> 3#include <fcntl.h>
4#include <unistd.h> 4#include <unistd.h>
5 5
6/**
7 * @addtogroup Lib-Spy-Functions
8 * @{
9 */
10
11/**
12 * @cond IGNORE
13 */
6static int _spy_init_count = 0; 14static int _spy_init_count = 0;
7int _spy_log_dom_global = -1; 15int _spy_log_dom_global = -1;
8 16
9int SPY_EVENT_LINE = 0; 17int SPY_EVENT_LINE = 0;
10 18/**
19 * @endcond
20 */
21
22/**
23 * @brief Create a new Spy structure.
24 * @return Pointer to newly created Spy or NULL if allocation failed.
25 */
11Spy * 26Spy *
12spy_new(void) 27spy_new(void)
13{ 28{
@@ -18,6 +33,13 @@ spy_new(void)
18 return spy; 33 return spy;
19} 34}
20 35
36/**
37 * @brief Frees a Spy structure.
38 *
39 * @param Spy structure to free.
40 *
41 * This function will also free all the associated Spy_File structures.
42 */
21void 43void
22spy_free(Spy *spy) 44spy_free(Spy *spy)
23{ 45{
@@ -30,6 +52,13 @@ spy_free(Spy *spy)
30 free(spy); 52 free(spy);
31} 53}
32 54
55/**
56 * @brief Frees a Spy_File structure.
57 *
58 * @param sf Spy_File structure to free.
59 *
60 * This function will also remove the Spy_File from the Spy list.
61 */
33void 62void
34spy_file_free(Spy_File *sf) 63spy_file_free(Spy_File *sf)
35{ 64{
@@ -52,6 +81,13 @@ spy_file_free(Spy_File *sf)
52 free(sf); 81 free(sf);
53} 82}
54 83
84/**
85 * @brief Pause spying of a file.
86 *
87 * @param sf Spy_File to pause.
88 *
89 * It doesnt stop its timer, but will block size checking.
90 */
55void 91void
56spy_file_pause(Spy_File *sf) 92spy_file_pause(Spy_File *sf)
57{ 93{
@@ -60,6 +96,13 @@ spy_file_pause(Spy_File *sf)
60 sf->poll.pause = EINA_TRUE; 96 sf->poll.pause = EINA_TRUE;
61} 97}
62 98
99/**
100 * @brief Resume spying of a file.
101 *
102 * @param sf Spy_File to resume.
103 *
104 * This function allows to resume the spying of a file that got paused.
105 */
63void 106void
64spy_file_resume(Spy_File *sf) 107spy_file_resume(Spy_File *sf)
65{ 108{
@@ -68,6 +111,15 @@ spy_file_resume(Spy_File *sf)
68 sf->poll.pause = EINA_FALSE; 111 sf->poll.pause = EINA_FALSE;
69} 112}
70 113
114/**
115 * @brief Get the Spy_File associated to a file.
116 *
117 * @param spy Spy structure to inpect.
118 * @param file File to search for.
119 * @return Spy_File structure spying the file, or NULL.
120 *
121 * This can be used to know if we are already spying a file or not
122 */
71Spy_File * 123Spy_File *
72spy_file_get(Spy *spy, const char *file) 124spy_file_get(Spy *spy, const char *file)
73{ 125{
@@ -82,6 +134,15 @@ spy_file_get(Spy *spy, const char *file)
82 return NULL; 134 return NULL;
83} 135}
84 136
137/**
138 * @brief Start to spy a file.
139 * @param spy Spy structure to attach file to.
140 * @param file File to start spying.
141 * @return Pointer to newly allocated Spy_File structure.
142 *
143 * This function will add a timer that will periodically look for changes
144 * on the file, and report every new line inserted into it.
145 */
85Spy_File * 146Spy_File *
86spy_file_new(Spy *spy, const char *file) 147spy_file_new(Spy *spy, const char *file)
87{ 148{
@@ -138,7 +199,10 @@ free_sf:
138 return NULL; 199 return NULL;
139} 200}
140 201
141 202/**
203 * @brief Initialize spy and all it's required submodules.
204 * @return 1 or greater on success, 0 otherwise.
205 */
142int 206int
143spy_init(void) 207spy_init(void)
144{ 208{
@@ -176,7 +240,13 @@ shutdown_eina:
176 return --_spy_init_count; 240 return --_spy_init_count;
177} 241}
178 242
179 243/**
244 * @brief Shutdown spy and all it's submodules if possible.
245 *
246 * @return 0 if spy shuts down, greater than 0 otherwise.
247 * This function shuts down all things set up in spy_init()
248 * and cleans up its memory.
249 */
180int 250int
181spy_shutdown(void) 251spy_shutdown(void)
182{ 252{
@@ -195,3 +265,7 @@ spy_shutdown(void)
195 eina_shutdown(); 265 eina_shutdown();
196 return _spy_init_count; 266 return _spy_init_count;
197} 267}
268
269/**
270 * @}
271 */
Copyright © Enlightenment.org