updated Doxyfile
[strongswan.git] / src / libstrongswan / utils / enumerator.h
1 /*
2 * Copyright (C) 2007 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 *
15 * $Id$
16 */
17
18 /**
19 * @defgroup enumerator enumerator
20 * @{ @ingroup utils
21 */
22
23 #ifndef ENUMERATOR_H_
24 #define ENUMERATOR_H_
25
26 typedef struct enumerator_t enumerator_t;
27
28 #include <library.h>
29
30 /**
31 * Enumerate is simpler, but more flexible than iterator.
32 */
33 struct enumerator_t {
34
35 /**
36 * Enumerate collection.
37 *
38 * The enumerate function takes a variable argument list containing
39 * pointers where the enumerated values get written.
40 *
41 * @param ... variable list of enumerated items, implementation dependant
42 * @return TRUE if pointers returned
43 */
44 bool (*enumerate)(enumerator_t *this, ...);
45
46 /**
47 * Destroy a enumerator instance.
48 */
49 void (*destroy)(enumerator_t *this);
50 };
51
52 /**
53 * Create an enumerator which enumerates over nothing
54 *
55 * @return an enumerator over no values
56 */
57 enumerator_t* enumerator_create_empty();
58
59 /**
60 * Create an enumerator which enumerates over a single item
61 *
62 * @param item item to enumerate
63 * @param cleanup cleanup function called on destroy with the item
64 * @return an enumerator over a single value
65 */
66 enumerator_t *enumerator_create_single(void *item, void (*cleanup)(void *item));
67
68 /**
69 * Create an enumerator over files/subdirectories in a directory.
70 *
71 * This enumerator_t.enumerate() function returns a (to the directory) relative
72 * filename (as a char*), an absolute filename (as a char*) and a file status
73 * (to a struct stat), which all may be NULL. "." and ".." entries are
74 * skipped. Example:
75 *
76 * @code
77 char *rel, *abs;
78 struct stat st;
79 enumerator_t *e;
80
81 e = enumerator_create_directory("/tmp");
82 if (e)
83 {
84 while (e->enumerate(e, &rel, &abs, &st))
85 {
86 if (S_ISDIR(st.st_mode) && *rel != '.')
87 {
88 printf("%s\n", abs);
89 }
90 }
91 e->destroy(e);
92 }
93 @endcode
94 *
95 * @param path path of the directory
96 * @return the directory enumerator, NULL on failure
97 */
98 enumerator_t* enumerator_create_directory(char *path);
99
100 /**
101 * Create an enumerator over tokens of a string.
102 *
103 * Tokens are separated by one of the characters in sep and trimmed by the
104 * characters in trim.
105 *
106 * @param string string to parse
107 * @param sep separator characters
108 * @param trim characters to trim from tokens
109 * @return enumerator over char* tokens
110 */
111 enumerator_t* enumerator_create_token(char *string, char *sep, char *trim);
112
113 /**
114 * Creates an enumerator which enumerates over enumerated enumerators :-).
115 *
116 * The variable argument list of enumeration values is limit to 5.
117 *
118 * @param outer outer enumerator
119 * @param inner_constructor constructor to inner enumerator
120 * @param data data to pass to each inner_constructor call
121 * @param destroy_data destructor to pass to data
122 * @return the nested enumerator
123 */
124 enumerator_t *enumerator_create_nested(enumerator_t *outer,
125 enumerator_t *(*inner_constructor)(void *outer, void *data),
126 void *data, void (*destroy_data)(void *data));
127
128 /**
129 * Creates an enumerator which filters output of another enumerator.
130 *
131 * The filter function receives the user supplied "data" followed by a
132 * unfiltered enumeration item, followed by an output pointer where to write
133 * the filtered data. Then the next input/output pair follows.
134 * It returns TRUE to deliver the
135 * values to the caller of enumerate(), FALSE to filter this enumeration.
136 *
137 * The variable argument list of enumeration values is limit to 5.
138 *
139 * @param unfiltered unfiltered enumerator to wrap, gets destroyed
140 * @param filter filter function
141 * @param data user data to supply to filter
142 * @param destructor destructor function to clean up data after use
143 * @return the filtered enumerator
144 */
145 enumerator_t *enumerator_create_filter(enumerator_t *unfiltered,
146 bool (*filter)(void *data, ...),
147 void *data, void (*destructor)(void *data));
148
149 /**
150 * Create an enumerator wrapper which does a cleanup on destroy.
151 *
152 * @param wrapped wrapped enumerator
153 * @param cleanup cleanup function called on destroy
154 * @param data user data to supply to cleanup
155 * @return the enumerator with cleanup
156 */
157 enumerator_t *enumerator_create_cleaner(enumerator_t *wrapped,
158 void (*cleanup)(void *data), void *data);
159
160 #endif /** ENUMERATOR_H_ @}*/