implemented more flexible iterator hook API
[strongswan.git] / src / libstrongswan / utils / iterator.h
index 02a15c5..b4ff85b 100644 (file)
 
 #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