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