botan: Add support for Ed25519 keys
[strongswan.git] / src / libstrongswan / collections / enumerator.h
1 /*
2 * Copyright (C) 2013-2017 Tobias Brunner
3 * Copyright (C) 2007 Martin Willi
4 * HSR Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup enumerator enumerator
19 * @{ @ingroup collections
20 */
21
22 #ifndef ENUMERATOR_H_
23 #define ENUMERATOR_H_
24
25 typedef struct enumerator_t enumerator_t;
26
27 #include <utils/utils.h>
28
29 /**
30 * Enumerator interface, allows enumeration over collections.
31 */
32 struct enumerator_t {
33
34 /**
35 * Enumerate collection.
36 *
37 * The enumerate() method takes a variable number of pointer arguments
38 * where the enumerated values get written to.
39 *
40 * @note Just assigning the generic enumerator_enumerate_default() function
41 * that calls the enumerator's venumerate() method is usually enough.
42 *
43 * @param ... variable list of enumerated items, implementation dependent
44 * @return TRUE if pointers returned
45 */
46 bool (*enumerate)(enumerator_t *this, ...);
47
48 /**
49 * Enumerate collection.
50 *
51 * The venumerate() method takes a variable argument list containing
52 * pointers where the enumerated values get written to.
53 *
54 * To simplify the implementation the VA_ARGS_VGET() macro may be used.
55 *
56 * @param args variable list of enumerated items, implementation dependent
57 * @return TRUE if pointers returned
58 */
59 bool (*venumerate)(enumerator_t *this, va_list args);
60
61 /**
62 * Destroy an enumerator_t instance.
63 */
64 void (*destroy)(enumerator_t *this);
65 };
66
67 /**
68 * Generic implementation of enumerator_t::enumerate() that simply calls
69 * the enumerator's venumerate() method.
70 *
71 * @param enumerator the enumerator
72 * @param ... arguments passed to enumerate()
73 */
74 bool enumerator_enumerate_default(enumerator_t *enumerator, ...);
75
76 /**
77 * Create an enumerator which enumerates over nothing
78 *
79 * @return an enumerator over no values
80 */
81 enumerator_t* enumerator_create_empty();
82
83 /**
84 * Create an enumerator which enumerates over a single item
85 *
86 * @param item item to enumerate
87 * @param cleanup cleanup function called on destroy with the item
88 * @return an enumerator over a single value
89 */
90 enumerator_t *enumerator_create_single(void *item, void (*cleanup)(void *item));
91
92 /**
93 * Create an enumerator over files/subdirectories in a directory.
94 *
95 * This enumerator_t.enumerate() function returns a (to the directory) relative
96 * filename (as a char*), an absolute filename (as a char*) and a file status
97 * (to a struct stat), which all may be NULL. "." and ".." entries are
98 * skipped.
99 *
100 * Example:
101 *
102 * @code
103 char *rel, *abs;
104 struct stat st;
105 enumerator_t *e;
106
107 e = enumerator_create_directory("/tmp");
108 if (e)
109 {
110 while (e->enumerate(e, &rel, &abs, &st))
111 {
112 if (S_ISDIR(st.st_mode) && *rel != '.')
113 {
114 printf("%s\n", abs);
115 }
116 }
117 e->destroy(e);
118 }
119 @endcode
120 *
121 * @param path path of the directory
122 * @return the directory enumerator, NULL on failure
123 */
124 enumerator_t* enumerator_create_directory(const char *path);
125
126 /**
127 * Create an enumerator over files/directories matching a file pattern.
128 *
129 * This enumerator_t.enumerate() function returns the filename (as a char*),
130 * and a file status (to a struct stat), which both may be NULL.
131 *
132 * Example:
133 *
134 * @code
135 char *file;
136 struct stat st;
137 enumerator_t *e;
138
139 e = enumerator_create_glob("/etc/ipsec.*.conf");
140 if (e)
141 {
142 while (e->enumerate(e, &file, &st))
143 {
144 if (S_ISREG(st.st_mode))
145 {
146 printf("%s\n", file);
147 }
148 }
149 e->destroy(e);
150 }
151 @endcode
152 *
153 * @param pattern file pattern to match
154 * @return the enumerator, NULL if not supported
155 */
156 enumerator_t* enumerator_create_glob(const char *pattern);
157
158 /**
159 * Create an enumerator over tokens of a string.
160 *
161 * Tokens are separated by one of the characters in sep and trimmed by the
162 * characters in trim.
163 *
164 * @param string string to parse
165 * @param sep separator characters
166 * @param trim characters to trim from tokens
167 * @return enumerator over char* tokens
168 */
169 enumerator_t* enumerator_create_token(const char *string, const char *sep,
170 const char *trim);
171
172 /**
173 * Creates an enumerator which enumerates over enumerated enumerators :-).
174 *
175 * The outer enumerator is expected to return objects that, when passed to
176 * inner_contructor, will create a new enumerator that will be enumerated until
177 * completion (to this enumerator will the pointer arguments that are passed to
178 * this enumerator be forwarded) at which point a new element from the outer
179 * enumerator is requested to create a new inner enumerator.
180 *
181 * @param outer outer enumerator
182 * @param inner_constructor constructor to create inner enumerator
183 * @param data data to pass to each inner_constructor call
184 * @param destructor destructor function to clean up data after use
185 * @return the nested enumerator
186 */
187 enumerator_t *enumerator_create_nested(enumerator_t *outer,
188 enumerator_t *(*inner_constructor)(void *outer, void *data),
189 void *data, void (*destructor)(void *data));
190
191 /**
192 * Creates an enumerator which filters/maps output of another enumerator.
193 *
194 * The filter function receives the user supplied "data" followed by the
195 * original enumerator, followed by the arguments passed to the outer
196 * enumerator. It returns TRUE to deliver the values assigned to these
197 * arguments to the caller of enumerate() and FALSE to end the enumeration.
198 * Filtering items is simple as the filter function may just skip enumerated
199 * items from the original enumerator.
200 *
201 * @param orig original enumerator to wrap, gets destroyed
202 * @param filter filter function
203 * @param data user data to supply to filter
204 * @param destructor destructor function to clean up data after use
205 * @return the filtered enumerator
206 */
207 enumerator_t *enumerator_create_filter(enumerator_t *orig,
208 bool (*filter)(void *data, enumerator_t *orig, va_list args),
209 void *data, void (*destructor)(void *data));
210
211 /**
212 * Create an enumerator wrapper which does a cleanup on destroy.
213 *
214 * @param wrapped wrapped enumerator
215 * @param cleanup cleanup function called on destroy
216 * @param data user data to supply to cleanup
217 * @return the enumerator with cleanup
218 */
219 enumerator_t *enumerator_create_cleaner(enumerator_t *wrapped,
220 void (*cleanup)(void *data), void *data);
221
222 #endif /** ENUMERATOR_H_ @}*/