From 6ee992c1d929d7f57e25442636c3a89be9d8f965 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Mon, 2 Apr 2007 23:35:09 +0000 Subject: [PATCH] Improved Doxygen comments. --- CHANGELOG.txt | 3 +- physfs.h | 179 ++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 175 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 65ec6458..b7fa2e63 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -2,7 +2,8 @@ * CHANGELOG. */ -04022007 - Added wxWidgets-based test program (incomplete). +04022007 - Added wxWidgets-based test program (incomplete). Filled in and + corrected some Doxygen comments. 04012007 - Added PHYSFS_isInit() and PHYSFS_symbolicLinksPermitted() functions. 03312007 - Added a quick'n'dirty unpack utility to the extras directory. Moved DIR archiver to start of the list, so we don't have to have every diff --git a/physfs.h b/physfs.h index 5d7cf79e..be1dcf46 100644 --- a/physfs.h +++ b/physfs.h @@ -639,7 +639,12 @@ __EXPORT__ void PHYSFS_permitSymbolicLinks(int allow); * E: has a disc in it, then that's all you get. If the user inserts a disc * in D: and you call this function again, you get both drives. If, on a * Unix box, the user unmounts a disc and remounts it elsewhere, the next - * call to this function will reflect that change. Fun. + * call to this function will reflect that change. + * + * This function refers to "CD-ROM" media, but it really means "inserted disc + * media," such as DVD-ROM, HD-DVD, CDRW, and Blu-Ray discs. It looks for + * filesystems, and as such won't report an audio CD, unless there's a + * mounted filesystem track on it. * * The returned value is an array of strings, with a NULL entry to signify the * end of the list: @@ -2009,7 +2014,7 @@ __EXPORT__ int PHYSFS_setAllocator(const PHYSFS_Allocator *allocator); /** - * \fn int PHYSFS_mount(const char *newDir, const char *mountPoint, int appendToPath); + * \fn int PHYSFS_mount(const char *newDir, const char *mountPoint, int appendToPath) * \brief Add an archive or directory to the search path. * * If this is a duplicate, the entry is not added again, even though the @@ -2051,7 +2056,7 @@ __EXPORT__ int PHYSFS_setAllocator(const PHYSFS_Allocator *allocator); __EXPORT__ int PHYSFS_mount(const char *newDir, const char *mountPoint, int appendToPath); /** - * \fn int PHYSFS_getMountPoint(const char *dir); + * \fn int PHYSFS_getMountPoint(const char *dir) * \brief Determine a mounted archive's mountpoint. * * You give this function the name of an archive or dir you successfully @@ -2075,14 +2080,176 @@ __EXPORT__ int PHYSFS_mount(const char *newDir, const char *mountPoint, int appe __EXPORT__ const char *PHYSFS_getMountPoint(const char *dir); -/* !!! FIXME: comment! */ -typedef void (*PHYSFS_StringCallback)(void *, const char *); -typedef void (*PHYSFS_EnumFilesCallback)(void *, const char *, const char *); +/** + * \typedef PHYSFS_StringCallback + * \brief Function signature for callbacks that report strings. + * + * These are used to report a list of strings to an original caller, one + * string per callback. All strings are UTF-8 encoded. Functions should not + * try to modify or free the string's memory. + * + * These callbacks are used, starting in PhysicsFS 1.1, as an alternative to + * functions that would return lists that need to be cleaned up with + * PHYSFS_freeList(). The callback means that the library doesn't need to + * allocate an entire list and all the strings up front. + * + * Be aware that promises data ordering in the list versions are not + * necessarily so in the callback versions. Check the documentation on + * specific APIs, but strings may not be sorted as you expect. + * + * \param data User-defined data pointer, passed through from the API + * that eventually called the callback. + * \param str The string data about which the callback is meant to inform. + * + * \sa PHYSFS_getCdRomDirsCallback + * \sa PHYSFS_getSearchPathCallback + */ +typedef void (*PHYSFS_StringCallback)(void *data, const char *str); + +/** + * \typedef PHYSFS_EnumFilesCallback + * \brief Function signature for callbacks that enumerate files. + * + * These are used to report a list of directory entries to an original caller, + * one file/dir/symlink per callback. All strings are UTF-8 encoded. + * Functions should not try to modify or free any string's memory. + * + * These callbacks are used, starting in PhysicsFS 1.1, as an alternative to + * functions that would return lists that need to be cleaned up with + * PHYSFS_freeList(). The callback means that the library doesn't need to + * allocate an entire list and all the strings up front. + * + * Be aware that promises data ordering in the list versions are not + * necessarily so in the callback versions. Check the documentation on + * specific APIs, but strings may not be sorted as you expect. + * + * \param data User-defined data pointer, passed through from the API + * that eventually called the callback. + * \param origdir A string containing the full path, in platform-independent + * notation, of the directory containing this file. In most + * cases, this is the directory on which you requested + * enumeration, passed in the callback for your convenience. + * \param fname The filename that is being enumerated. It may not be in + * alphabetical order compared to other callbacks that have + * fired, and it will not contain the full path. You can + * recreate the fullpath with $origdir/$fname ... The file + * can be a subdirectory, a file, a symlink, etc. + * + * \sa PHYSFS_enumerateFilesCallback + */ +typedef void (*PHYSFS_EnumFilesCallback)(void *data, const char *origdir, + const char *fname); + + +/** + * \fn void PHYSFS_getCdRomDirsCallback(PHYSFS_StringCallback c, void *d) + * \brief Enumerate CD-ROM directories, using an application-defined callback. + * + * Internally, PHYSFS_getCdRomDirs() 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_getCdRomDirs(), this function does not return an array. + * Rather, it calls a function specified by the application once per + * detected disc: + * + * \code + * + * static void foundDisc(void *data, const char *cddir) + * { + * printf("cdrom dir [%s] is available.\n", cddir); + * } + * + * // ... + * PHYSFS_getCdRomDirsCallback(foundDisc, NULL); + * \endcode + * + * This call may block while drives spin up. Be forewarned. + * + * \param c Callback function to notify about detected drives. + * \param d Application-defined data passed to callback. Can be NULL. + * + * \sa PHYSFS_StringCallback + * \sa PHYSFS_getCdRomDirs + */ __EXPORT__ void PHYSFS_getCdRomDirsCallback(PHYSFS_StringCallback c, void *d); + +/** + * \fn void PHYSFS_getSearchPathCallback(PHYSFS_StringCallback c, void *d) + * \brief Enumerate the search path, using an application-defined callback. + * + * Internally, PHYSFS_getSearchPath() 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_getSearchPath(), 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 void printSearchPath(void *data, const char *pathItem) + * { + * printf("[%s] is in the search path.\n", pathItem); + * } + * + * // ... + * PHYSFS_getSearchPathCallback(printSearchPath, NULL); + * \endcode + * + * Elements of the search path are reported in order search priority, so the + * first archive/dir that would be examined when looking for a file is the + * first element passed through the callback. + * + * \param c Callback function to notify about search path elements. + * \param d Application-defined data passed to callback. Can be NULL. + * + * \sa PHYSFS_StringCallback + * \sa PHYSFS_getSearchPath + */ __EXPORT__ void PHYSFS_getSearchPathCallback(PHYSFS_StringCallback c, void *d); + +/** + * \fn void PHYSFS_enumerateFilesCallback(const char *dir, PHYSFS_EnumFilesCallback c, void *d) + * \brief Get a file listing of a search path's directory, using an application-defined callback. + * + * 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 void printDir(void *data, const char *origdir, const char *fname) + * { + * printf(" * We've got [%s] in [%s].\n", fname, origdir); + * } + * + * // ... + * PHYSFS_enumerateFilesCallback("/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. + * + * \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. + * + * \sa PHYSFS_EnumFilesCallback + * \sa PHYSFS_enumerateFiles + */ __EXPORT__ void PHYSFS_enumerateFilesCallback(const char *dir, PHYSFS_EnumFilesCallback c, void *d);