updated Doxyfile
[strongswan.git] / src / libstrongswan / utils / linked_list.h
1 /*
2 * Copyright (C) 2007-2008 Tobias Brunner
3 * Copyright (C) 2005-2008 Martin Willi
4 * Copyright (C) 2005 Jan Hutter
5 * Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 *
17 * $Id$
18 */
19
20 /**
21 * @defgroup linked_list linked_list
22 * @{ @ingroup utils
23 */
24
25 #ifndef LINKED_LIST_H_
26 #define LINKED_LIST_H_
27
28 typedef struct linked_list_t linked_list_t;
29
30 #include <library.h>
31 #include <utils/iterator.h>
32 #include <utils/enumerator.h>
33
34 /**
35 * Method to match elements in a linked list (used in find_* functions)
36 *
37 * @param item current list item
38 * @param ... user supplied data (only pointers, at most 5)
39 * @return
40 * - TRUE, if the item matched
41 * - FALSE, otherwise
42 */
43 typedef bool (*linked_list_match_t)(void *item, ...);
44
45 /**
46 * Method to be invoked on elements in a linked list (used in invoke_* functions)
47 *
48 * @param item current list item
49 * @param ... user supplied data (only pointers, at most 5)
50 */
51 typedef void (*linked_list_invoke_t)(void *item, ...);
52
53 /**
54 * Class implementing a double linked list.
55 *
56 * General purpose linked list. This list is not synchronized.
57 */
58 struct linked_list_t {
59
60 /**
61 * Gets the count of items in the list.
62 *
63 * @return number of items in list
64 */
65 int (*get_count) (linked_list_t *this);
66
67 /**
68 * Creates a iterator for the given list.
69 *
70 * @warning Created iterator_t object has to get destroyed by the caller.
71 *
72 * @deprecated Iterator is obsolete and will disappear, it is too
73 * complicated to implement. Use enumerator instead.
74 *
75 * @param forward iterator direction (TRUE: front to end)
76 * @return new iterator_t object
77 */
78 iterator_t *(*create_iterator) (linked_list_t *this, bool forward);
79
80 /**
81 * Create an enumerator over the list.
82 *
83 * The enumerator is a "lightweight" iterator. It only has two methods
84 * and should therefore be much easier to implement.
85 *
86 * @return enumerator over list items
87 */
88 enumerator_t* (*create_enumerator)(linked_list_t *this);
89
90 /**
91 * Inserts a new item at the beginning of the list.
92 *
93 * @param item item value to insert in list
94 */
95 void (*insert_first) (linked_list_t *this, void *item);
96
97 /**
98 * Removes the first item in the list and returns its value.
99 *
100 * @param item returned value of first item, or NULL
101 * @return SUCCESS, or NOT_FOUND if list is empty
102 */
103 status_t (*remove_first) (linked_list_t *this, void **item);
104
105 /**
106 * Remove an item from the list where the enumerator points to.
107 *
108 * @param enumerator enumerator with position
109 */
110 void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
111
112 /**
113 * Remove items from the list matching item.
114 *
115 * If a compare function is given, it is called for each item, where
116 * the first parameter is the current list item and the second parameter
117 * is the supplied item parameter.
118 * If compare is NULL, compare is done by pointer.
119 *
120 * @param item item to remove/pass to comparator
121 * @param compare compare function, or NULL
122 * @return number of removed items
123 */
124 int (*remove)(linked_list_t *this, void *item, bool (*compare)(void *,void*));
125
126 /**
127 * Returns the value of the first list item without removing it.
128 *
129 * @param this calling object
130 * @param item returned value of first item
131 * @return SUCCESS, NOT_FOUND if list is empty
132 */
133 status_t (*get_first) (linked_list_t *this, void **item);
134
135 /**
136 * Inserts a new item at the end of the list.
137 *
138 * @param item value to insert into list
139 */
140 void (*insert_last) (linked_list_t *this, void *item);
141
142 /**
143 * Removes the last item in the list and returns its value.
144 *
145 * @param this calling object
146 * @param item returned value of last item, or NULL
147 * @return SUCCESS, NOT_FOUND if list is empty
148 */
149 status_t (*remove_last) (linked_list_t *this, void **item);
150
151 /**
152 * Returns the value of the last list item without removing it.
153 *
154 * @param this calling object
155 * @param item returned value of last item
156 * @return SUCCESS, NOT_FOUND if list is empty
157 */
158 status_t (*get_last) (linked_list_t *this, void **item);
159
160 /** Find the first matching element in the list.
161 *
162 * The first object passed to the match function is the current list item,
163 * followed by the user supplied data.
164 * If the supplied function returns TRUE this function returns SUCCESS, and
165 * the current object is returned in the third parameter, otherwise,
166 * the next item is checked.
167 *
168 * If match is NULL, *item and the current object are compared.
169 *
170 * @warning Only use pointers as user supplied data.
171 *
172 * @param match comparison function to call on each object, or NULL
173 * @param item the list item, if found
174 * @param ... user data to supply to match function (limited to 5 arguments)
175 * @return SUCCESS if found, NOT_FOUND otherwise
176 */
177 status_t (*find_first) (linked_list_t *this, linked_list_match_t match,
178 void **item, ...);
179
180 /** Find the last matching element in the list.
181 *
182 * The first object passed to the match function is the current list item,
183 * followed by the user supplied data.
184 * If the supplied function returns TRUE this function returns SUCCESS, and
185 * the current object is returned in the third parameter, otherwise,
186 * the next item is checked.
187 *
188 * If match is NULL, *item and the current object are compared.
189 *
190 * @warning Only use pointers as user supplied data.
191 *
192 * @param match comparison function to call on each object, or NULL
193 * @param item the list item, if found
194 * @param ... user data to supply to match function (limited to 5 arguments)
195 * @return SUCCESS if found, NOT_FOUND otherwise
196 */
197 status_t (*find_last) (linked_list_t *this, linked_list_match_t match,
198 void **item, ...);
199
200 /**
201 * Invoke a method on all of the contained objects.
202 *
203 * If a linked list contains objects with function pointers,
204 * invoke() can call a method on each of the objects. The
205 * method is specified by an offset of the function pointer,
206 * which can be evalutated at compile time using the offsetof
207 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
208 *
209 * @param offset offset of the method to invoke on objects
210 * @param ... user data to supply to called function (limited to 5 arguments)
211 */
212 void (*invoke_offset) (linked_list_t *this, size_t offset, ...);
213
214 /**
215 * Invoke a function on all of the contained objects.
216 *
217 * @param function offset of the method to invoke on objects
218 * @param ... user data to supply to called function (limited to 5 arguments)
219 */
220 void (*invoke_function) (linked_list_t *this, linked_list_invoke_t function, ...);
221
222 /**
223 * Clones a list and its objects using the objects' clone method.
224 *
225 * @param offset offset ot the objects clone function
226 * @return cloned list
227 */
228 linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
229
230 /**
231 * Clones a list and its objects using a given function.
232 *
233 * @param function function that clones an object
234 * @return cloned list
235 */
236 linked_list_t *(*clone_function) (linked_list_t *this, void*(*)(void*));
237
238 /**
239 * Destroys a linked_list object.
240 */
241 void (*destroy) (linked_list_t *this);
242
243 /**
244 * Destroys a list and its objects using the destructor.
245 *
246 * If a linked list and the contained objects should be destroyed, use
247 * destroy_offset. The supplied offset specifies the destructor to
248 * call on each object. The offset may be calculated using the offsetof
249 * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
250 *
251 * @param offset offset of the objects destructor
252 */
253 void (*destroy_offset) (linked_list_t *this, size_t offset);
254
255 /**
256 * Destroys a list and its contents using a a cleanup function.
257 *
258 * If a linked list and its contents should get destroyed using a specific
259 * cleanup function, use destroy_function. This is useful when the
260 * list contains malloc()-ed blocks which should get freed,
261 * e.g.: list->destroy_function(list, free);
262 *
263 * @param function function to call on each object
264 */
265 void (*destroy_function) (linked_list_t *this, void (*)(void*));
266 };
267
268 /**
269 * Creates an empty linked list object.
270 *
271 * @return linked_list_t object.
272 */
273 linked_list_t *linked_list_create(void);
274
275 #endif /** LINKED_LIST_H_ @}*/