implemented more flexible iterator hook API

[strongswan.git] / src / libstrongswan / utils / iterator.h

diff --git a/src/libstrongswan/utils/iterator.h b/src/libstrongswan/utils/iterator.h
index 02a15c5..b4ff85b 100644 (file)
--- a/src/libstrongswan/utils/iterator.h
+++ b/src/libstrongswan/utils/iterator.h
@@ -26,15 +26,46 @@
 
 #include <library.h>
 
 
 #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
 /**
  * @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;
 
 
 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.
  *
  * 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
  * @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
         * 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.
         * 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
         * 
         * @param this                  calling object
         * @param hook                  iterator hook which manipulates the iterated value