CrystalSpace

Public API Reference

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:

List of all members.

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)=0
 Check whether a file exists.
virtual csPtr< iDataBufferExpandPath (const char *Path, bool IsDir=false)=0
 Expand given virtual path, interpret all "." and ".."'s relative to 'current virtual directory'.
virtual csPtr< iStringArrayFindFiles (const char *Path)=0
 Find absolute paths of all files in a virtual directory and return an array with their names.
virtual const char * GetCwd ()=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)=0
 Query file date/time.
virtual csRef< iStringArrayGetMounts ()=0
 Get a list of all current virtual mount paths.
virtual csRef< iStringArrayGetRealMountPaths (const char *VirtualPath)=0
 Get the real paths associated with a mount.
virtual csPtr< iDataBufferGetRealPath (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< iStringArrayMountRoot (const char *VirtualPath)=0
 Mount the root directory or directories beneath the given virtual path.
virtual csPtr< iFileOpen (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< iDataBufferReadFile (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 SymbolicLink (const char *Target, const char *Link=0, int priority=0)=0
 Create or add a symbolic link within the VFS (works like unix 'ln -s' command) If the link already exists, then the target will be added to the link At the moment just remounts it at `Target'.
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:

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:

Main ways to get pointers to this interface:

Definition at line 274 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  )  [pure virtual]

Check whether a file exists.

virtual csPtr<iDataBuffer> iVFS::ExpandPath ( const char *  Path,
bool  IsDir = false 
) [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  )  [pure virtual]

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

virtual const char* iVFS::GetCwd (  )  [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 
) [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 a null reference. 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::SymbolicLink ( const char *  Target,
const char *  Link = 0,
int  priority = 0 
) [pure virtual]

Create or add a symbolic link within the VFS (works like unix 'ln -s' command) If the link already exists, then the target will be added to the link At the moment just remounts it at `Target'.

Parameters:
Target The target that the link will point to
Link The path of the link within the VFS, if this is 0 then the link will be created in the current directory with the same name as the target
priority Currently unused
Returns:
True if successful, 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:

Generated for Crystal Space 2.1 by doxygen 1.6.1