summaryrefslogtreecommitdiff
path: root/src/libstrongswan/utils/iterator.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/libstrongswan/utils/iterator.h')
-rw-r--r--src/libstrongswan/utils/iterator.h42
1 files changed, 37 insertions, 5 deletions
diff --git a/src/libstrongswan/utils/iterator.h b/src/libstrongswan/utils/iterator.h
index 02a15c534..b4ff85bfb 100644
--- a/src/libstrongswan/utils/iterator.h
+++ b/src/libstrongswan/utils/iterator.h
@@ -26,15 +26,46 @@
#include <library.h>
+typedef enum hook_result_t hook_result_t;
+
+/**
+ * @brief Return value of an iterator hook.
+ *
+ * Returning HOOK_AGAIN is useful to "inject" additional elements in an
+ * iteration, HOOK_NEXT is the normal iterator behavior, and HOOK_SKIP may
+ * be used to filter elements out.
+ *
+ * @ingroup utils
+ */
+enum hook_result_t {
+
+ /**
+ * A value was placed in out, hook is called again with the same "in"
+ */
+ HOOK_AGAIN,
+
+ /**
+ * A value was placed in out, hook is called again with next "in" (if any)
+ */
+ HOOK_NEXT,
+
+ /**
+ * No value in out, call again with next "in" (if any)
+ */
+ HOOK_SKIP,
+};
+
/**
* @brief Iterator hook function prototype.
*
* @param param user supplied parameter
* @param in the value the hook receives from the iterator
* @param out the value supplied as a result to the iterator
- * @return TRUE to return "out", FALSE to skip this value
+ * @return a hook_result_t
+ *
+ * @ingroup utils
*/
-typedef bool (iterator_hook_t)(void *param, void *in, void **out);
+typedef hook_result_t (iterator_hook_t)(void *param, void *in, void **out);
typedef struct iterator_t iterator_t;
@@ -45,8 +76,6 @@ typedef struct iterator_t iterator_t;
* iterator_t defines an interface for iterating over collections.
* It allows searching, deleting, updating and inserting.
*
- * Thanks to JMP for iterator lessons :-)
- *
* @b Constructors:
* - via linked_list_t.create_iterator, or
* - any other class which supports the iterator_t interface
@@ -84,8 +113,11 @@ struct iterator_t {
* Sometimes it is useful to hook in an iterator. The hook function is
* called before any successful return of iterate(). It takes the
* iterator value, may manipulate it (or the references object), and returns
- * the value that the iterate() function returns.
+ * the value that the iterate() function returns. Depending on the hook
+ * return value, the hook is called again, called with next, or skipped.
* A value of NULL deactivates the iterator hook.
+ * If an iterator is hooked, only the iterate() method is valid,
+ * all other methods behave undefined.
*
* @param this calling object
* @param hook iterator hook which manipulates the iterated value