Subversion Repositories Games.Descent

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
1 pmbaty 1 
#ifndef INCL_PHYSFSEXT_GLOBBING_H
2 
#define INCL_PHYSFSEXT_GLOBBING_H
3 
 
4 
/** \file globbing.h */
5 
 
6 
#include "physfs.h"
7 
 
8 
/**
9 
 * \mainpage PhysicsFS globbing
10 
 *
11 
 * This is an extension to PhysicsFS to let you search for files with basic
12 
 *  wildcard matching, regardless of what sort of filesystem or archive they
13 
 *  reside in. It does this by enumerating directories as needed and manually
14 
 *  locating matching entries.
15 
 *
16 
 * Usage: Set up PhysicsFS as you normally would, then use
17 
 *  PHYSFSEXT_enumerateFilesWildcard() when enumerating files. This is just
18 
 *  like PHYSFS_enumerateFiles(), but it returns a subset that matches your
19 
 *  wildcard pattern. You must call PHYSFSEXT_freeEnumeration() on the results,
20 
 *  just PHYSFS_enumerateFiles() would do with PHYSFS_freeList().
21 
 *
22 
 * License: this code is public domain. I make no warranty that it is useful,
23 
 *  correct, harmless, or environmentally safe.
24 
 *
25 
 * This particular file may be used however you like, including copying it
26 
 *  verbatim into a closed-source project, exploiting it commercially, and
27 
 *  removing any trace of my name from the source (although I hope you won't
28 
 *  do that). I welcome enhancements and corrections to this file, but I do
29 
 *  not require you to send me patches if you make changes. This code has
30 
 *  NO WARRANTY.
31 
 *
32 
 * Unless otherwise stated, the rest of PhysicsFS falls under the zlib license.
33 
 *  Please see LICENSE.txt in the source's "docs" directory.
34 
 *
35 
 *  \author Ryan C. Gordon.
36 
 */
37 
 
