- moved remove-method to iterator
[strongswan.git] / Source / charon / utils / linked_list.h
1 /**
2 * @file linked_list.h
3 *
4 * @brief Generic Double Linked List
5 *
6 */
7
8 /*
9 * Copyright (C) 2005 Jan Hutter, Martin Willi
10 * Hochschule fuer Technik Rapperswil
11 *
12 * This program is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU General Public License as published by the
14 * Free Software Foundation; either version 2 of the License, or (at your
15 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
19 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * for more details.
21 */
22
23 #ifndef LINKED_LIST_H_
24 #define LINKED_LIST_H_
25
26 #include <types.h>
27
28 typedef struct linked_list_iterator_t linked_list_iterator_t;
29
30 /**
31 * @brief Iterator for a linked list.
32 *
33 * This element holds a pointer to the current element in the linked list
34 *
35 * @warning the iterator is NOT thread-save
36 */
37 struct linked_list_iterator_t {
38
39 /**
40 * @brief returns TRUE if more elements are available
41 *
42 * @param this calling object
43 * @return if more elements are avaiable TRUE, FALSE otherwise
44 */
45 bool (*has_next) (linked_list_iterator_t *this);
46
47 /**
48 * @brief returns the current value at the iterator position
49 *
50 * @param this calling object
51 * @param[out] value value is set to the current value at iterator position
52 * @return SUCCESS if succeeded, FAILED otherwise
53 */
54 status_t (*current) (linked_list_iterator_t *this, void **value);
55
56 /**
57 * @brief inserts a new item before the given iterator position
58 *
59 * The iterator position is not changed after inserting
60 *
61 * @param this calling iterator
62 * @param[in] item value to insert in list
63 * @return SUCCESS if succeeded, FAILED otherwise
64 */
65 status_t (*insert_before) (linked_list_iterator_t *this, void *item);
66
67 /**
68 * @brief inserts a new item after the given iterator position
69 *
70 * The iterator position is not changed after inserting
71 *
72 * @param this calling iterator
73 * @param[in] item value to insert in list
74 * @return SUCCESS if succeeded, FAILED otherwise
75 */
76 status_t (*insert_after) (linked_list_iterator_t *this, void *item);
77
78 /**
79 * @brief removes an element from list at the given iterator position.
80 *
81 * The position of the iterator is set in the following order:
82 * - to the item before, if available
83 * - otherwise to the item after, if available
84 * - otherwise it gets reseted
85 *
86 * @param linked_list calling object
87 * @param iterator iterator holding the position of the element to remove
88 * @return SUCCESS if succeeded, FAILED otherwise
89 */
90 status_t (*remove) (linked_list_iterator_t *iterator);
91 /**
92 * @brief Resets a linked_list_iterator object
93 *
94 * @param this calling object
95 * @return SUCCESS if succeeded, FAILED otherwise
96 */
97 status_t (*reset) (linked_list_iterator_t *this);
98
99 /**
100 * @brief Destroys a linked_list_iterator object
101 *
102 * @param this calling object
103 * @return SUCCESS if succeeded, FAILED otherwise
104 */
105 status_t (*destroy) (linked_list_iterator_t *this);
106 };
107
108 typedef struct linked_list_t linked_list_t;
109
110
111 /**
112 * @brief Double Linked List (named only as linked list).
113 *
114 * @warning Access to an object of this type is not thread-save
115 *
116 * @see job_queue_t
117 * @see event_queue_t
118 * @see send_queue_t
119 */
120 struct linked_list_t {
121
122 /**
123 * @brief gets the count of items in the list
124 *
125 * @param linked_list calling object
126 * @return number of items in list
127 */
128 int (*get_count) (linked_list_t *linked_list);
129
130 /**
131 * @brief creates a iterator for the given list
132 *
133 * @warning has to get destroyed
134 *
135 * @param linked_list calling object
136 * @param[out] iterator place where the iterator is written
137 * @param[in] forward iterator direction (TRUE: front to end)
138 * @return SUCCESS if succeeded, FAILED otherwise
139 */
140 status_t (*create_iterator) (linked_list_t *linked_list, linked_list_iterator_t **iterator,bool forward);
141
142 /**
143 * @brief inserts a new item at the beginning of the list
144 *
145 * @param linked_list calling object
146 * @param[in] item value to insert in list
147 * @return SUCCESS if succeeded, FAILED otherwise
148 */
149 status_t (*insert_first) (linked_list_t *linked_list, void *item);
150
151 /**
152 * @brief removes the first item in the list and returns its value
153 *
154 * @param linked_list calling object
155 * @param[in] item returned value of first item
156 * @return SUCCESS if succeeded, FAILED otherwise
157 */
158 status_t (*remove_first) (linked_list_t *linked_list, void **item);
159
160 /**
161 * @brief returns the value of the first list item without removing it
162 *
163 * @param linked_list calling object
164 * @param[out] item returned value of first item
165 * @return SUCCESS if succeeded, FAILED otherwise
166 */
167 status_t (*get_first) (linked_list_t *linked_list, void **item);
168
169 /**
170 * @brief inserts a new item at the end of the list
171 *
172 * @param linked_list calling object
173 * @param[in] item value to insert into list
174 * @return SUCCESS if succeeded, FAILED otherwise
175 */
176 status_t (*insert_last) (linked_list_t *linked_list, void *item);
177
178 /**
179 * @brief removes the last item in the list and returns its value
180 *
181 * @param linked_list calling object
182 * @param[out] item returned value of last item
183 * @return SUCCESS if succeeded, FAILED otherwise
184 */
185 status_t (*remove_last) (linked_list_t *linked_list, void **item);
186
187 /**
188 * @brief Returns the value of the last list item without removing it
189 *
190 * @param linked_list calling object
191 * @param[out] item returned value of last item
192 * @return SUCCESS if succeeded, FAILED otherwise
193 */
194 status_t (*get_last) (linked_list_t *linked_list, void **item);
195
196 /**
197 * @brief Destroys a linked_list object
198 *
199 * @warning all items are removed before deleting the list. The
200 * associated values are NOT destroyed.
201 * Destroying an list which is not empty may cause
202 * memory leaks!
203 *
204 * @param linked_list calling object
205 * @return SUCCESS if succeeded, FAILED otherwise
206 */
207 status_t (*destroy) (linked_list_t *linked_list);
208 };
209
210 /**
211 * @brief Creates an empty linked list object
212 */
213 linked_list_t *linked_list_create(void);
214
215
216 #endif /*LINKED_LIST_H_*/