f5a87cd14c5a3a9000aeb0722992b9382cf31c2c
[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 Resets a linked_list_iterator object
80 *
81 * @param this calling object
82 * @return SUCCESS if succeeded, FAILED otherwise
83 */
84 status_t (*reset) (linked_list_iterator_t *this);
85
86 /**
87 * @brief Destroys a linked_list_iterator object
88 *
89 * @param this calling object
90 * @return SUCCESS if succeeded, FAILED otherwise
91 */
92 status_t (*destroy) (linked_list_iterator_t *this);
93 };
94
95 typedef struct linked_list_t linked_list_t;
96
97
98 /**
99 * @brief Double Linked List (named only as linked list).
100 *
101 * @warning Access to an object of this type is not thread-save
102 *
103 * @see job_queue_t
104 * @see event_queue_t
105 * @see send_queue_t
106 */
107 struct linked_list_t {
108
109 /**
110 * @brief gets the count of items in the list
111 *
112 * @param linked_list calling object
113 * @return number of items in list
114 */
115 int (*get_count) (linked_list_t *linked_list);
116
117 /**
118 * @brief creates a iterator for the given list
119 *
120 * @warning has to get destroyed
121 *
122 * @param linked_list calling object
123 * @param[out] iterator place where the iterator is written
124 * @param[in] forward iterator direction (TRUE: front to end)
125 * @return SUCCESS if succeeded, FAILED otherwise
126 */
127 status_t (*create_iterator) (linked_list_t *linked_list, linked_list_iterator_t **iterator,bool forward);
128
129 /**
130 * @brief inserts a new item at the beginning of the list
131 *
132 * @param linked_list calling object
133 * @param[in] item value to insert in list
134 * @return SUCCESS if succeeded, FAILED otherwise
135 */
136 status_t (*insert_first) (linked_list_t *linked_list, void *item);
137
138 /**
139 * @brief removes an element from list at the given iterator position
140 *
141 * The position of the iterator is set in the following order:
142 * - to the item before, if available
143 * - otherwise to the item after, if available
144 * - otherwise it gets reseted
145 *
146 * @param linked_list calling object
147 * @param iterator iterator holding the position of the element to remove
148 * @return SUCCESS if succeeded, FAILED otherwise
149 */
150 status_t (*remove) (linked_list_t *linked_list, linked_list_iterator_t *iterator);
151
152 /**
153 * @brief removes the first item in the list and returns its value
154 *
155 * @param linked_list calling object
156 * @param[in] item returned value of first item
157 * @return SUCCESS if succeeded, FAILED otherwise
158 */
159 status_t (*remove_first) (linked_list_t *linked_list, void **item);
160
161 /**
162 * @brief returns the value of the first list item without removing it
163 *
164 * @param linked_list calling object
165 * @param[out] item returned value of first item
166 * @return SUCCESS if succeeded, FAILED otherwise
167 */
168 status_t (*get_first) (linked_list_t *linked_list, void **item);
169
170 /**
171 * @brief inserts a new item at the end of the list
172 *
173 * @param linked_list calling object
174 * @param[in] item value to insert into list
175 * @return SUCCESS if succeeded, FAILED otherwise
176 */
177 status_t (*insert_last) (linked_list_t *linked_list, void *item);
178
179 /**
180 * @brief removes the last item in the list and returns its value
181 *
182 * @param linked_list calling object
183 * @param[out] item returned value of last item
184 * @return SUCCESS if succeeded, FAILED otherwise
185 */
186 status_t (*remove_last) (linked_list_t *linked_list, void **item);
187
188 /**
189 * @brief Returns the value of the last list item without removing it
190 *
191 * @param linked_list calling object
192 * @param[out] item returned value of last item
193 * @return SUCCESS if succeeded, FAILED otherwise
194 */
195 status_t (*get_last) (linked_list_t *linked_list, void **item);
196
197 /**
198 * @brief Destroys a linked_list object
199 *
200 * @warning all items are removed before deleting the list. The
201 * associated values are NOT destroyed.
202 * Destroying an list which is not empty may cause
203 * memory leaks!
204 *
205 * @param linked_list calling object
206 * @return SUCCESS if succeeded, FAILED otherwise
207 */
208 status_t (*destroy) (linked_list_t *linked_list);
209 };
210
211 /**
212 * @brief Creates an empty linked list object
213 */
214 linked_list_t *linked_list_create(void);
215
216
217 #endif /*LINKED_LIST_H_*/