r893 - trunk
DONOTREPLY at icculus.org
DONOTREPLY at icculus.org
Mon Apr 2 19:35:09 EDT 2007
Author: icculus
Date: 2007-04-02 19:35:09 -0400 (Mon, 02 Apr 2007)
New Revision: 893
Modified:
trunk/CHANGELOG.txt
trunk/physfs.h
Log:
Improved Doxygen comments.
Modified: trunk/CHANGELOG.txt
===================================================================
--- trunk/CHANGELOG.txt 2007-04-02 21:08:05 UTC (rev 892)
+++ trunk/CHANGELOG.txt 2007-04-02 23:35:09 UTC (rev 893)
@@ -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
Modified: trunk/physfs.h
===================================================================
--- trunk/physfs.h 2007-04-02 21:08:05 UTC (rev 892)
+++ trunk/physfs.h 2007-04-02 23:35:09 UTC (rev 893)
@@ -639,8 +639,13 @@
* 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 @@
/**
- * \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_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__ 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. <em>Any sorting you find in
+ * these callbacks is just pure luck. Do not rely on it.</em>
+ *
+ * \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);
More information about the physfs-commits
mailing list