LDK: LDK::VFileSystem Class Reference

With PhysicsFS, you have a single writing directory and multiple directories (the "search path") 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. This prevents an application's internal scripting language from piddling over c:\config.sys, for example. If you'd rather give PHYSFS full access to the system's REAL file system, set the writing dir to "C:\", but that's generally A Bad Thing for several reasons.

Drive letters are hidden in PhysicsFS once you set up your initial paths. The search path creates a single, hierarchical directory structure. Not only does this lend itself well to general abstraction with archives, it also gives better support to operating systems like MacOS and Unix. Generally speaking, you shouldn't ever hardcode a drive letter; not only does this hurt portability to non-Microsoft OSes, but it limits your win32 users to a single drive, too. Use the PhysicsFS abstraction functions and allow user-defined configuration options, too. When opening a file, you 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 dir to "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an abstraction across all platforms. Specifying a file in this way is termed "platform-independent notation" in this documentation. Specifying a a filename in a form such 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 directory and search path; after that, all file access into those directories are done with platform-independent notation.

All files opened for writing are opened in relation to the write directory, which is the root of the writable filesystem. When opening a file for reading, PhysicsFS goes through the search path. This is NOT the same thing as the PATH environment variable. An application using PhysicsFS specifies directories to be searched which may be actual directories, or archive files that contain files and subdirectories of their own. See the end of these docs for currently supported archive formats.

Once the search path is defined, you may open files for reading. If you've got the following search path defined (to use a win32 example again):

Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory 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, so you should be careful to specify it correctly.

Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir elements. Not only are these meaningless on MacOS and/or Unix, they are a security hole. Also, symbolic links (which can be found in some archive types and directly in the filesystem on Unix platforms) are NOT followed.

The write dir is not included in the search path unless you specifically add it. While you CAN change the write dir as many times as you like, you should probably set it once and stick to it. Remember that your program will not have permission to write in every directory on Unix and NT systems.

PhysicsFS has some convenience functions for platform-independence. There is a function to tell you the current platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS), which is needed only to set up your search/write paths. There is a function to tell you what CD-ROM drives contain accessible discs, and a function to recommend a good search path, etc.

A recommended order for the search path is the write dir, then the base dir, then the cdrom dir, then any archives discovered. Quake 3 does something like this, but moves the archives to the start of the search path. Build Engine games, like Duke Nukem 3D and Blood, place the archives last, and use the base dir for both searching and writing. There is a helper method (defaultConfig()) that puts together a basic configuration for you, based on a few parameters. Also see the comments on baseDir(), and userDir() for info on what those are and how they can help you determine an optimal search path.

Note that archives need not be named as such: if you have a ZIP file and rename it with a .PKG extension, the file will still be recognized as a ZIP archive by PhysicsFS; the file's contents are used to determine its type.

Member Function Documentation

static SmartFile LDK::VFileSystem::stdIn ( ) [inline, static]

Gets the VFile used for standard input. Defaults to the normal c stdin (but setup with locking).

Returns:: A reference to the VFile.

Definition at line 194 of file VFileSystem.h.

static SmartFile LDK::VFileSystem::stdOut ( ) [inline, static]

Gets the VFile used for standard output. Defaults to the normal c stdout (but setup with locking).

Returns:: A reference to the VFile.

Definition at line 201 of file VFileSystem.h.

static SmartFile LDK::VFileSystem::stdErr ( ) [inline, static]

Gets the VFile used for standard error. Defaults to the normal c stderr (but setup with locking).

Returns:: A reference to the VFile.

Definition at line 208 of file VFileSystem.h.

static void LDK::VFileSystem::stdIn ( SmartFile f ) [inline, static]

Replace the current stdIn. Deletes the old one. Increments the reference count on f, so it will never be deleted by a smart pointer.

Parameters:

The file to use.

Exceptions:

NullPtrError

if f contains a NULL pointer.

Definition at line 217 of file VFileSystem.h.

static void LDK::VFileSystem::stdOut ( SmartFile f ) [inline, static]

Replace the current stdOut. Deletes the old one.Increments the reference count on f, so it will never be deleted by a smart pointer.

