Fixed typos, expanded documentation, added init and deinit functions, and
some more !!! todos.
This commit is contained in:
Ryan C. Gordon
parent
de901e4d7f
commit
d41c242619
97
physfs.h
97
physfs.h
|
|
@ -5,17 +5,17 @@
|
|||
* stdio or system i/o calls. The brief benefits:
|
||||
*
|
||||
* - It's portable.
|
||||
* - It can handle byte ordering on alternative processors.
|
||||
* - It's safe. No file access is permitted outside the specified dirs.
|
||||
* - It can handle byte ordering on alternative processors.
|
||||
* - It's flexible. Archives (.ZIP files) can be used transparently as
|
||||
* directory structures.
|
||||
*
|
||||
* This system is largely inspired by Quake 3's PK3 files and the related
|
||||
* fs_* cvars. If you've ever tinkered with these, then this API will be very
|
||||
* fs_* cvars. If you've ever tinkered with these, then this API will be
|
||||
* familiar to you.
|
||||
*
|
||||
* With the PhysicsFS, you have a single writing directory and multiple
|
||||
* "search paths" for reading. You can think of this as a filesystem within a
|
||||
* With PhysicsFS, you have a single writing path and multiple "search paths"
|
||||
* for reading. You can think of this as a filesystem within a
|
||||
* filesystem. If (on Windows) you were to set the writing directory to
|
||||
* "C:\MyGame\MyWritingDirectory", then no PHYSFS calls could touch anything
|
||||
* above this directory, including the "C:\MyGame" and "C:\" directories.
|
||||
|
|
@ -35,7 +35,12 @@
|
|||
* specify it like it was on a Unix filesystem: if you want to write to
|
||||
* "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write path to
|
||||
* "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
|
||||
* abstraction across all platforms.
|
||||
* abstraction across all platforms. Specifying a file in this way is termed
|
||||
* "platform-independent notation" in this documentation. Specifying a path
|
||||
* as "C:\mydir\myfile" or "MacOS hard drive:My Directory:My File" is termed
|
||||
* "platform-dependent notation". The only time you use platform-dependent
|
||||
* notation is when setting up your write and search paths; after that, all
|
||||
* file access into those paths are done with platform-independent notation.
|
||||
*
|
||||
* All files opened for writing are opened in relation to the write path,
|
||||
* which is the root of the writable filesystem. When opening a file for
|
||||
|
|
@ -55,12 +60,14 @@
|
|||
* C:\mygame\installeddatafiles.zip
|
||||
*
|
||||
* Then a call to PHYSFS_openread("textfiles/myfile.txt") (note the directory
|
||||
* separator) will check for C:\mygame\textfiles\myfile.txt, then
|
||||
* separator, lack of drive letter, and lack of dir separator at the start of
|
||||
* the string; this is platform-independent notation) will check for
|
||||
* C:\mygame\textfiles\myfile.txt, then
|
||||
* C:\mygame\myuserfiles\textfiles\myfile.txt, then
|
||||
* D:\mygamescdromdatafiles\textfiles\myfile.txt, then, finally, for
|
||||
* textfiles\myfile.txt inside of C:\mygame\installeddatafiles.zip. Remember
|
||||
* that most archive types and platform filesystems store their filenames in
|
||||
* a case-sensitive manner.
|
||||
* a case-sensitive manner, so you should be careful to specify it correctly.
|
||||
*
|
||||
* Files opened through PhysicsFS may NOT contain "." or ".." as path
|
||||
* elements. Not only are these meaningless on MacOS, they are a security
|
||||
|
|
@ -119,11 +126,35 @@ extern "C" {
|
|||
|
||||
/* functions... */
|
||||
|
||||
/**
|
||||
* Initialize PhysicsFS. This must be called before any other PhysicsFS
|
||||
* function (except PHYSFS_getLastError()).
|
||||
*
|
||||
* @param argv0 the argv[0] string passed to your program's mainline.
|
||||
* @return nonzero on success, zero on error. Specifics of the error can be
|
||||
* gleaned from PHYSFS_getLastError().
|
||||
*/
|
||||
int PHYSFS_init(const char *argv0);
|
||||
|
||||
|
||||
/**
|
||||
* Shutdown PhysicsFS. This closes any files opened via PhysicsFS, blanks the
|
||||
* search/write paths, frees memory, and invalidates all your handles.
|
||||
*
|
||||
* Once deinitialized, PHYSFS_init() can be called again to restart the
|
||||
* subsystem.
|
||||
*
|
||||
* @return nonzero on success, zero on error. Specifics of the error can be
|
||||
* gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
|
||||
* undefined, and probably badly screwed up.
|
||||
*/
|
||||
void PHYSFS_deinit(void);
|
||||
|
||||
|
||||
/**
|
||||
* Get the last PhysicsFS error message as a null-terminated string.
|
||||
* This will be NULL if there's been no error since the last call to this
|
||||
* function. The pointer returned by this call points to a static buffer
|
||||
* function. The pointer returned by this call points to a static
|
||||
* internal buffer, and this call is not thread safe.
|
||||
*
|
||||
* @return READ ONLY string of last error message.
|
||||
|
|
@ -136,8 +167,9 @@ const char *PHYSFS_getLastError(void);
|
|||
* and ":" on MacOS. It may be more than one character, depending on the
|
||||
* platform, and your code should take that into account. Note that this is
|
||||
* only useful for setting up the search/write paths, since access into those
|
||||
* paths always use '/' to separate directories. This is also handy for
|
||||
* getting platform-independent access when using stdio calls.
|
||||
* paths always use '/' (platform-independent notation) to separate
|
||||
* directories. This is also handy for getting platform-independent access
|
||||
* when using stdio calls.
|
||||
*
|
||||
* @return READ ONLY null-terminated string of platform's path separator.
|
||||
*/
|
||||
|
|
@ -165,7 +197,7 @@ const char *PHYSFS_getPathSeparator(void);
|
|||
*
|
||||
* // lock thread here, if needed.
|
||||
*
|
||||
* for (i = PHYSFS__getCdRomPaths(); *i != NULL; i++)
|
||||
* for (i = PHYSFS_getCdRomPaths(); *i != NULL; i++)
|
||||
* printf("cdrom path [%s] is available.\n", *i);
|
||||
*
|
||||
* // unlock thread here, if needed.
|
||||
|
|
@ -256,7 +288,7 @@ int PHYSFS_addToSearchPath(const char *newPath, int appendToPath);
|
|||
|
||||
|
||||
/**
|
||||
* Remove a directory or archive to the search path.
|
||||
* Remove a directory or archive from the search path.
|
||||
*
|
||||
* This must be a (case-sensitive) match to a dir or archive already in the
|
||||
* search path, specified in platform-dependent notation.
|
||||
|
|
@ -307,12 +339,12 @@ const char **PHYSFS_getSearchPath(void);
|
|||
*
|
||||
* The search path will be:
|
||||
*
|
||||
* - The Write Path
|
||||
* - The Write Path/appName
|
||||
* - The Write Path (created if it doesn't exist)
|
||||
* - The Write Path/appName (created if it doesn't exist)
|
||||
* - The Base Path (PHYSFS_getBasePath())
|
||||
* - The Base Path/appName
|
||||
* - The Base Path/appName (if it exists)
|
||||
* - All found CD-ROM paths (optionally)
|
||||
* - All found CD-ROM paths/appName (optionally)
|
||||
* - All found CD-ROM paths/appName (optionally, and if they exist)
|
||||
*
|
||||
* These directories are then searched for files ending with the extension
|
||||
* (archiveExt), which, if they are valid and supported archives, will also
|
||||
|
|
@ -322,7 +354,7 @@ const char **PHYSFS_getSearchPath(void);
|
|||
* order, regardless of which directories they were found in.
|
||||
*
|
||||
* All of this can be accomplished from the application, but this just does it
|
||||
* all for you.
|
||||
* all for you. Feel free to add more to the search path manually, too.
|
||||
*
|
||||
* @param appName Program-specific name of your program, to separate it
|
||||
* from other programs using PhysicsFS.
|
||||
|
|
@ -333,15 +365,16 @@ const char **PHYSFS_getSearchPath(void);
|
|||
* archives automatically.
|
||||
*
|
||||
* @param includeCdRoms Non-zero to include CD-ROMs in the search path, and
|
||||
* search them for archives. This may cause a
|
||||
* significant amount of blocking while discs are
|
||||
* accessed, and if there are no discs in the drive
|
||||
* (or even not mounted on Unix systems), then they
|
||||
* may not be made available anyhow. You may want to
|
||||
* specify zero and handle the disc setup yourself.
|
||||
* (if (archiveExt) != NULL) search them for archives.
|
||||
* This may cause a significant amount of blocking
|
||||
* while discs are accessed, and if there are no discs
|
||||
* in the drive (or even not mounted on Unix systems),
|
||||
* then they may not be made available anyhow. You may
|
||||
* want to specify zero and handle the disc setup
|
||||
* yourself.
|
||||
*
|
||||
* @param archivesFirst Non-zero to prepend the archives to the search path.
|
||||
* Zero to append them.
|
||||
* Zero to append them. Ignored if !(archiveExt).
|
||||
*/
|
||||
void PHYSFS_setSanePaths(const char *appName, const char *archiveExt,
|
||||
int includeCdRoms, int archivesFirst);
|
||||
|
|
@ -377,6 +410,10 @@ int PHYSFS_mkdir(const char *dirName);
|
|||
* physical filesystem, if it exists and the operating system permits the
|
||||
* deletion.
|
||||
*
|
||||
* Note that on Unix systems, deleting a file may be successful, but the
|
||||
* actual file won't be removed until all processes that have an open
|
||||
* filehandle to it (including your program) close their handles.
|
||||
*
|
||||
* @param filename Filename to delete.
|
||||
* @return nonzero on success, zero on error. Specifics of the error can be
|
||||
* gleaned from PHYSFS_getLastError().
|
||||
|
|
@ -400,6 +437,10 @@ int PHYSFS_delete(const char *filename);
|
|||
* directories) is removed from the physical filesystem, if it exists and the
|
||||
* operating system permits the deletion.
|
||||
*
|
||||
* Note that on Unix systems, deleting a file may be successful, but the
|
||||
* actual file won't be removed until all processes that have an open
|
||||
* filehandle to it (including your program) close their handles.
|
||||
*
|
||||
* @param filename root of directory tree to delete.
|
||||
* @return nonzero on success, zero on error. Specifics of the error can be
|
||||
* gleaned from PHYSFS_getLastError().
|
||||
|
|
@ -433,7 +474,8 @@ void PHYSFS_permitSymbolicLinks(int allow);
|
|||
|
||||
/**
|
||||
* Determine if a file exists. Just because it exists does NOT mean that you
|
||||
* will have access to read or write it.
|
||||
* will have access to read or write it, or that it will continue to exist
|
||||
* after this call (as other processes may delete it on multitasking systems).
|
||||
*
|
||||
* @param filename a file in platform-independent notation.
|
||||
* @param inWritePath nonzero to check write path, zero to check search path.
|
||||
|
|
@ -454,6 +496,9 @@ int PHYSFS_exists(const char *filename, int inWritePath);
|
|||
* path and C:\mygame\maps\level1.map exists, then buffer will be filled in
|
||||
* with "C:\mygame\maps\level1.map" and the function returns nonzero.
|
||||
*
|
||||
* If a match is a symbolic link, and you've not explicitly permitted symlinks,
|
||||
* then it will be ignored, and the search for a match will continue.
|
||||
*
|
||||
* @param buffer pointer to buffer to fill with path.
|
||||
* @param bufsize size of buffer pointed to by (buffer).
|
||||
* @param filename file to look for.
|
||||
|
|
@ -587,6 +632,8 @@ int PHYSFS_writeBE16(void *handle, int buffer);
|
|||
int PHYSFS_writeBE32(void *handle, int buffer);
|
||||
*/
|
||||
|
||||
/* !!! need way to enumerate the contents of a directory. */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
|
|
|||
Loading…
Reference in New Issue