- iterator for linked list implemented
[strongswan.git] / Source / charon / 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 <freeswan.h>
27 #include <pluto/constants.h>
28 #include <pluto/defs.h>
29
30 #include "types.h"
31
32 /**
33 * @brief Element of the linked_list.
34 *
35 * This element holds a pointer to the value of the list item itself.
36 */
37 typedef struct linked_list_element_s linked_list_element_t;
38
39 struct linked_list_element_s {
40
41 /**
42 * value of a list item
43 */
44 void *value;
45
46 /**
47 * @brief Destroys a linked_list_element object
48 *
49 * @param linked_list_element_t calling object
50 * @returns SUCCESS if succeeded, FAILED otherwise
51 */
52 status_t (*destroy) (linked_list_element_t *this);
53 };
54
55 /**
56 * @brief Creates an empty linked list object
57 *
58 * @param[in] value value of item to be set
59 *
60 * @warning only the pointer to the value is stored
61 *
62 * @return linked_list_element object
63 */
64 linked_list_element_t *linked_list_element_create(void *value);
65
66 /**
67 * @brief Iterator for a linked list
68 *
69 * This element holds a pointer to the current element in the linked list
70 *
71 * @warning the iterator is NOT thread-save
72 */
73 typedef struct linked_list_iterator_s linked_list_iterator_t;
74
75 struct linked_list_iterator_s {
76
77 /**
78 * @brief returns TRUE if more elements are available
79 *
80 * @param this calling object
81 * @param[out] has_next if more elements are avaiable TRUE is set, FALSE otherwise
82 * @returns SUCCESS if succeeded, FAILED otherwise
83 */
84 status_t (*has_next) (linked_list_iterator_t *this, bool * has_next);
85
86 /**
87 * @brief returns the current element at the iterator position
88 *
89 * @param this calling object
90 * @param[out] element element is set to the current element in iterator
91 * @returns SUCCESS if succeeded, FAILED otherwise
92 */
93 status_t (*current) (linked_list_iterator_t *this, linked_list_element_t **element);
94
95 /**
96 * @brief Resets a linked_list_iterator object
97 *
98 * @param this calling object
99 * @returns SUCCESS if succeeded, FAILED otherwise
100 */
101 status_t (*reset) (linked_list_iterator_t *this);
102
103 /**
104 * @brief Destroys a linked_list_iterator object
105 *
106 * @param this calling object
107 * @returns SUCCESS if succeeded, FAILED otherwise
108 */
109 status_t (*destroy) (linked_list_iterator_t *this);
110 };
111
112 /**
113 * @brief Double Linked List (named only as linked list)
114 *
115 * @warning Access to an object of this type is not thread-save
116 *
117 * @see job_queue_t
118 * @see event_queue_t
119 * @see send_queue_t
120 */
121 typedef struct linked_list_s linked_list_t;
122
123
124 struct linked_list_s {
125
126 /**
127 * @brief gets the count of items in the list
128 *
129 * @param linked_list calling object
130 * @param[in] count place where the count is written
131 * @returns SUCCESS if succeeded, FAILED otherwise
132 */
133 status_t (*get_count) (linked_list_t *linked_list, int *count);
134
135 /**
136 * @brief creates a iterator for the given list
137 *
138 * @warning has to get destroyed
139 *
140 * @param linked_list calling object
141 * @param[out] iterator place where the iterator is written
142 * @param[in] forward iterator direction (TRUE: front to end)
143 * @returns SUCCESS if succeeded, FAILED otherwise
144 */
145 status_t (*create_iterator) (linked_list_t *linked_list, linked_list_iterator_t **iterator,bool forward);
146
147 /**
148 * @brief inserts a new item at the beginning of the list
149 *
150 * @param linked_list calling object
151 * @param[in] item value to insert in list
152 * @returns SUCCESS if succeeded, FAILED otherwise
153 */
154 status_t (*insert_first) (linked_list_t *linked_list, void *item);
155
156 /**
157 * @brief removes the first item in the list and returns its value
158 *
159 * @param linked_list calling object
160 * @param[in] item returned value of first item
161 * @returns SUCCESS if succeeded, FAILED otherwise
162 */
163 status_t (*remove_first) (linked_list_t *linked_list, void **item);
164
165 /**
166 * @brief returns the value of the first list item without removing it
167 *
168 * @param linked_list calling object
169 * @param[out] item returned value of first item
170 * @returns SUCCESS if succeeded, FAILED otherwise
171 */
172 status_t (*get_first) (linked_list_t *linked_list, void **item);
173
174 /**
175 * @brief inserts a new item at the end of the list
176 *
177 * @param linked_list calling object
178 * @param[in] item value to insert into list
179 * @returns SUCCESS if succeeded, FAILED otherwise
180 */
181 status_t (*insert_last) (linked_list_t *linked_list, void *item);
182
183 /**
184 * @brief removes the last item in the list and returns its value
185 *
186 * @param linked_list calling object
187 * @param[out] item returned value of last item
188 * @returns SUCCESS if succeeded, FAILED otherwise
189 */
190 status_t (*remove_last) (linked_list_t *linked_list, void **item);
191
192 /**
193 * @brief Returns the value of the last list item without removing it
194 *
195 * @param linked_list calling object
196 * @param[out] item returned value of last item
197 * @returns SUCCESS if succeeded, FAILED otherwise
198 */
199 status_t (*get_last) (linked_list_t *linked_list, void **item);
200
201 /**
202 * @brief Destroys a linked_list object
203 *
204 * @warning all items are removed before deleting the list. The
205 * associated values are NOT destroyed.
206 * Destroying an list which is not empty may cause
207 * memory leaks!
208 *
209 * @param linked_list calling object
210 * @returns SUCCESS if succeeded, FAILED otherwise
211 */
212 status_t (*destroy) (linked_list_t *linked_list);
213 };
214
215 /**
216 * @brief Creates an empty linked list object
217 */
218 linked_list_t *linked_list_create(void);
219
220
221 #endif /*LINKED_LIST_H_*/