iVFS Struct Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions
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< iDataBuffer > | ExpandPath (const char *Path, bool IsDir=false)=0
| Expand given virtual path, interpret all "." and ".."'s relative to 'current virtual directory'.
virtual csPtr< iStringArray > | FindFiles (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< 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 | 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:

- 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:

- csQueryRegistry<iVFS>()

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:

- iutil/vfs.h