Parameters:

The file to use.

Exceptions:

NullPtrError

if f contains a NULL pointer.

Definition at line 226 of file VFileSystem.h.

static void LDK::VFileSystem::stdErr ( SmartFile f ) [inline, static]

Replace the current stdErr. Deletes the old one. Increments the reference count on f, so it will never be deleted by a smart pointer.

Parameters:

The file to use.

Exceptions:

NullPtrError

if f contains a NULL pointer.

Definition at line 235 of file VFileSystem.h.

static void LDK::VFileSystem::defaultConfig	(	const char *	organisation,
		const char *	appName,
		const char *	archiveExt,
		bool	includeCdRoms,
		bool	archivesFirst
	)			`[static]`

The write dir will be set to "userdir/.organization/appName", which is created if it doesn't exist.

The above is sufficient to make sure your program's configuration directory is separated from other clutter, and platform-independent. The period before "mygame" hides the directory on Unix systems.

The search path will be:

The Write Dir (created if it doesn't exist)
The Base Dir
All found CD-ROM dirs (optionally)

These directories are then searched for files ending with the extension (archiveExt), which, if they are valid and supported archives, will also be added to the search path. If you specified "PKG" for (archiveExt), and there's a file named data.PKG in the base dir, it'll be checked. Archives can either be appended or prepended to the search path in alphabetical 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. Feel free to add more to the search path manually, too.

Parameters:

	organisation	Name of your company/group/etc to be used as a dirname, so keep it small, and no-frills.
	appName	Program-specific name of your program, to separate it from other programs using PhysicsFS.
	archiveExt	File extension used by your program to specify an archive. For example, Quake 3 uses "pk3", even though they are just zipfiles. Specify NULL to not dig out archives automatically. Do not specify the '.' char; If you want to look for ZIP files, specify "ZIP" and not ".ZIP" ... the archive search is case-insensitive.
	includeCdRoms	true to include CD-ROMs in the search path, and (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.
	archivesFirst	true to prepend the archives to the search path. False to append them. Ignored if !(archiveExt).

Exceptions:

	NullPointerError	if organisation or appName are NULL.
	RuntimeError	if there is some other error.

static void LDK::VFileSystem::addToSearchPath	(	const char *	dirName,
		bool	append = `true`
	)			`[static]`

If this is a duplicate, the entry is not added again, even though the function succeeds.

Parameters:

	dirName	directory or archive to add to the path, in platform-dependent notation.
	append	true to append to search path, false to prepend.

Exceptions:

	NullPtrError	is dirName is NULL.
	RuntimeError	if there is some other error.

static void LDK::VFileSystem::removeFromSearchPath ( const char * dirName ) [static]

This must be a (case-sensitive) match to a dir or archive already in the search path, specified in platform-dependent notation. This call will fail (and fail to remove from the path) if the element still has files open in it.

Parameters:

dirName

dir/archive to remove.

Exceptions:

	NullPtrError	is dirName is NULL.
	RuntimeError	if there is some other error.

static void LDK::VFileSystem::writeDir ( const char * dirName ) [static]

Set a new write dir. This will override the previous setting. If the directory or a parent directory doesn't exist in the physical filesystem, PhysicsFS will attempt to create them as needed. This call will fail (and fail to change the write dir) if the current write dir still has files open in it.

Parameters:

dirName

The new directory to be the root of the write dir, specified in platform-dependent notation. Setting to NULL disables the write dir, so no files can be opened for writing via PhysicsFS.

Exceptions:

	NullPtrError	if dirName is NULL.
	RuntimeError	if there is some other error.

static const char* LDK::VFileSystem::writeDir ( ) [static]

Get the current write dir. The default write dir is NULL.

Returns:: The write dir in platform-dependent notation or NULL if no write path is currently set.

static SmartFile LDK::VFileSystem::openRead	(	const char *	fileName,
		bool	text
	)			`[static]`

Open a file for reading, in platform-independent notation. The search path is checked one at a time until a matching file is found, in which case an abstract filehandle is associated with it, and reading may be done. The reading offset is set to the first byte of the file. Passes through exceptions from VFile::openRead()

Exceptions:

NullPtrError

if fileName is NULL.

static SmartFile LDK::VFileSystem::openWrite	(	const char *	fileName,
		bool	text
	)			`[static]`

Open a file for writing, in platform-independent notation and in relation to the write dir as the root of the writable filesystem. The specified file is created if it doesn't exist. If it does exist, it is truncated to zero bytes, and the writing offset is set to the start. Passes through exceptions from VFile::openWrite()

Exceptions:

NullPtrError

if fileName is NULL.

static SmartFile LDK::VFileSystem::openAppend	(	const char *	fileName,
		bool	text
	)			`[static]`

Open a file for writing, in platform-independent notation and in relation to the write dir as the root of the writable filesystem. The specified file is created if it doesn't exist. If it does exist, the writing offset is set to the end of the file, so the first write will be the byte after the end. Passes through exceptions from VFile::openAppend()

Exceptions:

NullPtrError

if fileName is NULL.

static SmartStringVec LDK::VFileSystem::searchDirs ( ) [static]

The default search path list is empty.

Returns:: SmartPointer to a vector of strings containing the search paths.

Exceptions:

BadAllocError

if there is not enough memory to allocate the return value.

static SmartStringVec LDK::VFileSystem::cdRomDirs ( ) [static]

The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or whatnot on Unix). Dirs are only returned if there is a disc ready and accessible in the drive. So if you've got two drives (D: and E:), and only 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. This call may block while drives spin up. Be forewarned.

Returns:: SmartPointer to a vector of strings containing the cdRom paths.

Exceptions:

BadAllocError

if there is not enough memory to allocate the return value.

static SmartStringVec LDK::VFileSystem::enumerateFiles ( const char * dir ) [static]

Matching directories are interpolated. That is, if "C:\mydir" is in the search path and contains a directory "savegames" that contains "x.sav", "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path that has a "savegames" subdirectory with "w.sav", then the following code:

 SmartStringVec v = VFileSystem::enumerateFiles("savegames");
 StringVec::iterator i;

 for(i = v->begin(); i != v->end(); i++)
     stdOut().printf(" * We've got [%s].\n", (*i).c_str());

...will print:

    /// We've got [x.sav].
    /// We've got [y.sav].
    /// We've got [z.sav].
    /// We've got [w.sav].
    ///

There will be no duplicates in the SmartStringVec, and it will not be sorted.

Parameters:

dir

directory in platform-independent notation to enumerate.

Returns:: SmartPointer to a vector of strings containing the files found.

Exceptions:

	NullPtrError	if dir is NULL.
	BadAllocError	if there is not enough memory to allocate the return value.

static const char* LDK::VFileSystem::dirSeperator ( ) [static]

This returns "\\\\" on win32, "/" on Unix, 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 dirs always use '/' (platform-independent notation) to separate directories. This is also handy for getting platform-independent access when using stdio calls.

Returns:: The platform's dir separator.

static const char* LDK::VFileSystem::baseDir ( ) [static]

Get the "base dir". This is the directory where the application was run from, which is probably the installation directory, and may or may not be the process's current working directory. You should probably use the base dir in your search path.

Returns:: the base directory in platform dependant notation.

static const char* LDK::VFileSystem::userDir ( ) [static]

Get the "user dir". This is meant to be a suggestion of where a specific user of the system can store files. On Unix, this is her home directory. On systems with no concept of multiple home directories (MacOS, win95), this will default to something like "C:\mybasedir\users\username" where "username" will either be the login name, or "default" if the platform doesn't support multiple users, either. You should probably use the user dir as the basis for your write dir, and also put it near the beginning of your search path.

Returns:: the user directory in platform dependant notation.

static void LDK::VFileSystem::makeDir ( const char * dirName ) [static]

This is specified in platform-independent notation in relation to the write dir. All missing parent directories are also created if they don't exist. So if you've got the write dir set to "C:\mygame\writedir" and call PHYSFS_mkdir("downloads/maps") then the directories "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps" will be created if possible. If the creation of "maps" fails after we have successfully created "downloads", then the function leaves the created directory behind and reports failure.

Parameters:

dirName

New dir to create.

Exceptions:

	NullPtrError	if dirName is NULL.
	RuntimeError	if there is some other error.

static bool LDK::VFileSystem::isDir ( const char * fileName ) [static]

Determine if the first occurence of (fname) in the search path is really a directory entry. *

Parameters:

fileName

filename in platform-independent notation.

Returns:: true if filename exists and is a directory, false otherwise.

Exceptions:

NullPtrError

if fileName is NULL.

static void LDK::VFileSystem::deleteFile ( const char * fileName ) [static]

fileName is specified in platform-independent notation in relation to the write dir. A directory must be empty before this call can delete it. So if you've got the write dir set to "C:\mygame\writedir" and call delete("downloads/maps/level1.map") then the file "C:\mygame\writedir\downloads\maps\level1.map" 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. Chances are, the bits that make up the file still exist, they are just made available to be written over at a later point. Don't consider this a security method or anything. :)

