Function physfs_sys::PHYSFS_enumerate

pub unsafe extern "C" fn PHYSFS_enumerate(
    dir: *const c_char, 
    c: PHYSFS_EnumerateCallback, 
    d: *mut c_void
) -> c_int

\fn int PHYSFS_enumerate(const char *dir, PHYSFS_EnumerateCallback c, void *d) \brief Get a file listing of a search path’s directory, using an application-defined callback, with errors reported.

Internally, PHYSFS_enumerateFiles() just calls this function and then builds a list before returning to the application, so functionality is identical except for how the information is represented to the application.

Unlike PHYSFS_enumerateFiles(), this function does not return an array. Rather, it calls a function specified by the application once per element of the search path:

\code

static int printDir(void *data, const char *origdir, const char *fname) { printf(“ * We’ve got [%s] in [%s].\n“, fname, origdir); return 1; // give me more data, please. }

// … PHYSFS_enumerate(“/some/path”, printDir, NULL); \endcode

Items sent to the callback are not guaranteed to be in any order whatsoever. There is no sorting done at this level, and if you need that, you should probably use PHYSFS_enumerateFiles() instead, which guarantees alphabetical sorting. This form reports whatever is discovered in each archive before moving on to the next. Even within one archive, we can’t guarantee what order it will discover data. Any sorting you find in these callbacks is just pure luck. Do not rely on it. As this walks the entire list of archives, you may receive duplicate filenames.

This API and the callbacks themselves are capable of reporting errors. Prior to this API, callbacks had to accept every enumerated item, even if they were only looking for a specific thing and wanted to stop after that, or had a serious error and couldn’t alert anyone. Furthermore, if PhysicsFS itself had a problem (disk error or whatnot), it couldn’t report it to the calling app, it would just have to skip items or stop enumerating outright, and the caller wouldn’t know it had lost some data along the way.

Now the caller can be sure it got a complete data set, and its callback has control if it wants enumeration to stop early. See the documentation for PHYSFS_EnumerateCallback for details on how your callback should behave.

\param dir Directory, in platform-independent notation, to enumerate. \param c Callback function to notify about search path elements. \param d Application-defined data passed to callback. Can be NULL. \return non-zero on success, zero on failure. Use PHYSFS_getLastErrorCode() to obtain the specific error. If the callback returns PHYSFS_ENUM_STOP to stop early, this will be considered success. Callbacks returning PHYSFS_ENUM_ERROR will make this function return zero and set the error code to PHYSFS_ERR_APP_CALLBACK.

\sa PHYSFS_EnumerateCallback \sa PHYSFS_enumerateFiles