Moved data structures to new collections subfolder
[strongswan.git] / src / libstrongswan / collections / 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
16 /**
17 * @defgroup enumerator enumerator
18 * @{ @ingroup collections
19 */
20
21 #ifndef ENUMERATOR_H_
22 #define ENUMERATOR_H_
23
24 typedef struct enumerator_t enumerator_t;
25
26 #include "../utils.h"
27
28 /**
29 * Enumerator interface, allows enumeration over collections.
30 */
31 struct enumerator_t {
32
33 /**
34 * Enumerate collection.
35 *
36 * The enumerate function takes a variable argument list containing
37 * pointers where the enumerated values get written.
38 *
39 * @param ... variable list of enumerated items, implementation dependent
40 * @return TRUE if pointers returned
41 */
42 bool (*enumerate)(enumerator_t *this, ...);
43
44 /**
45 * Destroy a enumerator instance.
46 */
47 void (*destroy)(enumerator_t *this);
48 };
49
50 /**
51 * Create an enumerator which enumerates over nothing
52 *
53 * @return an enumerator over no values
54 */
55 enumerator_t* enumerator_create_empty();
56
57 /**
58 * Create an enumerator which enumerates over a single item
59 *
60 * @param item item to enumerate
61 * @param cleanup cleanup function called on destroy with the item
62 * @return an enumerator over a single value
63 */
64 enumerator_t *enumerator_create_single(void *item, void (*cleanup)(void *item));
65
66 /**
67 * Create an enumerator over files/subdirectories in a directory.
68 *
69 * This enumerator_t.enumerate() function returns a (to the directory) relative
70 * filename (as a char*), an absolute filename (as a char*) and a file status
71 * (to a struct stat), which all may be NULL. "." and ".." entries are
72 * skipped. Example:
73 *
74 * @code
75 char *rel, *abs;
76 struct stat st;
77 enumerator_t *e;
78
79 e = enumerator_create_directory("/tmp");
80 if (e)
81 {
82 while (e->enumerate(e, &rel, &abs, &st))
83 {
84 if (S_ISDIR(st.st_mode) && *rel != '.')
85 {
86 printf("%s\n", abs);
87 }
88 }
89 e->destroy(e);
90 }
91 @endcode
92 *
93 * @param path path of the directory
94 * @return the directory enumerator, NULL on failure
95 */
96 enumerator_t* enumerator_create_directory(const char *path);
97
98 /**
99 * Create an enumerator over tokens of a string.
100 *
101 * Tokens are separated by one of the characters in sep and trimmed by the
102 * characters in trim.
103 *
104 * @param string string to parse
105 * @param sep separator characters
106 * @param trim characters to trim from tokens
107 * @return enumerator over char* tokens
108 */
109 enumerator_t* enumerator_create_token(const char *string, const char *sep,
110 const char *trim);
111
112 /**
113 * Creates an enumerator which enumerates over enumerated enumerators :-).
114 *
115 * The variable argument list of enumeration values is limit to 5.
116 *
117 * @param outer outer enumerator
118 * @param inner_constructor constructor to inner enumerator
119 * @param data data to pass to each inner_constructor call
120 * @param destroy_data destructor to pass to data
121 * @return the nested enumerator
122 */
123 enumerator_t *enumerator_create_nested(enumerator_t *outer,
124 enumerator_t *(*inner_constructor)(void *outer, void *data),
125 void *data, void (*destroy_data)(void *data));
126
127 /**
128 * Creates an enumerator which filters output of another enumerator.
129 *
130 * The filter function receives the user supplied "data" followed by a
131 * unfiltered enumeration item, followed by an output pointer where to write
132 * the filtered data. Then the next input/output pair follows.
133 * It returns TRUE to deliver the
134 * values to the caller of enumerate(), FALSE to filter this enumeration.
135 *
136 * The variable argument list of enumeration values is limit to 5.
137 *
138 * @param unfiltered unfiltered enumerator to wrap, gets destroyed
139 * @param filter filter function
140 * @param data user data to supply to filter
141 * @param destructor destructor function to clean up data after use
142 * @return the filtered enumerator
143 */
144 enumerator_t *enumerator_create_filter(enumerator_t *unfiltered,
145 bool (*filter)(void *data, ...),
146 void *data, void (*destructor)(void *data));
147
148 /**
149 * Create an enumerator wrapper which does a cleanup on destroy.
150 *
151 * @param wrapped wrapped enumerator
152 * @param cleanup cleanup function called on destroy
153 * @param data user data to supply to cleanup
154 * @return the enumerator with cleanup
155 */
156 enumerator_t *enumerator_create_cleaner(enumerator_t *wrapped,
157 void (*cleanup)(void *data), void *data);
158
159 #endif /** ENUMERATOR_H_ @}*/