iVFS Struct Reference
[Virtual File System (VFS)]

The Virtual Filesystem Class is intended to be the only way for Crystal Space engine to access the files. More...

#include <iutil/vfs.h>

Inheritance diagram for iVFS:


Public Member Functions
virtual bool	ChDir (const char *Path)=0
	Set current working directory.
virtual bool	ChDirAuto (const char path, const csStringArray paths=0, const char vfspath=0, const char filename=0)=0
	Convenience function to set the current VFS directory to the given path.
virtual bool	DeleteFile (const char *FileName)=0
	Delete a file on VFS.
virtual bool	Exists (const char *Path) const =0
	Check whether a file exists.
virtual csPtr< iDataBuffer >	ExpandPath (const char *Path, bool IsDir=false) const =0
	Expand given virtual path, interpret all "." and ".."'s relative to 'current virtual directory'.
virtual csPtr< iStringArray >	FindFiles (const char *Path) const =0
	Find absolute paths of all files in a virtual directory and return an array with their names.
virtual const char *	GetCwd () const =0
	Get current working directory.
virtual bool	GetFileSize (const char *FileName, size_t &oSize)=0
	Query file size (without opening it).
virtual bool	GetFileTime (const char *FileName, csFileTime &oTime) const =0
	Query file date/time.
virtual csRef< iStringArray >	GetMounts ()=0
	Get a list of all current virtual mount paths.
virtual csRef< iStringArray >	GetRealMountPaths (const char *VirtualPath)=0
	Get the real paths associated with a mount.
virtual csPtr< iDataBuffer >	GetRealPath (const char *FileName)=0
	Query real-world path from given VFS path.
virtual bool	LoadMountsFromFile (iConfigFile *file)=0
	Loads mounts from a configuration file.
virtual bool	Mount (const char VirtualPath, const char RealPath)=0
	Mount an VFS path on a "real-world-filesystem" path.
virtual csRef< iStringArray >	MountRoot (const char *VirtualPath)=0
	Mount the root directory or directories beneath the given virtual path.
virtual csPtr< iFile >	Open (const char *FileName, int Mode)=0
	Open a file on the VFS filesystem.
virtual bool	PopDir ()=0
	Pop current directory.
virtual void	PushDir (char const *Path=0)=0
	Push current directory and optionally change to a different directory.
virtual csPtr< iDataBuffer >	ReadFile (const char *FileName, bool nullterm=true)=0
	Get an entire file at once.
virtual bool	SaveMounts (const char *FileName)=0
	Save current configuration back into configuration file.
virtual bool	SetFileTime (const char *FileName, const csFileTime &iTime)=0
	Set file date/time.
virtual bool	Sync ()=0
	Close all opened archives, free temporary storage etc.
virtual bool	Unmount (const char VirtualPath, const char RealPath)=0
	Unmount a VFS path.
virtual bool	WriteFile (const char Name, const char Data, size_t Size)=0
	Write an entire file in one pass.

Detailed Description

The Virtual Filesystem Class is intended to be the only way for Crystal Space engine to access the files.

This gives unified control over the way how files are found, read and written. VFS gives the following goodies over the standard file i/o functions:

Multiple search directories. Several "real" directories can be collected together into one "virtual" directory.
Directories can be mapped to "real" directories as well as to archives (.zip files). Files are compressed/decompressed transparently for clients.
The Virtual File System is unique across all operating systems Crystal Space supports, no matter of features of the underlying OS.

This class has only most basic features of a real filesystem: file reading and writing (no simultaneous read and write mode are allowed because it would be rather complex to implement it for archives). However, most programs don't even need such functionality, and for sure Crystal Space itself doesn't need it. Files open for writing are always truncated. A simple meaning for getting a list of files in a virtual directory is implemented; however the user is presented with only a list of file names; no fancy things like file size, time etc (file size can be determined after opening it for reading).

Main creators of instances implementing this interface:

The VFS plugin (crystalspace.kernel.vfs)

Main ways to get pointers to this interface:

CS_QUERY_REGISTRY()

Definition at line 205 of file vfs.h.

Member Function Documentation

virtual bool iVFS::ChDir ( const char * Path ) [pure virtual]

Set current working directory.