Parameters:

fileName

Filename to delete.

static const char* LDK::VFileSystem::realDirectory ( const char * fileName ) [static]

The file is specified in platform-independent notation. The returned filename will be the element of the search path where the file was found, which may be a directory, or an archive. Even if there are multiple matches in different parts of the search path, only the first one found is used, just like when opening a file. Note that entries that are symlinks are ignored.

So, if you look for "maps/level1.map", and C:\mygame is in your search path and C:\mygame\maps\level1.map exists, then "C:\mygame" is returned.

Parameters:

fileName

file to look for.

Returns:: String of element of search path containing the file in question. NULL if not found.


Static Public Member Functions
static void	initialise (const char *argv0)
static SmartFile	stdIn ()
	Gets stdIn.
static SmartFile	stdOut ()
	Gets stdOut.
static SmartFile	stdErr ()
	Gets stdErr.
static void	stdIn (SmartFile f)
	Set stdin.
static void	stdOut (SmartFile f)
	Set stdout.
static void	stdErr (SmartFile f)
	Set stderr.
static void	defaultConfig (const char organisation, const char appName, const char *archiveExt, bool includeCdRoms, bool archivesFirst)
	set a sensible default config.
static void	addToSearchPath (const char *dirName, bool append=true)
	Add an archive or directory to the search path.
