Annotation of embedaddon/strongswan/src/libstrongswan/collections/enumerator.h, revision 1.1
1.1 ! misho 1: /*
! 2: * Copyright (C) 2013-2017 Tobias Brunner
! 3: * Copyright (C) 2007 Martin Willi
! 4: * HSR Hochschule fuer Technik Rapperswil
! 5: *
! 6: * This program is free software; you can redistribute it and/or modify it
! 7: * under the terms of the GNU General Public License as published by the
! 8: * Free Software Foundation; either version 2 of the License, or (at your
! 9: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
! 10: *
! 11: * This program is distributed in the hope that it will be useful, but
! 12: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
! 13: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
! 14: * for more details.
! 15: */
! 16:
! 17: /**
! 18: * @defgroup enumerator enumerator
! 19: * @{ @ingroup collections
! 20: */
! 21:
! 22: #ifndef ENUMERATOR_H_
! 23: #define ENUMERATOR_H_
! 24:
! 25: typedef struct enumerator_t enumerator_t;
! 26:
! 27: #include <utils/utils.h>
! 28:
! 29: /**
! 30: * Enumerator interface, allows enumeration over collections.
! 31: */
! 32: struct enumerator_t {
! 33:
! 34: /**
! 35: * Enumerate collection.
! 36: *
! 37: * The enumerate() method takes a variable number of pointer arguments
! 38: * where the enumerated values get written to.
! 39: *
! 40: * @note Just assigning the generic enumerator_enumerate_default() function
! 41: * that calls the enumerator's venumerate() method is usually enough.
! 42: *
! 43: * @param ... variable list of enumerated items, implementation dependent
! 44: * @return TRUE if pointers returned
! 45: */
! 46: bool (*enumerate)(enumerator_t *this, ...);
! 47:
! 48: /**
! 49: * Enumerate collection.
! 50: *
! 51: * The venumerate() method takes a variable argument list containing
! 52: * pointers where the enumerated values get written to.
! 53: *
! 54: * To simplify the implementation the VA_ARGS_VGET() macro may be used.
! 55: *
! 56: * @param args variable list of enumerated items, implementation dependent
! 57: * @return TRUE if pointers returned
! 58: */
! 59: bool (*venumerate)(enumerator_t *this, va_list args);
! 60:
! 61: /**
! 62: * Destroy an enumerator_t instance.
! 63: */
! 64: void (*destroy)(enumerator_t *this);
! 65: };
! 66:
! 67: /**
! 68: * Generic implementation of enumerator_t::enumerate() that simply calls
! 69: * the enumerator's venumerate() method.
! 70: *
! 71: * @param enumerator the enumerator
! 72: * @param ... arguments passed to enumerate()
! 73: */
! 74: bool enumerator_enumerate_default(enumerator_t *enumerator, ...);
! 75:
! 76: /**
! 77: * Create an enumerator which enumerates over nothing
! 78: *
! 79: * @return an enumerator over no values
! 80: */
! 81: enumerator_t* enumerator_create_empty();
! 82:
! 83: /**
! 84: * Create an enumerator which enumerates over a single item
! 85: *
! 86: * @param item item to enumerate
! 87: * @param cleanup cleanup function called on destroy with the item
! 88: * @return an enumerator over a single value
! 89: */
! 90: enumerator_t *enumerator_create_single(void *item, void (*cleanup)(void *item));
! 91:
! 92: /**
! 93: * Create an enumerator over files/subdirectories in a directory.
! 94: *
! 95: * This enumerator_t.enumerate() function returns a (to the directory) relative
! 96: * filename (as a char*), an absolute filename (as a char*) and a file status
! 97: * (to a struct stat), which all may be NULL. "." and ".." entries are
! 98: * skipped.
! 99: *
! 100: * Example:
! 101: *
! 102: * @code
! 103: char *rel, *abs;
! 104: struct stat st;
! 105: enumerator_t *e;
! 106:
! 107: e = enumerator_create_directory("/tmp");
! 108: if (e)
! 109: {
! 110: while (e->enumerate(e, &rel, &abs, &st))
! 111: {
! 112: if (S_ISDIR(st.st_mode) && *rel != '.')
! 113: {
! 114: printf("%s\n", abs);
! 115: }
! 116: }
! 117: e->destroy(e);
! 118: }
! 119: @endcode
! 120: *
! 121: * @param path path of the directory
! 122: * @return the directory enumerator, NULL on failure
! 123: */
! 124: enumerator_t* enumerator_create_directory(const char *path);
! 125:
! 126: /**
! 127: * Create an enumerator over files/directories matching a file pattern.
! 128: *
! 129: * This enumerator_t.enumerate() function returns the filename (as a char*),
! 130: * and a file status (to a struct stat), which both may be NULL.
! 131: *
! 132: * Example:
! 133: *
! 134: * @code
! 135: char *file;
! 136: struct stat st;
! 137: enumerator_t *e;
! 138:
! 139: e = enumerator_create_glob("/etc/ipsec.*.conf");
! 140: if (e)
! 141: {
! 142: while (e->enumerate(e, &file, &st))
! 143: {
! 144: if (S_ISREG(st.st_mode))
! 145: {
! 146: printf("%s\n", file);
! 147: }
! 148: }
! 149: e->destroy(e);
! 150: }
! 151: @endcode
! 152: *
! 153: * @param pattern file pattern to match
! 154: * @return the enumerator, NULL if not supported
! 155: */
! 156: enumerator_t* enumerator_create_glob(const char *pattern);
! 157:
! 158: /**
! 159: * Create an enumerator over tokens of a string.
! 160: *
! 161: * Tokens are separated by one of the characters in sep and trimmed by the
! 162: * characters in trim.
! 163: *
! 164: * @param string string to parse
! 165: * @param sep separator characters
! 166: * @param trim characters to trim from tokens
! 167: * @return enumerator over char* tokens
! 168: */
! 169: enumerator_t* enumerator_create_token(const char *string, const char *sep,
! 170: const char *trim);
! 171:
! 172: /**
! 173: * Creates an enumerator which enumerates over enumerated enumerators :-).
! 174: *
! 175: * The outer enumerator is expected to return objects that, when passed to
! 176: * inner_constructor, will create a new enumerator that will be enumerated until
! 177: * completion (to this enumerator will the pointer arguments that are passed to
! 178: * this enumerator be forwarded) at which point a new element from the outer
! 179: * enumerator is requested to create a new inner enumerator.
! 180: *
! 181: * @param outer outer enumerator
! 182: * @param inner_constructor constructor to create inner enumerator
! 183: * @param data data to pass to each inner_constructor call
! 184: * @param destructor destructor function to clean up data after use
! 185: * @return the nested enumerator
! 186: */
! 187: enumerator_t *enumerator_create_nested(enumerator_t *outer,
! 188: enumerator_t *(*inner_constructor)(void *outer, void *data),
! 189: void *data, void (*destructor)(void *data));
! 190:
! 191: /**
! 192: * Creates an enumerator which filters/maps output of another enumerator.
! 193: *
! 194: * The filter function receives the user supplied "data" followed by the
! 195: * original enumerator, followed by the arguments passed to the outer
! 196: * enumerator. It returns TRUE to deliver the values assigned to these
! 197: * arguments to the caller of enumerate() and FALSE to end the enumeration.
! 198: * Filtering items is simple as the filter function may just skip enumerated
! 199: * items from the original enumerator.
! 200: *
! 201: * @param orig original enumerator to wrap, gets destroyed
! 202: * @param filter filter function
! 203: * @param data user data to supply to filter
! 204: * @param destructor destructor function to clean up data after use
! 205: * @return the filtered enumerator
! 206: */
! 207: enumerator_t *enumerator_create_filter(enumerator_t *orig,
! 208: bool (*filter)(void *data, enumerator_t *orig, va_list args),
! 209: void *data, void (*destructor)(void *data));
! 210:
! 211: /**
! 212: * Create an enumerator wrapper which does a cleanup on destroy.
! 213: *
! 214: * @param wrapped wrapped enumerator
! 215: * @param cleanup cleanup function called on destroy
! 216: * @param data user data to supply to cleanup
! 217: * @return the enumerator with cleanup
! 218: */
! 219: enumerator_t *enumerator_create_cleaner(enumerator_t *wrapped,
! 220: void (*cleanup)(void *data), void *data);
! 221:
! 222: #endif /** ENUMERATOR_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to enumerator.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libstrongswan / collections