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_constructor, 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_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to enumerator.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / collections