static void	removeFromSearchPath (const char *dirName)
	Remove a directory or archive from the search path.
static void	writeDir (const char *dirName)
	Tell PhysicsFS where it may write files.
static const char *	writeDir ()
	Get the current write directory.
static SmartFile	openRead (const char *fileName, bool text)
	Open a file for reading.
static SmartFile	openWrite (const char *fileName, bool text)
	Open a file for appending.
static SmartFile	openAppend (const char *fileName, bool text)
	Open a file for appending.
static SmartStringVec	searchDirs ()
	Get the current search paths.
static SmartStringVec	cdRomDirs ()
	Get an array of paths to available CD-ROM drives.
static SmartStringVec	enumerateFiles (const char *dir)
	Get a file listing of a search path's directory.
static const char *	dirSeperator ()
	Get platform-dependent dir separator string.
static const char *	baseDir ()
	Get the path where the application resides.
static const char *	userDir ()
	Get the path where user's home directory resides.
static void	makeDir (const char *dirName)
	Create a directory.
static bool	isDir (const char *fileName)
	Determine if a file in the search path is really a directory.
static void	deleteFile (const char *fileName)
	Delete a file or directory.
static const char *	realDirectory (const char *fileName)
	Figure out where in the search path a file resides.
static bool	exists (const char *fileName)
	Determine if a file exists in the search path.

LDK::VFileSystem Class Reference
[File and filesystem virtualisation]

Static Public Member Functions

Detailed Description

Member Function Documentation

LDK::VFileSystem Class Reference [File and filesystem virtualisation]

Static Public Member Functions

Detailed Description

Member Function Documentation

LDK::VFileSystem Class Reference
[File and filesystem virtualisation]