diff options
Diffstat (limited to 'src/libstrongswan/collections/enumerator.h')
| -rw-r--r-- | src/libstrongswan/collections/enumerator.h | 70 |
1 files changed, 49 insertions, 21 deletions
diff --git a/src/libstrongswan/collections/enumerator.h b/src/libstrongswan/collections/enumerator.h index 55f8d83e6..99f8847e4 100644 --- a/src/libstrongswan/collections/enumerator.h +++ b/src/libstrongswan/collections/enumerator.h @@ -1,7 +1,7 @@ /* - * Copyright (C) 2013 Tobias Brunner + * Copyright (C) 2013-2017 Tobias Brunner * Copyright (C) 2007 Martin Willi - * Hochschule fuer Technik Rapperswil + * HSR Hochschule fuer Technik Rapperswil * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the @@ -34,8 +34,11 @@ struct enumerator_t { /** * Enumerate collection. * - * The enumerate function takes a variable argument list containing - * pointers where the enumerated values get written. + * The enumerate() method takes a variable number of pointer arguments + * where the enumerated values get written to. + * + * @note Just assigning the generic enumerator_enumerate_default() function + * that calls the enumerator's venumerate() method is usually enough. * * @param ... variable list of enumerated items, implementation dependent * @return TRUE if pointers returned @@ -43,12 +46,34 @@ struct enumerator_t { bool (*enumerate)(enumerator_t *this, ...); /** - * Destroy a enumerator instance. + * Enumerate collection. + * + * The venumerate() method takes a variable argument list containing + * pointers where the enumerated values get written to. + * + * To simplify the implementation the VA_ARGS_VGET() macro may be used. + * + * @param args variable list of enumerated items, implementation dependent + * @return TRUE if pointers returned + */ + bool (*venumerate)(enumerator_t *this, va_list args); + + /** + * Destroy an enumerator_t instance. */ void (*destroy)(enumerator_t *this); }; /** + * Generic implementation of enumerator_t::enumerate() that simply calls + * the enumerator's venumerate() method. + * + * @param enumerator the enumerator + * @param ... arguments passed to enumerate() + */ +bool enumerator_enumerate_default(enumerator_t *enumerator, ...); + +/** * Create an enumerator which enumerates over nothing * * @return an enumerator over no values @@ -147,38 +172,41 @@ enumerator_t* enumerator_create_token(const char *string, const char *sep, /** * Creates an enumerator which enumerates over enumerated enumerators :-). * - * The variable argument list of enumeration values is limit to 5. + * The outer enumerator is expected to return objects that, when passed to + * inner_contructor, will create a new enumerator that will be enumerated until + * completion (to this enumerator will the pointer arguments that are passed to + * this enumerator be forwarded) at which point a new element from the outer + * enumerator is requested to create a new inner enumerator. * * @param outer outer enumerator - * @param inner_constructor constructor to inner enumerator + * @param inner_constructor constructor to create inner enumerator * @param data data to pass to each inner_constructor call - * @param destroy_data destructor to pass to data + * @param destructor destructor function to clean up data after use * @return the nested enumerator */ enumerator_t *enumerator_create_nested(enumerator_t *outer, enumerator_t *(*inner_constructor)(void *outer, void *data), - void *data, void (*destroy_data)(void *data)); + void *data, void (*destructor)(void *data)); /** - * Creates an enumerator which filters output of another enumerator. + * Creates an enumerator which filters/maps output of another enumerator. * - * The filter function receives the user supplied "data" followed by a - * unfiltered enumeration item, followed by an output pointer where to write - * the filtered data. Then the next input/output pair follows. - * It returns TRUE to deliver the - * values to the caller of enumerate(), FALSE to filter this enumeration. + * The filter function receives the user supplied "data" followed by the + * original enumerator, followed by the arguments passed to the outer + * enumerator. It returns TRUE to deliver the values assigned to these + * arguments to the caller of enumerate() and FALSE to end the enumeration. + * Filtering items is simple as the filter function may just skip enumerated + * items from the original enumerator. * - * The variable argument list of enumeration values is limit to 5. - * - * @param unfiltered unfiltered enumerator to wrap, gets destroyed + * @param orig original enumerator to wrap, gets destroyed * @param filter filter function * @param data user data to supply to filter * @param destructor destructor function to clean up data after use * @return the filtered enumerator */ -enumerator_t *enumerator_create_filter(enumerator_t *unfiltered, - bool (*filter)(void *data, ...), - void *data, void (*destructor)(void *data)); +enumerator_t *enumerator_create_filter(enumerator_t *orig, + bool (*filter)(void *data, enumerator_t *orig, va_list args), + void *data, void (*destructor)(void *data)); /** * Create an enumerator wrapper which does a cleanup on destroy. |