Annotation of embedaddon/strongswan/src/libstrongswan/collections/linked_list.h, revision 1.1
1.1 ! misho 1: /*
! 2: * Copyright (C) 2007-2018 Tobias Brunner
! 3: * Copyright (C) 2005-2008 Martin Willi
! 4: * Copyright (C) 2005 Jan Hutter
! 5: * HSR Hochschule fuer Technik Rapperswil
! 6: *
! 7: * This program is free software; you can redistribute it and/or modify it
! 8: * under the terms of the GNU General Public License as published by the
! 9: * Free Software Foundation; either version 2 of the License, or (at your
! 10: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
! 11: *
! 12: * This program is distributed in the hope that it will be useful, but
! 13: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
! 14: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
! 15: * for more details.
! 16: */
! 17:
! 18: /**
! 19: * @defgroup linked_list linked_list
! 20: * @{ @ingroup collections
! 21: */
! 22:
! 23: #ifndef LINKED_LIST_H_
! 24: #define LINKED_LIST_H_
! 25:
! 26: typedef struct linked_list_t linked_list_t;
! 27:
! 28: #include <collections/enumerator.h>
! 29:
! 30: /**
! 31: * Function to match elements in a linked list
! 32: *
! 33: * @param item current list item
! 34: * @param args user supplied data
! 35: * @return TRUE, if the item matched, FALSE otherwise
! 36: */
! 37: typedef bool (*linked_list_match_t)(void *item, va_list args);
! 38:
! 39: /**
! 40: * Helper function to match a string in a linked list of strings
! 41: *
! 42: * @param item list item (char*)
! 43: * @param args user supplied data (char*)
! 44: * @return
! 45: */
! 46: bool linked_list_match_str(void *item, va_list args);
! 47:
! 48: /**
! 49: * Function to be invoked on elements in a linked list
! 50: *
! 51: * @param item current list item
! 52: * @param args user supplied data
! 53: */
! 54: typedef void (*linked_list_invoke_t)(void *item, va_list args);
! 55:
! 56: /**
! 57: * Class implementing a double linked list.
! 58: *
! 59: * General purpose linked list. This list is not synchronized.
! 60: */
! 61: struct linked_list_t {
! 62:
! 63: /**
! 64: * Gets the count of items in the list.
! 65: *
! 66: * @return number of items in list
! 67: */
! 68: int (*get_count) (linked_list_t *this);
! 69:
! 70: /**
! 71: * Create an enumerator over the list.
! 72: *
! 73: * @note The enumerator's position is invalid before the first call
! 74: * to enumerate().
! 75: *
! 76: * @return enumerator over list items
! 77: */
! 78: enumerator_t* (*create_enumerator)(linked_list_t *this);
! 79:
! 80: /**
! 81: * Resets the enumerator's current position to the beginning of the list.
! 82: *
! 83: * @param enumerator enumerator to reset
! 84: */
! 85: void (*reset_enumerator)(linked_list_t *this, enumerator_t *enumerator);
! 86:
! 87: /**
! 88: * Inserts a new item at the beginning of the list.
! 89: *
! 90: * @param item item value to insert in list
! 91: */
! 92: void (*insert_first) (linked_list_t *this, void *item);
! 93:
! 94: /**
! 95: * Removes the first item in the list and returns its value.
! 96: *
! 97: * @param item returned value of first item, or NULL
! 98: * @return SUCCESS, or NOT_FOUND if list is empty
! 99: */
! 100: status_t (*remove_first) (linked_list_t *this, void **item);
! 101:
! 102: /**
! 103: * Inserts a new item before the item the enumerator currently points to.
! 104: *
! 105: * If this method is called after all items have been enumerated, the item
! 106: * is inserted last. This is helpful when inserting items into a sorted
! 107: * list.
! 108: *
! 109: * @note The position of the enumerator is not changed. So it is safe to
! 110: * call this before or after remove_at() to replace the item at the current
! 111: * position (the enumerator will continue with the next item in the list).
! 112: * And in particular, when inserting an item before calling enumerate(),
! 113: * the enumeration will continue (or start) at the item that was first in
! 114: * the list before any items were inserted (enumerate() will return FALSE
! 115: * if the list was empty before).
! 116: *
! 117: * @param enumerator enumerator with position
! 118: * @param item item value to insert in list
! 119: */
! 120: void (*insert_before)(linked_list_t *this, enumerator_t *enumerator,
! 121: void *item);
! 122:
! 123: /**
! 124: * Remove an item from the list where the enumerator points to.
! 125: *
! 126: * If this method is called before calling enumerate() of the enumerator,
! 127: * the first item in the list, if any, will be removed. No item is removed,
! 128: * if the method is called after enumerating all items.
! 129: *
! 130: * @param enumerator enumerator with position
! 131: */
! 132: void (*remove_at)(linked_list_t *this, enumerator_t *enumerator);
! 133:
! 134: /**
! 135: * Remove items from the list matching the given item.
! 136: *
! 137: * If a compare function is given, it is called for each item, with the
! 138: * first parameter being the current list item and the second parameter
! 139: * being the supplied item. Return TRUE from the compare function to remove
! 140: * the item, return FALSE to keep it in the list.
! 141: *
! 142: * If compare is NULL, comparison is done by pointers.
! 143: *
! 144: * @param item item to remove/pass to comparator
! 145: * @param compare compare function, or NULL
! 146: * @return number of removed items
! 147: */
! 148: int (*remove)(linked_list_t *this, void *item, bool (*compare)(void*,void*));
! 149:
! 150: /**
! 151: * Returns the value of the first list item without removing it.
! 152: *
! 153: * @param item returned value of first item
! 154: * @return SUCCESS, NOT_FOUND if list is empty
! 155: */
! 156: status_t (*get_first) (linked_list_t *this, void **item);
! 157:
! 158: /**
! 159: * Inserts a new item at the end of the list.
! 160: *
! 161: * @param item value to insert into list
! 162: */
! 163: void (*insert_last) (linked_list_t *this, void *item);
! 164:
! 165: /**
! 166: * Removes the last item in the list and returns its value.
! 167: *
! 168: * @param item returned value of last item, or NULL
! 169: * @return SUCCESS, NOT_FOUND if list is empty
! 170: */
! 171: status_t (*remove_last) (linked_list_t *this, void **item);
! 172:
! 173: /**
! 174: * Returns the value of the last list item without removing it.
! 175: *
! 176: * @param item returned value of last item
! 177: * @return SUCCESS, NOT_FOUND if list is empty
! 178: */
! 179: status_t (*get_last) (linked_list_t *this, void **item);
! 180:
! 181: /**
! 182: * Find the first matching element in the list.
! 183: *
! 184: * The first object passed to the match function is the current list item,
! 185: * followed by the user supplied data.
! 186: * If the supplied function returns TRUE so does this function, and the
! 187: * current object is returned in the third parameter (if given), otherwise,
! 188: * the next item is checked.
! 189: *
! 190: * If match is NULL, *item and the current object are compared.
! 191: *
! 192: * @param match comparison function to call on each object, or NULL
! 193: * @param item the list item, if found, or NULL
! 194: * @param ... user data to supply to match function
! 195: * @return TRUE if found, FALSE otherwise (or if neither match,
! 196: * nor item is supplied)
! 197: */
! 198: bool (*find_first)(linked_list_t *this, linked_list_match_t match,
! 199: void **item, ...);
! 200:
! 201: /**
! 202: * Invoke a method on all of the contained objects.
! 203: *
! 204: * If a linked list contains objects with function pointers,
! 205: * invoke() can call a method on each of the objects. The
! 206: * method is specified by an offset of the function pointer,
! 207: * which can be evaluated at compile time using the offsetof
! 208: * macro, e.g.: list->invoke(list, offsetof(object_t, method));
! 209: *
! 210: * @param offset offset of the method to invoke on objects
! 211: */
! 212: void (*invoke_offset)(linked_list_t *this, size_t offset);
! 213:
! 214: /**
! 215: * Invoke a function on all of the contained objects.
! 216: *
! 217: * @param function function to call for each object
! 218: * @param ... user data to supply to called function
! 219: */
! 220: void (*invoke_function)(linked_list_t *this, linked_list_invoke_t function,
! 221: ...);
! 222:
! 223: /**
! 224: * Clones a list and its objects using the objects' clone method.
! 225: *
! 226: * @param offset offset to the objects clone function
! 227: * @return cloned list
! 228: */
! 229: linked_list_t *(*clone_offset) (linked_list_t *this, size_t offset);
! 230:
! 231: /**
! 232: * Compare two lists and their objects for equality using the given equals
! 233: * method.
! 234: *
! 235: * @param other list to compare
! 236: * @param offset offset of the objects equals method
! 237: * @return TRUE if lists and objects are equal, FALSE otherwise
! 238: */
! 239: bool (*equals_offset) (linked_list_t *this, linked_list_t *other,
! 240: size_t offset);
! 241:
! 242: /**
! 243: * Compare two lists and their objects for equality using the given function.
! 244: *
! 245: * @param other list to compare
! 246: * @param function function to compare the objects
! 247: * @return TRUE if lists and objects are equal, FALSE otherwise
! 248: */
! 249: bool (*equals_function) (linked_list_t *this, linked_list_t *other,
! 250: bool (*)(void*,void*));
! 251:
! 252: /**
! 253: * Destroys a linked_list object.
! 254: */
! 255: void (*destroy) (linked_list_t *this);
! 256:
! 257: /**
! 258: * Destroys a list and its objects using the destructor.
! 259: *
! 260: * If a linked list and the contained objects should be destroyed, use
! 261: * destroy_offset. The supplied offset specifies the destructor to
! 262: * call on each object. The offset may be calculated using the offsetof
! 263: * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
! 264: *
! 265: * @param offset offset of the objects destructor
! 266: */
! 267: void (*destroy_offset) (linked_list_t *this, size_t offset);
! 268:
! 269: /**
! 270: * Destroys a list and its contents using a a cleanup function.
! 271: *
! 272: * If a linked list and its contents should get destroyed using a specific
! 273: * cleanup function, use destroy_function. This is useful when the
! 274: * list contains malloc()-ed blocks which should get freed,
! 275: * e.g.: list->destroy_function(list, free);
! 276: *
! 277: * @param function function to call on each object
! 278: */
! 279: void (*destroy_function) (linked_list_t *this, void (*)(void*));
! 280: };
! 281:
! 282: /**
! 283: * Creates an empty linked list object.
! 284: *
! 285: * @return linked_list_t object.
! 286: */
! 287: linked_list_t *linked_list_create(void);
! 288:
! 289: /**
! 290: * Creates a linked list from an enumerator.
! 291: *
! 292: * @param enumerator enumerator over void*, gets destroyed
! 293: * @return linked_list_t object, containing enumerated values
! 294: */
! 295: linked_list_t *linked_list_create_from_enumerator(enumerator_t *enumerator);
! 296:
! 297: /**
! 298: * Creates a linked list from a NULL terminated vararg list of items.
! 299: *
! 300: * @param first first item
! 301: * @param ... subsequent items, terminated by NULL
! 302: * @return linked_list_t object, containing passed items
! 303: */
! 304: linked_list_t *linked_list_create_with_items(void *first, ...);
! 305:
! 306: #endif /** LINKED_LIST_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to linked_list.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / collections