implemented more flexible iterator hook API
[strongswan.git] / src / libstrongswan / utils / iterator.h
1 /**
2 * @file iterator.h
3 *
4 * @brief Interface iterator_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef ITERATOR_H_
25 #define ITERATOR_H_
26
27 #include <library.h>
28
29 typedef enum hook_result_t hook_result_t;
30
31 /**
32 * @brief Return value of an iterator hook.
33 *
34 * Returning HOOK_AGAIN is useful to "inject" additional elements in an
35 * iteration, HOOK_NEXT is the normal iterator behavior, and HOOK_SKIP may
36 * be used to filter elements out.
37 *
38 * @ingroup utils
39 */
40 enum hook_result_t {
41
42 /**
43 * A value was placed in out, hook is called again with the same "in"
44 */
45 HOOK_AGAIN,
46
47 /**
48 * A value was placed in out, hook is called again with next "in" (if any)
49 */
50 HOOK_NEXT,
51
52 /**
53 * No value in out, call again with next "in" (if any)
54 */
55 HOOK_SKIP,
56 };
57
58 /**
59 * @brief Iterator hook function prototype.
60 *
61 * @param param user supplied parameter
62 * @param in the value the hook receives from the iterator
63 * @param out the value supplied as a result to the iterator
64 * @return a hook_result_t
65 *
66 * @ingroup utils
67 */
68 typedef hook_result_t (iterator_hook_t)(void *param, void *in, void **out);
69
70
71 typedef struct iterator_t iterator_t;
72
73 /**
74 * @brief Iterator interface, allows iteration over collections.
75 *
76 * iterator_t defines an interface for iterating over collections.
77 * It allows searching, deleting, updating and inserting.
78 *
79 * @b Constructors:
80 * - via linked_list_t.create_iterator, or
81 * - any other class which supports the iterator_t interface
82 *
83 * @see linked_list_t
84 *
85 * @ingroup utils
86 */
87 struct iterator_t {
88
89 /**
90 * @brief Return number of list items.
91 *
92 * @param this calling object
93 * @return number of list items
94 */
95 int (*get_count) (iterator_t *this);
96
97 /**
98 * @brief Iterate over all items.
99 *
100 * The easy way to iterate over items.
101 *
102 * @param this calling object
103 * @param[out] value item
104 * @return
105 * - TRUE, if there was an element available,
106 * - FALSE otherwise
107 */
108 bool (*iterate) (iterator_t *this, void** value);
109
110 /**
111 * @brief Hook a function into the iterator.
112 *
113 * Sometimes it is useful to hook in an iterator. The hook function is
114 * called before any successful return of iterate(). It takes the
115 * iterator value, may manipulate it (or the references object), and returns
116 * the value that the iterate() function returns. Depending on the hook
117 * return value, the hook is called again, called with next, or skipped.
118 * A value of NULL deactivates the iterator hook.
119 * If an iterator is hooked, only the iterate() method is valid,
120 * all other methods behave undefined.
121 *
122 * @param this calling object
123 * @param hook iterator hook which manipulates the iterated value
124 * @param param user supplied parameter to pass back to the hook
125 */
126 void (*set_iterator_hook) (iterator_t *this, iterator_hook_t *hook,
127 void *param);
128
129 /**
130 * @brief Inserts a new item before the given iterator position.
131 *
132 * The iterator position is not changed after inserting
133 *
134 * @param this calling iterator
135 * @param[in] item value to insert in list
136 */
137 void (*insert_before) (iterator_t *this, void *item);
138
139 /**
140 * @brief Inserts a new item after the given iterator position.
141 *
142 * The iterator position is not changed after inserting.
143 *
144 * @param this calling iterator
145 * @param[in] item value to insert in list
146 */
147 void (*insert_after) (iterator_t *this, void *item);
148
149 /**
150 * @brief Replace the current item at current iterator position.
151 *
152 * The iterator position is not changed after replacing.
153 *
154 * @param this calling iterator
155 * @param[out] old_item old value will be written here(can be NULL)
156 * @param[in] new_item new value
157 *
158 * @return
159 * - SUCCESS
160 * - FAILED if iterator is on an invalid position
161 */
162 status_t (*replace) (iterator_t *this, void **old_item, void *new_item);
163
164 /**
165 * @brief Removes an element from list at the given iterator position.
166 *
167 * The iterator is set the the following position:
168 * - to the item before, if available
169 * - it gets reseted, otherwise
170 *
171 * @param this calling object
172 * @return
173 * - SUCCESS
174 * - FAILED if iterator is on an invalid position
175 */
176 status_t (*remove) (iterator_t *this);
177
178 /**
179 * @brief Resets the iterator position.
180 *
181 * After reset, the iterator_t objects doesn't point to an element.
182 * A call to iterator_t.has_next is necessary to do any other operations
183 * with the resetted iterator.
184 *
185 * @param this calling object
186 */
187 void (*reset) (iterator_t *this);
188
189 /**
190 * @brief Destroys an iterator.
191 *
192 * @param this iterator to destroy
193 *
194 */
195 void (*destroy) (iterator_t *this);
196 };
197
198 #endif /*ITERATOR_H_*/