Source/charon/utils/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 typedef struct linked_list_iterator_t linked_list_iterator_t;
  29
  30 /**
  31  * @brief Iterator for a linked list.
  32  *
  33  * This element holds a pointer to the current element in the linked list
  34  *
  35  * @warning the iterator is NOT thread-save
  36  */
  37 struct linked_list_iterator_t {
  38
  39         /**
  40          * @brief returns TRUE if more elements are available
  41          *
  42          * @param this calling object
  43          * @return if more elements are avaiable TRUE, FALSE otherwise
  44          */
  45         bool (*has_next) (linked_list_iterator_t *this);
  46
  47         /**
  48          * @brief returns the current value at the iterator position
  49          *
  50          * @param this calling object
  51          * @param[out] value value is set to the current value at iterator position
  52          * @return SUCCESS if succeeded, FAILED otherwise
  53          */
  54         status_t (*current) (linked_list_iterator_t *this, void **value);
  55
  56         /**
  57          * @brief inserts a new item before the given iterator position
  58          *
  59          * The iterator position is not changed after inserting
  60          *
  61          * @param this calling iterator
  62          * @param[in] item value to insert in list
  63          * @return SUCCESS if succeeded, FAILED otherwise
  64          */
  65         status_t (*insert_before) (linked_list_iterator_t *this, void *item);
  66
  67         /**
  68          * @brief inserts a new item after the given iterator position
  69          *
  70          * The iterator position is not changed after inserting
  71          *
  72          * @param this calling iterator
  73          * @param[in] item value to insert in list
  74          * @return SUCCESS if succeeded, FAILED otherwise
  75          */
  76         status_t (*insert_after) (linked_list_iterator_t *this, void *item);
  77
  78         /**
  79          * @brief Resets a linked_list_iterator object
  80          *
  81          * @param this calling object
  82          * @return SUCCESS if succeeded, FAILED otherwise
  83          */
  84         status_t (*reset) (linked_list_iterator_t *this);
  85
  86         /**
  87          * @brief Destroys a linked_list_iterator object
  88          *
  89          * @param this calling object
  90          * @return SUCCESS if succeeded, FAILED otherwise
  91          */
  92         status_t (*destroy) (linked_list_iterator_t *this);
  93 };
  94
  95 typedef struct linked_list_t linked_list_t;
  96
  97
  98 /**
  99  * @brief Double Linked List (named only as linked list).
 100  *
 101  * @warning Access to an object of this type is not thread-save
 102  *
 103  * @see job_queue_t
 104  * @see event_queue_t
 105  * @see send_queue_t
 106  */
 107 struct linked_list_t {
 108
 109         /**
 110          * @brief gets the count of items in the list
 111          *
 112          * @param linked_list calling object
 113          * @return number of items in list
 114          */
 115         int (*get_count) (linked_list_t *linked_list);
 116
 117         /**
 118          * @brief creates a iterator for the given list
 119          *
 120          * @warning has to get destroyed
 121          *
 122          * @param linked_list calling object
 123          * @param[out] iterator place where the iterator is written
 124          * @param[in] forward iterator direction (TRUE: front to end)
 125          * @return SUCCESS if succeeded, FAILED otherwise
 126          */
 127         status_t (*create_iterator) (linked_list_t *linked_list, linked_list_iterator_t **iterator,bool forward);
 128
 129         /**
 130          * @brief inserts a new item at the beginning of the list
 131          *
 132          * @param linked_list calling object
 133          * @param[in] item value to insert in list
 134          * @return SUCCESS if succeeded, FAILED otherwise
 135          */
 136         status_t (*insert_first) (linked_list_t *linked_list, void *item);
 137
 138         /**
 139          * @brief removes an element from list at the given iterator position
 140          *
 141          * The position of the iterator is set in the following order:
 142          * - to the item before, if available
 143          * - otherwise to the item after, if available
 144          * - otherwise it gets reseted
 145          *
 146          * @param linked_list calling object
 147          * @param iterator iterator holding the position of the element to remove
 148          * @return SUCCESS if succeeded, FAILED otherwise
 149          */
 150         status_t (*remove) (linked_list_t *linked_list, linked_list_iterator_t *iterator);
 151
 152         /**
 153          * @brief removes the first item in the list and returns its value
 154          *
 155          * @param linked_list calling object
 156          * @param[in] item returned value of first item
 157          * @return SUCCESS if succeeded, FAILED otherwise
 158          */
 159         status_t (*remove_first) (linked_list_t *linked_list, void **item);
 160
 161         /**
 162          * @brief returns the value of the first list item without removing it
 163          *
 164          * @param linked_list calling object
 165          * @param[out] item returned value of first item
 166          * @return SUCCESS if succeeded, FAILED otherwise
 167          */
 168         status_t (*get_first) (linked_list_t *linked_list, void **item);
 169
 170         /**
 171          * @brief inserts a new item at the end of the list
 172          *
 173          * @param linked_list calling object
 174          * @param[in] item value to insert into list
 175          * @return SUCCESS if succeeded, FAILED otherwise
 176          */
 177         status_t (*insert_last) (linked_list_t *linked_list, void *item);
 178
 179         /**
 180          * @brief removes the last item in the list and returns its value
 181          *
 182          * @param linked_list calling object
 183          * @param[out] item returned value of last item
 184          * @return SUCCESS if succeeded, FAILED otherwise
 185          */
 186         status_t (*remove_last) (linked_list_t *linked_list, void **item);
 187
 188         /**
 189          * @brief Returns the value of the last list item without removing it
 190          *
 191          * @param linked_list calling object
 192          * @param[out] item returned value of last item
 193          * @return SUCCESS if succeeded, FAILED otherwise
 194          */
 195         status_t (*get_last) (linked_list_t *linked_list, void **item);
 196
 197         /**
 198          * @brief Destroys a linked_list object
 199          *
 200          * @warning all items are removed before deleting the list. The
 201          *          associated values are NOT destroyed.
 202          *                      Destroying an list which is not empty may cause
 203          *                      memory leaks!
 204          *
 205          * @param linked_list calling object
 206          * @return SUCCESS if succeeded, FAILED otherwise
 207          */
 208         status_t (*destroy) (linked_list_t *linked_list);
 209 };
 210
 211 /**
 212  * @brief Creates an empty linked list object
 213  */
 214 linked_list_t *linked_list_create(void);
 215
 216
 217 #endif /*LINKED_LIST_H_*/