fixed typo
[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 /**
30 * @brief Iterator hook function prototype.
31 *
32 * @param param user supplied parameter
33 * @param in the value the hook receives from the iterator
34 * @param out the value supplied as a result to the iterator
35 * @return TRUE to return "out", FALSE to skip this value
36 */
37 typedef bool (iterator_hook_t)(void *param, void *in, void **out);
38
39
40 typedef struct iterator_t iterator_t;
41
42 /**
43 * @brief Iterator interface, allows iteration over collections.
44 *
45 * iterator_t defines an interface for iterating over collections.
46 * It allows searching, deleting, updating and inserting.
47 *
48 * Thanks to JMP for iterator lessons :-)
49 *
50 * @b Constructors:
51 * - via linked_list_t.create_iterator, or
52 * - any other class which supports the iterator_t interface
53 *
54 * @see linked_list_t
55 *
56 * @ingroup utils
57 */
58 struct iterator_t {
59
60 /**
61 * @brief Return number of list items.
62 *
63 * @param this calling object
64 * @return number of list items
65 */
66 int (*get_count) (iterator_t *this);
67
68 /**
69 * @brief Iterate over all items.
70 *
71 * The easy way to iterate over items.
72 *
73 * @param this calling object
74 * @param[out] value item
75 * @return
76 * - TRUE, if there was an element available,
77 * - FALSE otherwise
78 */
79 bool (*iterate) (iterator_t *this, void** value);
80
81 /**
82 * @brief Hook a function into the iterator.
83 *
84 * Sometimes it is useful to hook in an iterator. The hook function is
85 * called before any successful return of iterate(). It takes the
86 * iterator value, may manipulate it (or the references object), and returns
87 * the value that the iterate() function returns.
88 * A value of NULL deactivates the iterator hook.
89 *
90 * @param this calling object
91 * @param hook iterator hook which manipulates the iterated value
92 * @param param user supplied parameter to pass back to the hook
93 */
94 void (*set_iterator_hook) (iterator_t *this, iterator_hook_t *hook,
95 void *param);
96
97 /**
98 * @brief Inserts a new item before the given iterator position.
99 *
100 * The iterator position is not changed after inserting
101 *
102 * @param this calling iterator
103 * @param[in] item value to insert in list
104 */
105 void (*insert_before) (iterator_t *this, void *item);
106
107 /**
108 * @brief Inserts a new item after the given iterator position.
109 *
110 * The iterator position is not changed after inserting.
111 *
112 * @param this calling iterator
113 * @param[in] item value to insert in list
114 */
115 void (*insert_after) (iterator_t *this, void *item);
116
117 /**
118 * @brief Replace the current item at current iterator position.
119 *
120 * The iterator position is not changed after replacing.
121 *
122 * @param this calling iterator
123 * @param[out] old_item old value will be written here(can be NULL)
124 * @param[in] new_item new value
125 *
126 * @return
127 * - SUCCESS
128 * - FAILED if iterator is on an invalid position
129 */
130 status_t (*replace) (iterator_t *this, void **old_item, void *new_item);
131
132 /**
133 * @brief Removes an element from list at the given iterator position.
134 *
135 * The iterator is set the the following position:
136 * - to the item before, if available
137 * - it gets reseted, otherwise
138 *
139 * @param this calling object
140 * @return
141 * - SUCCESS
142 * - FAILED if iterator is on an invalid position
143 */
144 status_t (*remove) (iterator_t *this);
145
146 /**
147 * @brief Resets the iterator position.
148 *
149 * After reset, the iterator_t objects doesn't point to an element.
150 * A call to iterator_t.has_next is necessary to do any other operations
151 * with the resetted iterator.
152 *
153 * @param this calling object
154 */
155 void (*reset) (iterator_t *this);
156
157 /**
158 * @brief Destroys an iterator.
159 *
160 * @param this iterator to destroy
161 *
162 */
163 void (*destroy) (iterator_t *this);
164 };
165
166 #endif /*ITERATOR_H_*/