botan: Add support for Ed25519 keys
[strongswan.git] / src / libstrongswan / collections / linked_list.h
1 /*
2 * Copyright (C) 2007-2018 Tobias Brunner
3 * Copyright (C) 2005-2008 Martin Willi
4 * Copyright (C) 2005 Jan Hutter
5 * HSR 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
18 /**
19 * @defgroup linked_list linked_list
20 * @{ @ingroup collections
21 */
22
23 #ifndef LINKED_LIST_H_
24 #define LINKED_LIST_H_
25
26 typedef struct linked_list_t linked_list_t;
27
28 #include <collections/enumerator.h>
29
30 /**
31 * Function to match elements in a linked list
32 *
33 * @param item current list item
34 * @param args user supplied data
35 * @return TRUE, if the item matched, FALSE otherwise
36 */
37 typedef bool (*linked_list_match_t)(void *item, va_list args);
38
39 /**
40 * Helper function to match a string in a linked list of strings
41 *
42 * @param item list item (char*)
43 * @param args user supplied data (char*)
44 * @return
45 */
46 bool linked_list_match_str(void *item, va_list args);
47
48 /**
49 * Function to be invoked on elements in a linked list
50 *
51 * @param item current list item
52 * @param args user supplied data
53 */
54 typedef void (*linked_list_invoke_t)(void *item, va_list args);
55
56 /**
57 * Class implementing a double linked list.
58 *
59 * General purpose linked list. This list is not synchronized.
60 */
61 struct linked_list_t {
62
63 /**
64 * Gets the count of items in the list.
65 *
66 * @return number of items in list
67 */
68 int (*get_count) (linked_list_t *this);
69
70 /**
71 * Create an enumerator over the list.
72 *
73 * @note The enumerator's position is invalid before the first call
74 * to enumerate().
75 *
76 * @return enumerator over list items
77 */
78 enumerator_t* (*create_enumerator)(linked_list_t *this);
79
80 /**
81 * Resets the enumerator's current position to the beginning of the list.
82 *
83 * @param enumerator enumerator to reset
84 */
85 void (*reset_enumerator)(linked_list_t *this, enumerator_t *enumerator);
86
87 /**
88 * Inserts a new item at the beginning of the list.
89 *
90 * @param item item value to insert in list
91 */
92 void (*insert_first) (linked_list_t *this, void *item);
93
94 /**
95 * Removes the first item in the list and returns its value.
96 *
97 * @param item returned value of first item, or NULL
98 * @return SUCCESS, or NOT_FOUND if list is empty
99 */
100 status_t (*remove_first) (linked_list_t *this, void **item);
101
102 /**
103 * Inserts a new item before the item the enumerator currently points to.
104 *
105 * If this method is called after all items have been enumerated, the item
106 * is inserted last. This is helpful when inserting items into a sorted
107 * list.
108 *
109 * @note The position of the enumerator is not changed. So it is safe to
110 * call this before or after remove_at() to replace the item at the current
111 * position (the enumerator will continue with the next item in the list).
112 * And in particular, when inserting an item before calling enumerate(),
113 * the enumeration will continue (or start) at the item that was first in
114 * the list before any items were inserted (enumerate() will return FALSE
115 * if the list was empty before).
116 *
117 * @param enumerator enumerator with position
118 * @param item item value to insert in list
119 */
120 void (*insert_before)(linked_list_t *this, enumerator_t *enumerator,
121 void *item);
122
123 /**
124 * Remove an item from the list where the enumerator points to.
125 *
126 * If this method is called before calling enumerate() of the enumerator,
127 * the first item in the list, if any, will be removed. No item is removed,
128 * if the method is called after enumerating all items.
129 *
130 * @param enumerator enumerator with position
131 */
132 void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
133
134 /**
135 * Remove items from the list matching the given item.
136 *
137 * If a compare function is given, it is called for each item, with the
138 * first parameter being the current list item and the second parameter
139 * being the supplied item. Return TRUE from the compare function to remove
140 * the item, return FALSE to keep it in the list.
141 *
142 * If compare is NULL, comparison is done by pointers.
143 *
144 * @param item item to remove/pass to comparator
145 * @param compare compare function, or NULL
146 * @return number of removed items
147 */
148 int (*remove)(linked_list_t *this, void *item, bool (*compare)(void*,void*));
149
150 /**
151 * Returns the value of the first list item without removing it.
152 *
153 * @param item returned value of first item
154 * @return SUCCESS, NOT_FOUND if list is empty
155 */
156 status_t (*get_first) (linked_list_t *this, void **item);
157
158 /**
159 * Inserts a new item at the end of the list.
160 *
161 * @param item value to insert into list
162 */
163 void (*insert_last) (linked_list_t *this, void *item);
164
165 /**
166 * Removes the last item in the list and returns its value.
167 *
168 * @param item returned value of last item, or NULL
169 * @return SUCCESS, NOT_FOUND if list is empty
170 */
171 status_t (*remove_last) (linked_list_t *this, void **item);
172
173 /**
174 * Returns the value of the last list item without removing it.
175 *
176 * @param item returned value of last item
177 * @return SUCCESS, NOT_FOUND if list is empty
178 */
179 status_t (*get_last) (linked_list_t *this, void **item);
180
181 /**
182 * Find the first matching element in the list.
183 *
184 * The first object passed to the match function is the current list item,
185 * followed by the user supplied data.
186 * If the supplied function returns TRUE so does this function, and the
187 * current object is returned in the third parameter (if given), otherwise,
188 * the next item is checked.
189 *
190 * If match is NULL, *item and the current object are compared.
191 *
192 * @param match comparison function to call on each object, or NULL
193 * @param item the list item, if found, or NULL
194 * @param ... user data to supply to match function
195 * @return TRUE if found, FALSE otherwise (or if neither match,
196 * nor item is supplied)
197 */
198 bool (*find_first)(linked_list_t *this, linked_list_match_t match,
199 void **item, ...);
200
201 /**
202 * Invoke a method on all of the contained objects.
203 *
204 * If a linked list contains objects with function pointers,
205 * invoke() can call a method on each of the objects. The
206 * method is specified by an offset of the function pointer,
207 * which can be evaluated at compile time using the offsetof
208 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
209 *
210 * @param offset offset of the method to invoke on objects
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 function to call for each object
218 * @param ... user data to supply to called function
219 */
220 void (*invoke_function)(linked_list_t *this, linked_list_invoke_t function,
221 ...);
222
223 /**
224 * Clones a list and its objects using the objects' clone method.
225 *
226 * @param offset offset to the objects clone function
227 * @return cloned list
228 */
229 linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
230
231 /**
232 * Compare two lists and their objects for equality using the given equals
233 * method.
234 *
235 * @param other list to compare
236 * @param offset offset of the objects equals method
237 * @return TRUE if lists and objects are equal, FALSE otherwise
238 */
239 bool (*equals_offset) (linked_list_t *this, linked_list_t *other,
240 size_t offset);
241
242 /**
243 * Compare two lists and their objects for equality using the given function.
244 *
245 * @param other list to compare
246 * @param function function to compare the objects
247 * @return TRUE if lists and objects are equal, FALSE otherwise
248 */
249 bool (*equals_function) (linked_list_t *this, linked_list_t *other,
250 bool (*)(void*,void*));
251
252 /**
253 * Destroys a linked_list object.
254 */
255 void (*destroy) (linked_list_t *this);
256
257 /**
258 * Destroys a list and its objects using the destructor.
259 *
260 * If a linked list and the contained objects should be destroyed, use
261 * destroy_offset. The supplied offset specifies the destructor to
262 * call on each object. The offset may be calculated using the offsetof
263 * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
264 *
265 * @param offset offset of the objects destructor
266 */
267 void (*destroy_offset) (linked_list_t *this, size_t offset);
268
269 /**
270 * Destroys a list and its contents using a a cleanup function.
271 *
272 * If a linked list and its contents should get destroyed using a specific
273 * cleanup function, use destroy_function. This is useful when the
274 * list contains malloc()-ed blocks which should get freed,
275 * e.g.: list->destroy_function(list, free);
276 *
277 * @param function function to call on each object
278 */
279 void (*destroy_function) (linked_list_t *this, void (*)(void*));
280 };
281
282 /**
283 * Creates an empty linked list object.
284 *
285 * @return linked_list_t object.
286 */
287 linked_list_t *linked_list_create(void);
288
289 /**
290 * Creates a linked list from an enumerator.
291 *
292 * @param enumerator enumerator over void*, gets destroyed
293 * @return linked_list_t object, containing enumerated values
294 */
295 linked_list_t *linked_list_create_from_enumerator(enumerator_t *enumerator);
296
297 /**
298 * Creates a linked list from a NULL terminated vararg list of items.
299 *
300 * @param first first item
301 * @param ... subsequent items, terminated by NULL
302 * @return linked_list_t object, containing passed items
303 */
304 linked_list_t *linked_list_create_with_items(void *first, ...);
305
306 #endif /** LINKED_LIST_H_ @}*/