38 
#ifdef __cplusplus
39 
extern "C" {
40 
#endif
41 
 
42 
/**
43 
 * \fn char **PHYSFS_enumerateFilesWildcard(const char *dir, const char *wildcard, int caseSensitive)
44 
 * \brief Get a file listing of a search path's directory, filtered with a wildcard pattern.
45 
 *
46 
 * Matching directories are interpolated. That is, if "C:\mydir" is in the
47 
 *  search path and contains a directory "savegames" that contains "x.sav",
48 
 *  "y.Sav", and "z.txt", and there is also a "C:\userdir" in the search path
49 
 *  that has a "savegames" subdirectory with "w.sav", then the following code:
50 
 *
51 
 * \code
52 
 * char **rc = PHYSFS_enumerateFilesWildcard("savegames", "*.sav", 0);
53 
 * char **i;
54 
 *
55 
 * for (i = rc; *i != NULL; i++)
56 
 *     printf(" * We've got [%s].\n", *i);
57 
 *
58 
 * PHYSFS_freeList(rc);
59 
 * \endcode
60 
 *
61 
 *  ...will print:
62 
 *
63 
 * \verbatim
64 
 * We've got [x.sav].
65 
 * We've got [y.Sav].
66 
 * We've got [w.sav].\endverbatim
67 
 *
68 
 * Feel free to sort the list however you like. We only promise there will
69 
 *  be no duplicates, but not what order the final list will come back in.
70 
 *
71 
 * Wildcard strings can use the '*' and '?' characters, currently.
72 
 * Matches can be case-insensitive if you pass a zero for argument 3.
73 
 *
74 
 * Don't forget to call PHYSFSEXT_freeEnumerator() with the return value from
75 
 *  this function when you are done with it. As we use PhysicsFS's allocator
76 
 *  for this list, you must free it before calling PHYSFS_deinit().
77 
 *  Do not use PHYSFS_freeList() on the returned value!
78 
 *
79 
 *    \param dir directory in platform-independent notation to enumerate.
80 
 *    \param wildcard Wildcard pattern to use for filtering.
81 
 *    \param caseSensitive Zero for case-insensitive matching,
82 
 *                         non-zero for case-sensitive.
83 
 *   \return Null-terminated array of null-terminated strings.
84 
 *
85 
 * \sa PHYSFSEXT_freeEnumeration
86 
 */
87 
PHYSFS_DECL char **PHYSFSEXT_enumerateFilesWildcard(const char *dir,
88 
                                                   const char *wildcard,
89 
                                                   int caseSensitive);
90 
 
91 
/**
92 
 * \fn void PHYSFSEXT_freeEnumeration(char **list)
93 
 * \brief Free data returned by PHYSFSEXT_enumerateFilesWildcard
94 
 *
95 
 * Conceptually, this works like PHYSFS_freeList(), but is used with data
96 
 *  returned by PHYSFSEXT_enumerateFilesWildcard() only. Be sure to call this
97 
 *  on any returned data from that function before
98 
 *
99 
 *    \param list Pointer previously returned by
100 
 *                PHYSFSEXT_enumerateFilesWildcard(). It is safe to pass a
101 
 *                NULL here.
102 
 *
103 
 * \sa PHYSFSEXT_enumerateFilesWildcard
104 
 */
105 
PHYSFS_DECL void PHYSFSEXT_freeEnumeration(char **list);
106 
 
107 
 
108 
/**
109 
 * \fn void PHYSFSEXT_enumerateFilesCallbackWildcard(const char *dir, const char *wildcard, int caseSensitive, PHYSFS_EnumFilesCallback c, void *d);
110 
 * \brief Get a file listing of a search path's directory, filtered with a wildcard pattern, using an application-defined callback.
111 
 *
112 
 * This function is equivalent to PHYSFSEXT_enumerateFilesWildcard(). It
113 
 *  reports file listings, filtered by a wildcard pattern.
114 
 *
115 
 * Unlike PHYSFS_enumerateFiles(), this function does not return an array.
116 
 *  Rather, it calls a function specified by the application once per
117 
 *  element of the search path:
118 
 *
119 
 * \code
120 
 *
121 
 * static void printDir(void *data, const char *origdir, const char *fname)
122 
 * {
123 
 *     printf(" * We've got [%s] in [%s].\n", fname, origdir);
124 
 * }
125 
 *
126 
 * // ...
127 
 * PHYSFS_enumerateFilesCallbackWildcard("savegames","*.sav",0,printDir,NULL);
128 
 * \endcode
129 
 *
130 
 * Items sent to the callback are not guaranteed to be in any order whatsoever.
131 
 *  There is no sorting done at this level, and if you need that, you should
132 
 *  probably use PHYSFS_enumerateFilesWildcard() instead, which guarantees
133 
 *  alphabetical sorting. This form reports whatever is discovered in each
134 
 *  archive before moving on to the next. Even within one archive, we can't
135 
 *  guarantee what order it will discover data. <em>Any sorting you find in
136 
 *  these callbacks is just pure luck. Do not rely on it.</em> As this walks
137 
 *  the entire list of archives, you may receive duplicate filenames.
138 
 *
139 
 * Wildcard strings can use the '*' and '?' characters, currently.
140 
 * Matches can be case-insensitive if you pass a zero for argument 3.
141 
 *
142 
 *    \param dir Directory, in platform-independent notation, to enumerate.
143 
 *    \param wildcard Wildcard pattern to use for filtering.
144 
 *    \param caseSensitive Zero for case-insensitive matching,
145 
 *                         non-zero for case-sensitive.
146 
 *    \param c Callback function to notify about search path elements.
147 
 *    \param d Application-defined data passed to callback. Can be NULL.
148 
 *
149 
 * \sa PHYSFS_EnumFilesCallback
150 
 * \sa PHYSFS_enumerateFiles
151 
 */
152 
PHYSFS_DECL void PHYSFSEXT_enumerateFilesCallbackWildcard(const char *dir,
153 
                                              const char *wildcard,
154 
                                              int caseSensitive,
155 
                                              PHYSFS_EnumFilesCallback c,
156 
                                              void *d);
157 
 
158 
#ifdef __cplusplus
159 
}
160 
#endif
161 
 
162 
#endif  /* include-once blocker. */
163 
 
164 
/* end of globbing.h ... */
165