src/libstrongswan/utils/iterator.h

   1 /**
   2  * @file iterator.h
   3  *
   4  * @brief Interface iterator_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005-2006 Martin Willi
  10  * Copyright (C) 2005 Jan Hutter
  11  * Hochschule fuer Technik Rapperswil
  12  *
  13  * This program is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU General Public License as published by the
  15  * Free Software Foundation; either version 2 of the License, or (at your
  16  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  17  *
  18  * This program is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  20  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  21  * for more details.
  22  */
  23
  24 #ifndef ITERATOR_H_
  25 #define ITERATOR_H_
  26
  27 #include <library.h>
  28
  29 typedef enum hook_result_t hook_result_t;
  30
  31 /**
  32  * @brief Return value of an iterator hook.
  33  *
  34  * Returning HOOK_AGAIN is useful to "inject" additional elements in an
  35  * iteration, HOOK_NEXT is the normal iterator behavior, and HOOK_SKIP may
  36  * be used to filter elements out.
  37  *
  38  * @ingroup utils
  39  */
  40 enum hook_result_t {
  41
  42         /**
  43          * A value was placed in out, hook is called again with the same "in"
  44          */
  45         HOOK_AGAIN,
  46
  47         /**
  48          * A value was placed in out, hook is called again with next "in" (if any)
  49          */
  50         HOOK_NEXT,
  51
  52         /**
  53          * No value in out, call again with next "in" (if any)
  54          */
  55         HOOK_SKIP,
  56 };
  57
  58 /**
  59  * @brief Iterator hook function prototype.
  60  *
  61  * @param param         user supplied parameter
  62  * @param in            the value the hook receives from the iterator
  63  * @param out           the value supplied as a result to the iterator
  64  * @return                      a hook_result_t
  65  *
  66  * @ingroup utils
  67  */
  68 typedef hook_result_t (iterator_hook_t)(void *param, void *in, void **out);
  69
  70
  71 typedef struct iterator_t iterator_t;
  72
  73 /**
  74  * @brief Iterator interface, allows iteration over collections.
  75  *
  76  * iterator_t defines an interface for iterating over collections.
  77  * It allows searching, deleting, updating and inserting.
  78  *
  79  * @b Constructors:
  80  * - via linked_list_t.create_iterator, or
  81  * - any other class which supports the iterator_t interface
  82  *
  83  * @see linked_list_t
  84  *
  85  * @ingroup utils
  86  */
  87 struct iterator_t {
  88
  89         /**
  90          * @brief Return number of list items.
  91          *
  92          * @param this                  calling object
  93          * @return                              number of list items
  94          */
  95         int (*get_count) (iterator_t *this);
  96
  97         /**
  98          * @brief Iterate over all items.
  99          *
 100          * The easy way to iterate over items.
 101          *
 102          * @param this                  calling object
 103          * @param[out] value    item
 104          * @return
 105          *                                              - TRUE, if there was an element available,
 106          *                                              - FALSE otherwise
 107          */
 108         bool (*iterate) (iterator_t *this, void** value);
 109
 110         /**
 111          * @brief Hook a function into the iterator.
 112          *
 113          * Sometimes it is useful to hook in an iterator. The hook function is
 114          * called before any successful return of iterate(). It takes the
 115          * iterator value, may manipulate it (or the references object), and returns
 116          * the value that the iterate() function returns. Depending on the hook
 117          * return value, the hook is called again, called with next, or skipped.
 118          * A value of NULL deactivates the iterator hook.
 119          * If an iterator is hooked, only the iterate() method is valid,
 120          * all other methods behave undefined.
 121          *
 122          * @param this                  calling object
 123          * @param hook                  iterator hook which manipulates the iterated value
 124          * @param param                 user supplied parameter to pass back to the hook
 125          */
 126         void (*set_iterator_hook) (iterator_t *this, iterator_hook_t *hook,
 127                                                            void *param);
 128
 129         /**
 130          * @brief Inserts a new item before the given iterator position.
 131          *
 132          * The iterator position is not changed after inserting
 133          *
 134          * @param this                  calling iterator
 135          * @param[in] item              value to insert in list
 136          */
 137         void (*insert_before) (iterator_t *this, void *item);
 138
 139         /**
 140          * @brief Inserts a new item after the given iterator position.
 141          *
 142          * The iterator position is not changed after inserting.
 143          *
 144          * @param this                  calling iterator
 145          * @param[in] item              value to insert in list
 146          */
 147         void (*insert_after) (iterator_t *this, void *item);
 148
 149         /**
 150          * @brief Replace the current item at current iterator position.
 151          *
 152          * The iterator position is not changed after replacing.
 153          *
 154          * @param this                  calling iterator
 155          * @param[out] old_item old value will be written here(can be NULL)
 156          * @param[in] new_item  new value
 157          *
 158          * @return
 159          *                                              - SUCCESS
 160          *                                              - FAILED if iterator is on an invalid position
 161          */
 162         status_t (*replace) (iterator_t *this, void **old_item, void *new_item);
 163
 164         /**
 165          * @brief Removes an element from list at the given iterator position.
 166          *
 167          * The iterator is set the the following position:
 168          * - to the item before, if available
 169          * - it gets reseted, otherwise
 170          *
 171          * @param this                  calling object
 172          * @return
 173          *                                              - SUCCESS
 174          *                                              - FAILED if iterator is on an invalid position
 175          */
 176         status_t (*remove) (iterator_t *this);
 177
 178         /**
 179          * @brief Resets the iterator position.
 180          *
 181          * After reset, the iterator_t objects doesn't point to an element.
 182          * A call to iterator_t.has_next is necessary to do any other operations
 183          * with the resetted iterator.
 184          *
 185          * @param this                  calling object
 186          */
 187         void (*reset) (iterator_t *this);
 188
 189         /**
 190          * @brief Destroys an iterator.
 191          *
 192          * @param this                  iterator to destroy
 193          *
 194          */
 195         void (*destroy) (iterator_t *this);
 196 };
 197
 198 #endif /*ITERATOR_H_*/