src/libstrongswan/collections/enumerator.h

   1 /*
   2  * Copyright (C) 2007 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup enumerator enumerator
  18  * @{ @ingroup collections
  19  */
  20
  21 #ifndef ENUMERATOR_H_
  22 #define ENUMERATOR_H_
  23
  24 typedef struct enumerator_t enumerator_t;
  25
  26 #include <utils/utils.h>
  27
  28 /**
  29  * Enumerator interface, allows enumeration over collections.
  30  */
  31 struct enumerator_t {
  32
  33         /**
  34          * Enumerate collection.
  35          *
  36          * The enumerate function takes a variable argument list containing
  37          * pointers where the enumerated values get written.
  38          *
  39          * @param ...   variable list of enumerated items, implementation dependent
  40          * @return              TRUE if pointers returned
  41          */
  42         bool (*enumerate)(enumerator_t *this, ...);
  43
  44         /**
  45          * Destroy a enumerator instance.
  46          */
  47         void (*destroy)(enumerator_t *this);
  48 };
  49
  50 /**
  51  * Create an enumerator which enumerates over nothing
  52  *
  53  * @return                      an enumerator over no values
  54  */
  55 enumerator_t* enumerator_create_empty();
  56
  57 /**
  58  * Create an enumerator which enumerates over a single item
  59  *
  60  * @param item          item to enumerate
  61  * @param cleanup       cleanup function called on destroy with the item
  62  * @return                      an enumerator over a single value
  63  */
  64 enumerator_t *enumerator_create_single(void *item, void (*cleanup)(void *item));
  65
  66 /**
  67  * Create an enumerator over files/subdirectories in a directory.
  68  *
  69  * This enumerator_t.enumerate() function returns a (to the directory) relative
  70  * filename (as a char*), an absolute filename (as a char*) and a file status
  71  * (to a struct stat), which all may be NULL. "." and ".." entries are
  72  * skipped. Example:
  73  *
  74  * @code
  75         char *rel, *abs;
  76         struct stat st;
  77         enumerator_t *e;
  78
  79         e = enumerator_create_directory("/tmp");
  80         if (e)
  81         {
  82                 while (e->enumerate(e, &rel, &abs, &st))
  83                 {
  84                         if (S_ISDIR(st.st_mode) && *rel != '.')
  85                         {
  86                                 printf("%s\n", abs);
  87                         }
  88                 }
  89                 e->destroy(e);
  90         }
  91    @endcode
  92  *
  93  * @param path          path of the directory
  94  * @return                      the directory enumerator, NULL on failure
  95  */
  96 enumerator_t* enumerator_create_directory(const char *path);
  97
  98 /**
  99  * Create an enumerator over tokens of a string.
 100  *
 101  * Tokens are separated by one of the characters in sep and trimmed by the
 102  * characters in trim.
 103  *
 104  * @param string        string to parse
 105  * @param sep           separator characters
 106  * @param trim          characters to trim from tokens
 107  * @return                      enumerator over char* tokens
 108  */
 109 enumerator_t* enumerator_create_token(const char *string, const char *sep,
 110                                                                           const char *trim);
 111
 112 /**
 113  * Creates an enumerator which enumerates over enumerated enumerators :-).
 114  *
 115  * The variable argument list of enumeration values is limit to 5.
 116  *
 117  * @param outer                                 outer enumerator
 118  * @param inner_constructor             constructor to inner enumerator
 119  * @param data                                  data to pass to each inner_constructor call
 120  * @param destroy_data                  destructor to pass to data
 121  * @return                                              the nested enumerator
 122  */
 123 enumerator_t *enumerator_create_nested(enumerator_t *outer,
 124                                         enumerator_t *(*inner_constructor)(void *outer, void *data),
 125                                         void *data, void (*destroy_data)(void *data));
 126
 127 /**
 128  * Creates an enumerator which filters output of another enumerator.
 129  *
 130  * The filter function receives the user supplied "data" followed by a
 131  * unfiltered enumeration item, followed by an output pointer where to write
 132  * the filtered data. Then the next input/output pair follows.
 133  * It returns TRUE to deliver the
 134  * values to the caller of enumerate(), FALSE to filter this enumeration.
 135  *
 136  * The variable argument list of enumeration values is limit to 5.
 137  *
 138  * @param unfiltered                    unfiltered enumerator to wrap, gets destroyed
 139  * @param filter                                filter function
 140  * @param data                                  user data to supply to filter
 141  * @param destructor                    destructor function to clean up data after use
 142  * @return                                              the filtered enumerator
 143  */
 144 enumerator_t *enumerator_create_filter(enumerator_t *unfiltered,
 145                                         bool (*filter)(void *data, ...),
 146                                         void *data, void (*destructor)(void *data));
 147
 148 /**
 149  * Create an enumerator wrapper which does a cleanup on destroy.
 150  *
 151  * @param wrapped                               wrapped enumerator
 152  * @param cleanup                               cleanup function called on destroy
 153  * @param data                                  user data to supply to cleanup
 154  * @return                                              the enumerator with cleanup
 155  */
 156 enumerator_t *enumerator_create_cleaner(enumerator_t *wrapped,
 157                                         void (*cleanup)(void *data), void *data);
 158
 159 #endif /** ENUMERATOR_H_ @}*/