- fixed alot of bugs in child_proposal
[strongswan.git] / Source / charon / utils / linked_list.h
1 /**
2 * @file linked_list.h
3 *
4 * @brief Interface of linked_list_t.
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 #include <utils/iterator.h>
28
29
30 typedef struct linked_list_t linked_list_t;
31
32 /**
33 * @brief Class implementing a double linked list (named only as linked list).
34 *
35 * @warning Access to an object of this type is not thread-save.
36 *
37 * @b Costructors:
38 * - linked_list_create()
39 *
40 * @see
41 * - job_queue_t
42 * - event_queue_t
43 * - send_queue_t
44 *
45 * @ingroup utils
46 */
47 struct linked_list_t {
48
49 /**
50 * @brief Gets the count of items in the list.
51 *
52 * @param linked_list calling object
53 * @return number of items in list
54 */
55 int (*get_count) (linked_list_t *linked_list);
56
57 /**
58 * @brief Creates a iterator for the given list.
59 *
60 * @warning Created iterator_t object has to get destroyed by the caller.
61 *
62 * @param linked_list calling object
63 * @param forward iterator direction (TRUE: front to end)
64 * @return new iterator_t object
65 */
66 iterator_t * (*create_iterator) (linked_list_t *linked_list, bool forward);
67
68 /**
69 * @brief Call a function with list element as argument.
70 *
71 * This method accepts a function, which will be called for
72 * each list element once. The function must accept the list
73 * element as the first argument. Handy for destruction of
74 * list elements.
75 *
76 * @todo Additional vararg which are passed to the
77 * function would be nice...
78 *
79 * @param linked_list calling object
80 * @param func function to call
81 */
82 void (*call_on_items) (linked_list_t *linked_list, void(*func)(void*));
83
84 /**
85 * @brief Inserts a new item at the beginning of the list.
86 *
87 * @param linked_list calling object
88 * @param[in] item item value to insert in list
89 */
90 void (*insert_first) (linked_list_t *linked_list, void *item);
91
92 /**
93 * @brief Removes the first item in the list and returns its value.
94 *
95 * @param linked_list calling object
96 * @param[out] item returned value of first item, or NULL
97 * @return
98 * - SUCCESS
99 * - NOT_FOUND, if list is empty
100 */
101 status_t (*remove_first) (linked_list_t *linked_list, void **item);
102
103 /**
104 * @brief Returns the value of the first list item without removing it.
105 *
106 * @param linked_list calling object
107 * @param[out] item item returned value of first item
108 * @return
109 * - SUCCESS
110 * - NOT_FOUND, if list is empty
111 */
112 status_t (*get_first) (linked_list_t *linked_list, void **item);
113
114 /**
115 * @brief Inserts a new item at the end of the list.
116 *
117 * @param linked_list calling object
118 * @param[in] item item value to insert into list
119 */
120 void (*insert_last) (linked_list_t *linked_list, void *item);
121
122 /**
123 * @brief Inserts a new item at a given position in the list.
124 *
125 * @param linked_list calling object
126 * @param position position starting at 0 to insert new entry
127 * @param[in] item item value to insert into list
128 * @return
129 * - SUCCESS
130 * - INVALID_ARG if position not existing
131 */
132 status_t (*insert_at_position) (linked_list_t *linked_list,size_t position, void *item);
133
134 /**
135 * @brief Removes an item from a given position in the list.
136 *
137 * @param linked_list calling object
138 * @param position position starting at 0 to remove entry from
139 * @param[out] item removed item will be stored at this location
140 * @return
141 * - SUCCESS
142 * - INVALID_ARG if position not existing
143 */
144 status_t (*remove_at_position) (linked_list_t *linked_list,size_t position, void **item);
145
146 /**
147 * @brief Get an item from a given position in the list.
148 *
149 * @param linked_list calling object
150 * @param position position starting at 0 to get entry from
151 * @param[out] item item will be stored at this location
152 * @return
153 * - SUCCESS
154 * - INVALID_ARG if position not existing
155 */
156 status_t (*get_at_position) (linked_list_t *linked_list,size_t position, void **item);
157
158 /**
159 * @brief Removes the last item in the list and returns its value.
160 *
161 * @param linked_list calling object
162 * @param[out] item returned value of last item, or NULL
163 * @return
164 * - SUCCESS
165 * - NOT_FOUND if list is empty
166 */
167 status_t (*remove_last) (linked_list_t *linked_list, void **item);
168
169 /**
170 * @brief Returns the value of the last list item without removing it.
171 *
172 * @param linked_list calling object
173 * @param[out] item returned value of last item
174 * @return
175 * - SUCCESS
176 * - NOT_FOUND if list is empty
177 */
178 status_t (*get_last) (linked_list_t *linked_list, void **item);
179
180 /**
181 * @brief Destroys a linked_list object.
182 *
183 * @warning All items are removed before deleting the list. The
184 * associated values are NOT destroyed.
185 * Destroying an list which is not empty may cause
186 * memory leaks!
187 *
188 * @param linked_list calling object
189 */
190 void (*destroy) (linked_list_t *linked_list);
191 };
192
193 /**
194 * @brief Creates an empty linked list object.
195 *
196 * @return linked_list_t object.
197 *
198 * @ingroup utils
199 */
200 linked_list_t *linked_list_create();
201
202
203 #endif /*LINKED_LIST_H_*/