virtual bool iVFS::ChDirAuto	(	const char *	path,
		const csStringArray *	paths = `0`,
		const char *	vfspath = `0`,
		const char *	filename = `0`
	)			`[pure virtual]`

Convenience function to set the current VFS directory to the given path.

The path can be any of the following:

A valid VFS path. In that case this is equivalent to calling ChDir(path).
A real path (using '/', '\', or '$/' for path delimiter). In this case this path will be mounted on the 'vfspath' parameter and a ChDir(vfspath) will happen.
A real path to a zip file. In this case the zip file will be mounted on the 'vfspath' parameter and a ChDir(vfspath) will happen.

Parameters:

	path	is the path to mount (VFS, real, zip, ...)
	paths	is an array of possible vfs paths to also look in for the given file. This can an empty array or 0. If not empty then this routine will first try to find the 'path' as such if it is a VFS path. Otherwise it will scan all paths here and add the path as a prefix. Only if all this fails will it try to interprete the input path as a real world dir or zip file.
	vfspath	is the temporary name to use in case it is not a vfs path. If not given then this routine will try to use a suitable temporary name.
	filename	is an optional filename that must be present on the given path. If this is given then the chdir will only work if the given file is present.

virtual bool iVFS::DeleteFile ( const char * FileName ) [pure virtual]

Delete a file on VFS.

Returns:: True if the deletion succeeded, else false.

virtual bool iVFS::Exists ( const char * Path ) const [pure virtual]

Check whether a file exists.

virtual csPtr<iDataBuffer> iVFS::ExpandPath	(	const char *	Path,
		bool	IsDir = `false`
	)			const `[pure virtual]`

Expand given virtual path, interpret all "." and ".."'s relative to 'current virtual directory'.

Parameters:

	Path	The path to expand.
	IsDir	If true, the expanded path will be terminated with '/'.

Returns:: A new iDataBuffer object.

virtual csPtr<iStringArray> iVFS::FindFiles ( const char * Path ) const [pure virtual]

Find absolute paths of all files in a virtual directory and return an array with their names.

virtual const char* iVFS::GetCwd ( ) const [pure virtual]

Get current working directory.

virtual bool iVFS::GetFileSize	(	const char *	FileName,
		size_t &	oSize
	)			`[pure virtual]`

Query file size (without opening it).

Returns:: True if the query succeeded, else false.

virtual bool iVFS::GetFileTime	(	const char *	FileName,
		csFileTime &	oTime
	)			const `[pure virtual]`

Query file date/time.

Returns:: True if the query succeeded, else false.

virtual csRef<iStringArray> iVFS::GetMounts ( ) [pure virtual]

Get a list of all current virtual mount paths.

Returns:: An iStringArray containing all the current virtual mounts

virtual csRef<iStringArray> iVFS::GetRealMountPaths ( const char * VirtualPath ) [pure virtual]

Get the real paths associated with a mount.

Parameters:

VirtualPath

The virtual path of a mount point

Returns:: An iStringArray containing all the real filesystem paths associated with the VirtualPath mount, or an empty array if the VirtualPath isn't mounted.

virtual csPtr<iDataBuffer> iVFS::GetRealPath ( const char * FileName ) [pure virtual]

Query real-world path from given VFS path.

Parameters:

FileName

The virtual path for which the physical path is desired.

Remarks:: This will work only for files that are stored on real filesystem, not in archive files. You should expect this function to return an invalidated iDataBuffer for filesystems which do not support this operation.

Returns:: An iDataBuffer containing the actual physical path corresponding to the virtual path named by FileName, or an invalidated iDataBuffer if the operation fails or is not supported. Use csRef<>::IsValid() to check validity.

virtual bool iVFS::LoadMountsFromFile ( iConfigFile * file ) [pure virtual]

Loads mounts from a configuration file.

Returns:: True if no error occured, false otherwise.

virtual bool iVFS::Mount	(	const char *	VirtualPath,
		const char *	RealPath
	)			`[pure virtual]`

Mount an VFS path on a "real-world-filesystem" path.

Parameters:

	VirtualPath	The location in the virtual filesystem in which to mount RealPath.
	RealPath	The physical filesystem path to mount at VirtualPath. All VFS pseudo-variables and anything that appears in the right-hand side of an equal sign in vfs.cfg is valid.

Returns:: True if the mount succeeded, else false.

virtual csRef<iStringArray> iVFS::MountRoot ( const char * VirtualPath ) [pure virtual]

Mount the root directory or directories beneath the given virtual path.

Returns:: A list of absolute virtual pathnames mounted by this operation.

Remarks:: On Unix, there is only a single root directory, but on other platforms there may be many. For example, on Unix, if VirtualPath is "/native", then the single Unix root directory "/" will be mounted directly to "/native". On Windows, which has multiple root directories, one for each drive letter, they will be mounted as "/native/a/", "/native/c/", "/native/d/", and so on.

virtual csPtr<iFile> iVFS::Open	(	const char *	FileName,
		int	Mode
	)			`[pure virtual]`

Open a file on the VFS filesystem.

Parameters:

	FileName	The VFS path of the file in the VFS filesystem.
	Mode	Combination of VFS_FILE_XXX constants.

Returns:: A valid iFile if the file was opened successfully, otherwise an invalidated iFile. Use csRef<>::IsValid() to check validity.

See also:: VFS_FILE_MODE

virtual bool iVFS::PopDir ( ) [pure virtual]

Pop current directory.

Set the current working directory to the one most recently pushed.

Returns:: True if there was a remembered directory and the invocation of ChDir() for the remembered directory succeeded; else false if there was no remembered directory, or ChDir() failed.

virtual void iVFS::PushDir ( char const * Path = 0 ) [pure virtual]

Push current directory and optionally change to a different directory.

Parameters:

Path

Path which should become the new working directory after the current directory is remembered. May be null.

Remarks:: If Path is not the null pointer, then current working directory is remembered and Path is set as the new working directory. If Path is the null pointer, then the current working directory is remembered, but not changed.

virtual csPtr<iDataBuffer> iVFS::ReadFile	(	const char *	FileName,
		bool	nullterm = `true`
	)			`[pure virtual]`

Get an entire file at once.

This is more effective than opening files and reading the file in blocks. Note that the returned buffer can be null-terminated (so that it can be conveniently used with string functions) but the extra null-terminator is not counted as part of the returned size.

Parameters:

	FileName	VFS path of the file to be read.
	nullterm	Null-terminate the returned buffer.

Returns:: An iDataBuffer containing the file contents if the file was opened and read successfully, otherwise an invalidated iFile. Use csRef<>::IsValid() to check validity.

Remarks:: Null-termination might have a performance penalty (dependent on where the file is stored.) Use only when needed.

virtual bool iVFS::SaveMounts ( const char * FileName ) [pure virtual]

Save current configuration back into configuration file.

Returns:: True if the operation succeeded, else false.

virtual bool iVFS::SetFileTime	(	const char *	FileName,
		const csFileTime &	iTime
	)			`[pure virtual]`

Set file date/time.

Returns:: True if the operation succeeded, else false.

virtual bool iVFS::Sync ( ) [pure virtual]

Close all opened archives, free temporary storage etc.

Returns:: True if the synchronization succeeded, else false.

virtual bool iVFS::Unmount	(	const char *	VirtualPath,
		const char *	RealPath
	)			`[pure virtual]`

Unmount a VFS path.

Parameters:

	VirtualPath	The location in the virtual filesystem which is to be unmounted.
	RealPath	The physical filesystem path corresponding to the virtual path.

Remarks:: A single virtual path may represent multiple physical locations; in which case, the physical locations appear as a conglomerate in the virtual filesystem. The RealPath argument allows unmounting of just a single location represented by the given VirtualPath. If RealPath is the null pointer, then all physical locations represented by VirtualPath are umounted.

Returns:: True if the unmount succeeded, else false.

virtual bool iVFS::WriteFile	(	const char *	Name,
		const char *	Data,
		size_t	Size
	)			`[pure virtual]`

Write an entire file in one pass.

Parameters:

	Name	Name of file to write.
	Data	Pointer to the data to be written.
	Size	Number of bytes to write.

Returns:: True if the write succeeded, else false.

The documentation for this struct was generated from the following file:

iutil/vfs.h

Generated for Crystal Space by doxygen 1.4.7

Public API Reference

iVFS Struct Reference [Virtual File System (VFS)]

Public Member Functions

Detailed Description

Member Function Documentation

iVFS Struct Reference
[Virtual File System (VFS)]