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