1 /* spmfilter - mail filtering framework 2 * Copyright (C) 2009-2012 Axel Steiner and SpaceNet AG 3 * 4 * This program is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 3 of the License, or (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this program. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 /*! 19 * @file smf_list.h 20 * @brief Defines the #SMFList_T data type and functions for a linked lists 21 * that can be iterated over in both directions. 22 * @details Each element in the list contains a piece of data, together with 23 * pointers which link to the previous and next elements in the list. 24 * Using these pointers it is possible to move through the list in both directions. 25 * 26 * @details To create a new #SMFList_T, use smf_list_new() 27 * @details To insert an element into a #SMFList_T, use smf_list_append() 28 * @details To remove an element, use smf_list_remove() 29 * @details To destroy a #SMFList_T use smf_list_free() 30 */ 31 32 #ifndef _SMF_LIST_H 33 #define _SMF_LIST_H 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 #include <cmime.h> 40 41 /*! 42 * @typedef typedef CMimeListElem_T SMFListElem_T 43 * @brief An element of a SMFList_T list 44 */ 45 typedef CMimeListElem_T SMFListElem_T; 46 47 /*! 48 * @typedef typedef CMimeList_T SMFList_T 49 * @brief Double linked list implementation 50 */ 51 typedef CMimeList_T SMFList_T; 52 53 /*! 54 * @fn int smf_list_new(SMFList_T **list, void (*destroy)(void *data)) 55 * @brief Creates a new SMFList_T list 56 * @param list out param to return the new list 57 * @param destroy list destroy function 58 * @returns 0 on success or -1 in case of error 59 */ 60 int smf_list_new(SMFList_T **list, void (*destroy)(void *data)); 61 62 /*! 63 * @fn int smf_list_free(SMFList_T *list) 64 * @brief Free a SMFList_T list 65 * @param list list to free 66 * @returns 0 on success or -1 in case of error 67 */ 68 int smf_list_free(SMFList_T *list); 69 70 /*! 71 * @fn int smf_list_remove(SMFList_T *list, SMFListElem_T *elem, void **data) 72 * @brief Remove an element from list 73 * @param list a SMFList_T list 74 * @param elem the SMFListElem_T element which should be removed 75 * @param data out param to return element data 76 * @returns 0 on success or -1 in case of error 77 */ 78 int smf_list_remove(SMFList_T *list, SMFListElem_T *elem, void **data); 79 80 /*! 81 * @fn int smf_list_append(SMFList_T *list, void *data) 82 * @brief Append data to the end of a list 83 * @param list SMFList_T list to which new data should be appended 84 * @param data new data which should be appended 85 * @returns 0 on success or -1 in case of error 86 */ 87 int smf_list_append(SMFList_T *list, void *data); 88 89 /*! 90 * @fn int smf_list_prepend(SMFList_T *list, void *data) 91 * @brief Prepend data to a list 92 * @param list a SMFList_T list to which new data should be prepended 93 * @param data new data which should be appended 94 * @returns 0 on success or -1 in case of error 95 */ 96 int smf_list_prepend(SMFList_T *list, void *data); 97 98 /*! 99 * @fn void *smf_list_pop_tail(SMFList_T *list) 100 * @brief Remove tail element from list and return data pointer 101 * @param list a SMFList_T list 102 * @returns data pointer of removed list element 103 */ 104 void *smf_list_pop_tail(SMFList_T *list); 105 106 /*! 107 * @fn void *smf_list_pop_head(SMFList_T *list) 108 * @brief Remove head element from list an return data pointer 109 * @param list a SMFList_T list 110 * @returns data pointer of removed list element 111 */ 112 void *smf_list_pop_head(SMFList_T *list); 113 114 /*! 115 * @fn int smf_list_insert_next(SMFList_T *list, SMFListElem_T *elem, void *data) 116 * @brief Insert new element next to elem 117 * @param list a SMFList_T list 118 * @param elem a SMFListElem_T element 119 * @param data data to insert next to element 120 * @returns 0 on sucess or -1 in case of error 121 */ 122 int smf_list_insert_next(SMFList_T *list, SMFListElem_T *elem, void *data); 123 124 /*! 125 * @fn int smf_list_insert_prev(SMFList_T *list, SMFListElem_T *elem, void *data) 126 * @brief Insert new element previous to elem 127 * @param list a SMFList_T list 128 * @param elem a SMFListElem_T element 129 * @param data data to insert previous to element 130 * @returns 0 on sucess or -1 in case of error 131 */ 132 int smf_list_insert_prev(SMFList_T *list, SMFListElem_T *elem, void *data); 133 134 /*! 135 * @fn void smf_list_map(SMFList_T *list, void(*func)(SMFListElem_T *elem,void *args), void *args) 136 * @brief Iterates over list and calls function for every element with the current element 137 * @param list a SMFList_T list 138 * @param func function to call for each element 139 * @param args optional arguments for function pointer 140 */ 141 void smf_list_map(SMFList_T *list, void(*func)(SMFListElem_T *elem,void *args), void *args); 142 143 /*! 144 * @fn int smf_list_map_new(SMFList_T *list, SMFList_T **new, void *(*func)(SMFListElem_T *elem, void *args), void *args) 145 * @brief Iterates over list and calls function func with every element, return value of func will be saved in new list **new 146 * @param list a SMFList_T list 147 * @param new out param to return the new list 148 * @param func function to call for each element 149 * @param args optional arguments for function pointer 150 * returns 0 on sucess or -1 in case of error 151 */ 152 int smf_list_map_new(SMFList_T *list, SMFList_T **new, void *(*func)(SMFListElem_T *elem, void *args), void *args); 153 154 /*! 155 * @def smf_list_size(list) 156 * @returns size of SMFList_T list 157 */ 158 #define smf_list_size(list) ((list)->size) 159 160 /*! 161 * @def smf_list_head(list) 162 * @returns head element of SMFList_T list 163 */ 164 #define smf_list_head(list) ((list)->head) 165 166 /*! 167 * @def smf_list_tail(list) 168 * @returns tail element of SMFList_T list 169 */ 170 #define smf_list_tail(list) ((list)->tail) 171 172 /*! 173 * @def smf_list_is_head(elem) 174 * @returns 1 if element is list head, 0 if not 175 */ 176 #define smf_list_is_head(elem) ((elem)->prev == NULL ? 1 : 0) 177 178 /*! 179 * @def smf_list_is_tail(elem) 180 * @returns 1 if element is list tail, 0 if not 181 */ 182 #define smf_list_is_tail(elem) ((elem)->next == NULL ? 1 : 0) 183 184 /*! 185 * @def smf_list_data(elem) 186 * @returns data pointer of element 187 */ 188 #define smf_list_data(elem) ((elem)->data) 189 190 /*! 191 * @def smf_list_next(elem) 192 * @returns next element 193 */ 194 #define smf_list_next(elem) ((elem)->next) 195 196 /*! 197 * @def smf_list_prev(elem) 198 * @returns previous element 199 */ 200 #define smf_list_prev(elem) ((elem)->prev) 201 202 #ifdef __cplusplus 203 } 204 #endif 205 206 #endif /* _SMF_LIST_H */ 207 208