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