bfaf16034ff63b54fdc88c8bff9f913b06d35a0a
[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 "types.h"
27
28 /**
29 * @brief Element of the linked_list.
30 *
31 * This element holds a pointer to the value of the list item itself.
32 */
33 typedef struct linked_list_element_s linked_list_element_t;
34
35 struct linked_list_element_s {
36 /**
37 * previous list element
38 * NULL if first element in list
39 */
40 linked_list_element_t *previous;
41 /**
42 * next list element
43 * NULL if last element in list
44 */
45 linked_list_element_t *next;
46 /**
47 * value of a list item
48 */
49 void *value;
50
51 /**
52 * @brief Destroys a linked_list_element object
53 *
54 * @param linked_list_element_t calling object
55 * @returns SUCCESS if succeeded, FAILED otherwise
56 */
57 status_t (*destroy) (linked_list_element_t *this);
58 };
59
60 /**
61 * @brief Creates an empty linked list object
62 *
63 * @param[in] value value of item to be set
64 *
65 * @warning only the pointer to the value is stored
66 *
67 * @return linked_list_element object
68 */
69 linked_list_element_t *linked_list_element_create(void *value);
70
71
72 /**
73 * @brief Double Linked List (named only as linked list)
74 *
75 * @warning Access to an object of this type is not thread-save
76 *
77 * @see job_queue_t
78 * @see event_queue_t
79 * @see send_queue_t
80 */
81 typedef struct linked_list_s linked_list_t;
82
83
84 struct linked_list_s {
85 /**
86 * number of items in the list
87 */
88 int count;
89 /**
90 * First element in list
91 * NULL if no elements in list
92 */
93 linked_list_element_t *first;
94 /**
95 * Last element in list
96 * NULL if no elements in list
97 */
98 linked_list_element_t *last;
99
100 /**
101 * @brief inserts a new item at the beginning of the list
102 *
103 * @param linked_list calling object
104 * @param[in] item value to insert in list
105 * @returns SUCCESS if succeeded, FAILED otherwise
106 */
107 status_t (*insert_first) (linked_list_t *linked_list, void *item);
108
109 /**
110 * @brief removes the first item in the list and returns its value
111 *
112 * @param linked_list calling object
113 * @param[in] item returned value of first item
114 * @returns SUCCESS if succeeded, FAILED otherwise
115 */
116 status_t (*remove_first) (linked_list_t *linked_list, void **item);
117
118 /**
119 * @brief returns the value of the first list item without removing it
120 *
121 * @param linked_list calling object
122 * @param[out] item returned value of first item
123 * @returns SUCCESS if succeeded, FAILED otherwise
124 */
125 status_t (*get_first) (linked_list_t *linked_list, void **item);
126
127 /**
128 * @brief inserts a new item at the end of the list
129 *
130 * @param linked_list calling object
131 * @param[in] item value to insert into list
132 * @returns SUCCESS if succeeded, FAILED otherwise
133 */
134 status_t (*insert_last) (linked_list_t *linked_list, void *item);
135
136 /**
137 * @brief removes the last item in the list and returns its value
138 *
139 * @param linked_list calling object
140 * @param[out] item returned value of last item
141 * @returns SUCCESS if succeeded, FAILED otherwise
142 */
143 status_t (*remove_last) (linked_list_t *linked_list, void **item);
144
145 /**
146 * @brief Returns the value of the last list item without removing it
147 *
148 * @param linked_list calling object
149 * @param[out] item returned value of last item
150 * @returns SUCCESS if succeeded, FAILED otherwise
151 */
152 status_t (*get_last) (linked_list_t *linked_list, void **item);
153
154 /**
155 * @brief Destroys a linked_list object
156 *
157 * @warning all items are removed before deleting the list. The
158 * associated values are NOT destroyed.
159 * Destroying an list which is not empty may cause
160 * memory leaks!
161 *
162 * @param linked_list calling object
163 * @returns SUCCESS if succeeded, FAILED otherwise
164 */
165 status_t (*destroy) (linked_list_t *linked_list);
166 };
167
168 /**
169 * @brief Creates an empty linked list object
170 */
171 linked_list_t *linked_list_create(void);
172
173
174 #endif /*LINKED_LIST_H_*/