113d642608a678e32320f26fd74b9b7a4891f022
[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 Inserts a new item at the beginning of the list.
70 *
71 * @param linked_list calling object
72 * @param[in] item item value to insert in list
73 */
74 void (*insert_first) (linked_list_t *linked_list, void *item);
75
76 /**
77 * @brief Removes the first item in the list and returns its value.
78 *
79 * @param linked_list calling object
80 * @param[out] item returned value of first item
81 * @return
82 * - SUCCESS
83 * - NOT_FOUND, if list is empty
84 */
85 status_t (*remove_first) (linked_list_t *linked_list, void **item);
86
87 /**
88 * @brief Returns the value of the first list item without removing it.
89 *
90 * @param linked_list calling object
91 * @param[out] item item returned value of first item
92 * @return
93 * - SUCCESS
94 * - NOT_FOUND, if list is empty
95 */
96 status_t (*get_first) (linked_list_t *linked_list, void **item);
97
98 /**
99 * @brief Inserts a new item at the end of the list.
100 *
101 * @param linked_list calling object
102 * @param[in] item item value to insert into list
103 */
104 void (*insert_last) (linked_list_t *linked_list, void *item);
105
106 /**
107 * @brief Inserts a new item at a given position in the list.
108 *
109 * @param linked_list calling object
110 * @param position position starting at 0 to insert new entry
111 * @param[in] item item value to insert into list
112 * @return
113 * - SUCCESS
114 * - INVALID_ARG if position not existing
115 */
116 status_t (*insert_at_position) (linked_list_t *linked_list,size_t position, void *item);
117
118 /**
119 * @brief Removes an item from a given position in the list.
120 *
121 * @param linked_list calling object
122 * @param position position starting at 0 to remove entry from
123 * @param[out] item removed item will be stored at this location
124 * @return
125 * - SUCCESS
126 * - INVALID_ARG if position not existing
127 */
128 status_t (*remove_at_position) (linked_list_t *linked_list,size_t position, void **item);
129
130 /**
131 * @brief Get an item from a given position in the list.
132 *
133 * @param linked_list calling object
134 * @param position position starting at 0 to get entry from
135 * @param[out] item item will be stored at this location
136 * @return
137 * - SUCCESS
138 * - INVALID_ARG if position not existing
139 */
140 status_t (*get_at_position) (linked_list_t *linked_list,size_t position, void **item);
141
142 /**
143 * @brief Removes the last item in the list and returns its value.
144 *
145 * @param linked_list calling object
146 * @param[out] item item returned value of last item
147 * @return
148 * - SUCCESS
149 * - NOT_FOUND if list is empty
150 */
151 status_t (*remove_last) (linked_list_t *linked_list, void **item);
152
153 /**
154 * @brief Returns the value of the last list item without removing it.
155 *
156 * @param linked_list calling object
157 * @param[out] item item returned value of last item
158 * @return
159 * - SUCCESS
160 * - NOT_FOUND if list is empty
161 */
162 status_t (*get_last) (linked_list_t *linked_list, void **item);
163
164 /**
165 * @brief Destroys a linked_list object.
166 *
167 * @warning All items are removed before deleting the list. The
168 * associated values are NOT destroyed.
169 * Destroying an list which is not empty may cause
170 * memory leaks!
171 *
172 * @param linked_list calling object
173 */
174 void (*destroy) (linked_list_t *linked_list);
175 };
176
177 /**
178 * @brief Creates an empty linked list object.
179 *
180 * @return linked_list_t object.
181 *
182 * @ingroup utils
183 */
184 linked_list_t *linked_list_create();
185
186
187 #endif /*LINKED_LIST_H_*/