Panda3D
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes

VirtualFileSystem Class Reference

A hierarchy of directories and files that appears to be one continuous file system, even though the files may originate from several different sources that may not be related to the actual OS's file system. More...

#include "virtualFileSystem.h"

List of all members.

Public Types

enum  MountFlags { MF_read_only = 0x0002 }
enum  OpenFlags { OF_status_only = 0x0001, OF_create_file = 0x0002, OF_make_directory = 0x0004, OF_allow_nonexist = 0x0008 }

Public Member Functions

bool atomic_compare_and_exchange_contents (const Filename &filename, string &orig_contents, const string &old_contents, const string &new_contents)
 See Filename::atomic_compare_and_exchange_contents().
bool atomic_read_contents (const Filename &filename, string &contents) const
 See Filename::atomic_read_contents().
bool chdir (const Filename &new_directory)
 Changes the current directory.
bool copy_file (const Filename &orig_filename, const Filename &new_filename)
 Attempts to copy the contents of the indicated file to the indicated file.
bool delete_file (const Filename &filename)
 Attempts to delete the indicated file or directory.
bool exists (const Filename &filename) const
 Convenience function; returns true if the named file exists.
int find_all_files (const Filename &filename, const DSearchPath &searchpath, DSearchPath::Results &results) const
 Searches all the directories in the search list for the indicated file, in order.
Filename get_cwd () const
 Returns the current directory name.
int get_num_mounts () const
 Returns the number of individual mounts in the system.
bool is_directory (const Filename &filename) const
 Convenience function; returns true if the named file exists and is a directory.
bool is_regular_file (const Filename &filename) const
 Convenience function; returns true if the named file exists and is a regular file.
void ls (const Filename &filename) const
 Convenience function; lists the files within the indicated directory.
void ls_all (const Filename &filename) const
 Convenience function; lists the files within the indicated directory, and all files below, recursively.
bool make_directory (const Filename &filename)
 Attempts to create a directory within the file system.
bool make_directory_full (const Filename &filename)
 Attempts to create a directory within the file system.
 MAKE_SEQ (get_mounts, get_num_mounts, get_mount)
bool mount (const Filename &physical_filename, const Filename &mount_point, int flags, const string &password="")
 Mounts the indicated system file or directory at the given mount point.
bool mount (Multifile *multifile, const Filename &mount_point, int flags)
 Mounts the indicated Multifile at the given mount point.
bool mount (VirtualFileMount *mount, const Filename &mount_point, int flags)
 Adds the given VirtualFileMount object to the mount list.
bool mount_loop (const Filename &virtual_filename, const Filename &mount_point, int flags, const string &password="")
 This is similar to mount(), but it receives the name of a Multifile that already appears within the virtual file system.
ostream * open_append_file (const Filename &filename)
 Works like open_write_file(), but the file is opened in append mode.
iostream * open_read_append_file (const Filename &filename)
 Works like open_read_write_file(), but the file is opened in append mode.
istream * open_read_file (const Filename &filename, bool auto_unwrap) const
 Convenience function; returns a newly allocated istream if the file exists and can be read, or NULL otherwise.
iostream * open_read_write_file (const Filename &filename, bool truncate)
 Convenience function; returns a newly allocated iostream if the file exists and can be written, or NULL otherwise.
ostream * open_write_file (const Filename &filename, bool auto_wrap, bool truncate)
 Convenience function; returns a newly allocated ostream if the file exists and can be written, or NULL otherwise.
 PT (VirtualFile) create_file(const Filename &filename)
 PT (VirtualFile) find_file(const Filename &filename
 PT (VirtualFileList) scan_directory(const Filename &filename) const
 PT (VirtualFileMount) get_mount(int n) const
 PT (VirtualFile) get_file(const Filename &filename
bool read_file (const Filename &filename, pvector< unsigned char > &result, bool auto_unwrap) const
 Convenience function; fills the pvector up with the data from the indicated file, if it exists and can be read.
string read_file (const Filename &filename, bool auto_unwrap) const
 Convenience function; returns the entire contents of the indicated file as a string.
bool read_file (const Filename &filename, string &result, bool auto_unwrap) const
 Convenience function; fills the string up with the data from the indicated file, if it exists and can be read.
bool rename_file (const Filename &orig_filename, const Filename &new_filename)
 Attempts to move or rename the indicated file or directory.
bool resolve_filename (Filename &filename, const DSearchPath &searchpath, const string &default_extension=string()) const
 Searches the given search path for the filename.
void scan_mount_points (vector_string &names, const Filename &path) const
 Adds to names a list of all the mount points in use that are one directory below path, if any.
int unmount (const Filename &physical_filename)
 Unmounts all appearances of the indicated directory name or multifile name from the file system.
int unmount (Multifile *multifile)
 Unmounts all appearances of the indicated Multifile from the file system.
int unmount (VirtualFileMount *mount)
 Unmounts the indicated VirtualFileMount object from the file system.
int unmount_all ()
 Unmounts all files from the file system.
int unmount_point (const Filename &mount_point)
 Unmounts all systems attached to the given mount point from the file system.
void write (ostream &out) const
 Print debugging information.
bool write_file (const Filename &filename, const unsigned char *data, size_t data_size, bool auto_wrap)
 Convenience function; writes the entire contents of the indicated file as a block of data.
bool write_file (const Filename &filename, const string &data, bool auto_wrap)
 Convenience function; writes the entire contents of the indicated file as a string.

Static Public Member Functions

static void close_read_file (istream *stream)
 Closes a file opened by a previous call to open_read_file().
static void close_read_write_file (iostream *stream)
 Closes a file opened by a previous call to open_read_write_file().
static void close_write_file (ostream *stream)
 Closes a file opened by a previous call to open_write_file().
static VirtualFileSystemget_global_ptr ()
 Returns the default global VirtualFileSystem.
static void parse_option (const string &option, int &flags, string &password)
 Parses one of the option flags in the options list on the vfs-mount Config.prc line.
static void parse_options (const string &options, int &flags, string &password)
 Parses all of the option flags in the options list on the vfs-mount Config.prc line.

Public Attributes

const DSearchPathsearchpath
bool status_only = false) const
const DSearchPath bool status_only = false) const
ConfigVariableBool vfs_case_sensitive
ConfigVariableBool vfs_implicit_mf
ConfigVariableBool vfs_implicit_pz

Detailed Description

A hierarchy of directories and files that appears to be one continuous file system, even though the files may originate from several different sources that may not be related to the actual OS's file system.

For instance, a VirtualFileSystem can transparently mount one or more Multifiles as their own subdirectory hierarchies.

Definition at line 44 of file virtualFileSystem.h.


Member Function Documentation

bool VirtualFileSystem::atomic_compare_and_exchange_contents ( const Filename filename,
string &  orig_contents,
const string &  old_contents,
const string &  new_contents 
)
bool VirtualFileSystem::atomic_read_contents ( const Filename filename,
string &  contents 
) const
bool VirtualFileSystem::chdir ( const Filename new_directory)

Changes the current directory.

This is used to resolve relative pathnames in get_file() and/or find_file(). Returns true if successful, false otherwise.

Definition at line 471 of file virtualFileSystem.cxx.

Referenced by get_global_ptr().

void VirtualFileSystem::close_read_file ( istream *  stream) [static]

Closes a file opened by a previous call to open_read_file().

This really just deletes the istream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 986 of file virtualFileSystem.cxx.

Referenced by SpeedTreeNode::add_from_stf(), PandaIOSystem::Close(), DatagramInputFile::close(), Texture::do_read_dds_file(), Texture::do_read_txo_file(), PNMImageHeader::make_reader(), open_read_file(), DXFFile::process(), XFile::read(), PfmFile::read(), EggData::read(), DCFile::read(), FltHeader::read_flt(), and IffInputFile::set_input().

void VirtualFileSystem::close_read_write_file ( iostream *  stream) [static]

Closes a file opened by a previous call to open_read_write_file().

This really just deletes the iostream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 1148 of file virtualFileSystem.cxx.

Referenced by open_read_append_file(), and open_read_write_file().

void VirtualFileSystem::close_write_file ( ostream *  stream) [static]

Closes a file opened by a previous call to open_write_file().

This really just deletes the ostream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 1084 of file virtualFileSystem.cxx.

Referenced by DatagramOutputFile::close(), Texture::do_write_txo_file(), open_append_file(), open_write_file(), and EggData::write_egg().

bool VirtualFileSystem::copy_file ( const Filename orig_filename,
const Filename new_filename 
)

Attempts to copy the contents of the indicated file to the indicated file.

Returns true on success, false on failure.

Definition at line 689 of file virtualFileSystem.cxx.

bool VirtualFileSystem::delete_file ( const Filename filename)

Attempts to delete the indicated file or directory.

This can remove a single file or an empty directory. It will not remove a nonempty directory. Returns true on success, false on failure.

Definition at line 635 of file virtualFileSystem.cxx.

Referenced by BamCache::flush_index(), BamFile::open_write(), BamCache::store(), and EggData::write_egg().

bool VirtualFileSystem::exists ( const Filename filename) const [inline]
int VirtualFileSystem::find_all_files ( const Filename filename,
const DSearchPath searchpath,
DSearchPath::Results results 
) const

Searches all the directories in the search list for the indicated file, in order.

Fills up the results list with *all* of the matching filenames found, if any. Returns the number of matches found.

It is the responsibility of the the caller to clear the results list first; otherwise, the newly-found files will be appended to the list.

Definition at line 765 of file virtualFileSystem.cxx.

References DSearchPath::Results::add_file(), exists(), DSearchPath::get_directory(), DSearchPath::get_num_directories(), Filename::is_fully_qualified(), and Filename::is_local().

Filename VirtualFileSystem::get_cwd ( ) const

Returns the current directory name.

See chdir().

Definition at line 496 of file virtualFileSystem.cxx.

Referenced by Texture::do_write_datagram_header(), and SpeedTreeNode::InstanceList::write_datagram().

VirtualFileSystem * VirtualFileSystem::get_global_ptr ( ) [static]

Returns the default global VirtualFileSystem.

You may create your own personal VirtualFileSystem objects and use them for whatever you like, but Panda will attempt to load models and stuff from this default object.

Initially, the global VirtualFileSystem is set up to mount the OS filesystem to root; i.e. it is equivalent to the OS filesystem. This may be subsequently adjusted by the user.

Definition at line 826 of file virtualFileSystem.cxx.

References chdir(), ExecutionEnvironment::expand_string(), Filename::from_os_specific(), ExecutionEnvironment::get_cwd(), ConfigVariableList::get_num_unique_values(), ConfigVariableList::get_unique_value(), mount(), and parse_options().

Referenced by SpeedTreeNode::add_from_stf(), VirtualFileMountSystem::atomic_compare_and_exchange_contents(), VirtualFileMountSystem::atomic_read_contents(), DatagramOutputFile::close(), DatagramInputFile::close(), DatagramOutputFile::copy_datagram(), Texture::do_read(), Texture::do_read_dds_file(), Texture::do_read_txo_file(), Texture::do_write_datagram_header(), Texture::do_write_txo_file(), PathReplace::full_convert_path(), AudioManager::get_dls_pathname(), VirtualFileMountSystem::has_file(), VirtualFileMountSystem::is_directory(), VirtualFileMountSystem::is_regular_file(), VirtualFileMountSystem::is_writable(), Texture::load_related(), PNMImageHeader::make_reader(), Texture::make_this_from_bam(), PNMImageHeader::make_writer(), PathReplace::match_path(), DatagramOutputFile::open(), DatagramInputFile::open(), VirtualFileMountSystem::open_append_file(), IffInputFile::open_read(), Multifile::open_read(), VirtualFileMountSystem::open_read_append_file(), VirtualFileMountSystem::open_read_file(), VirtualFileMountSystem::open_read_write_file(), BamFile::open_write(), VirtualFileMountSystem::open_write_file(), DXFFile::process(), XFile::read(), PfmFile::read(), EggData::read(), ColladaLoader::read(), DCFile::read(), FltHeader::read_flt(), EggData::resolve_egg_filename(), EggGroupNode::resolve_filenames(), RocketFileInterface::RocketFileInterface(), VirtualFileMountSystem::scan_directory(), IffInputFile::set_input(), STBasicTerrain::setup_terrain(), SpeedTreeNode::InstanceList::write_datagram(), and EggData::write_egg().

int VirtualFileSystem::get_num_mounts ( ) const

Returns the number of individual mounts in the system.

Definition at line 438 of file virtualFileSystem.cxx.

bool VirtualFileSystem::is_directory ( const Filename filename) const [inline]

Convenience function; returns true if the named file exists and is a directory.

Definition at line 34 of file virtualFileSystem.I.

Referenced by BamCache::set_root().

bool VirtualFileSystem::is_regular_file ( const Filename filename) const [inline]

Convenience function; returns true if the named file exists and is a regular file.

Definition at line 46 of file virtualFileSystem.I.

void VirtualFileSystem::ls ( const Filename filename) const [inline]

Convenience function; lists the files within the indicated directory.

Definition at line 77 of file virtualFileSystem.I.

void VirtualFileSystem::ls_all ( const Filename filename) const [inline]

Convenience function; lists the files within the indicated directory, and all files below, recursively.

Definition at line 95 of file virtualFileSystem.I.

bool VirtualFileSystem::make_directory ( const Filename filename)

Attempts to create a directory within the file system.

Returns true on success, false on failure (for instance, because the parent directory does not exist, or is read-only). If the directory already existed prior to this call, returns true.

Definition at line 513 of file virtualFileSystem.cxx.

bool VirtualFileSystem::make_directory_full ( const Filename filename)

Attempts to create a directory within the file system.

Will also create any intervening directories needed. Returns true on success, false on failure.

Definition at line 528 of file virtualFileSystem.cxx.

Referenced by BamCache::set_root().

bool VirtualFileSystem::mount ( VirtualFileMount mount,
const Filename mount_point,
int  flags 
)

Adds the given VirtualFileMount object to the mount list.

This is a lower-level function that the other flavors of mount(); it requires you to create a VirtualFileMount object specifically.

Definition at line 211 of file virtualFileSystem.cxx.

bool VirtualFileSystem::mount ( Multifile multifile,
const Filename mount_point,
int  flags 
)

Mounts the indicated Multifile at the given mount point.

Definition at line 91 of file virtualFileSystem.cxx.

Referenced by get_global_ptr(), mount(), mount_loop(), scan_mount_points(), unmount(), unmount_all(), unmount_point(), and write().

bool VirtualFileSystem::mount ( const Filename physical_filename,
const Filename mount_point,
int  flags,
const string &  password = "" 
)

Mounts the indicated system file or directory at the given mount point.

If the named file is a directory, mounts the directory. If the named file is a Multifile, mounts it as a Multifile. Returns true on success, false on failure.

A given system directory may be mounted to multiple different mount point, and the same mount point may share multiple system directories. In the case of ambiguities (that is, two different files with exactly the same full pathname), the most-recently mounted system wins.

The filename specified as the first parameter must refer to a real, physical filename on disk; it cannot be a virtual file already appearing within the vfs filespace. However, it is possible to mount such a file; see mount_loop() for this.

Definition at line 125 of file virtualFileSystem.cxx.

References mount(), and Multifile::set_encryption_password().

bool VirtualFileSystem::mount_loop ( const Filename virtual_filename,
const Filename mount_point,
int  flags,
const string &  password = "" 
)

This is similar to mount(), but it receives the name of a Multifile that already appears within the virtual file system.

It can be used to mount a Multifile that is itself hosted within a virtually-mounted Multifile.

This interface can also be used to mount physical files (that appear within the virtual filespace), but it cannot be used to mount directories. Use mount() if you need to mount a directory.

Note that there is additional overhead, in the form of additional buffer copies of the data, for recursively mounting a multifile like this.

Definition at line 172 of file virtualFileSystem.cxx.

References mount(), and Multifile::set_encryption_password().

ostream * VirtualFileSystem::open_append_file ( const Filename filename)

Works like open_write_file(), but the file is opened in append mode.

Like open_write_file, the returned pointer should eventually be passed to close_write_file().

Definition at line 1061 of file virtualFileSystem.cxx.

References close_write_file(), and VirtualFile::open_append_file().

iostream * VirtualFileSystem::open_read_append_file ( const Filename filename)

Works like open_read_write_file(), but the file is opened in append mode.

Like open_read_write_file, the returned pointer should eventually be passed to close_read_write_file().

Definition at line 1125 of file virtualFileSystem.cxx.

References close_read_write_file(), and VirtualFile::open_read_append_file().

istream * VirtualFileSystem::open_read_file ( const Filename filename,
bool  auto_unwrap 
) const

Convenience function; returns a newly allocated istream if the file exists and can be read, or NULL otherwise.

Does not return an invalid istream.

If auto_unwrap is true, an explicitly-named .pz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 963 of file virtualFileSystem.cxx.

References close_read_file(), and VirtualFile::open_read_file().

Referenced by DatagramOutputFile::copy_datagram(), PNMImageHeader::make_reader(), PandaIOSystem::Open(), IffInputFile::open_read(), Multifile::open_read(), DXFFile::process(), XFile::read(), EggData::read(), DCFile::read(), and FltHeader::read_flt().

iostream * VirtualFileSystem::open_read_write_file ( const Filename filename,
bool  truncate 
)

Convenience function; returns a newly allocated iostream if the file exists and can be written, or NULL otherwise.

Does not return an invalid iostream.

Definition at line 1103 of file virtualFileSystem.cxx.

References close_read_write_file(), and VirtualFile::open_read_write_file().

ostream * VirtualFileSystem::open_write_file ( const Filename filename,
bool  auto_wrap,
bool  truncate 
)

Convenience function; returns a newly allocated ostream if the file exists and can be written, or NULL otherwise.

Does not return an invalid ostream.

If auto_wrap is true, an explicitly-named .pz file is automatically compressed while writing. If truncate is true, the file is truncated to zero length before writing.

Definition at line 1039 of file virtualFileSystem.cxx.

References close_write_file(), and VirtualFile::open_write_file().

Referenced by Texture::do_write_txo_file(), PNMImageHeader::make_writer(), and EggData::write_egg().

void VirtualFileSystem::parse_option ( const string &  option,
int &  flags,
string &  password 
) [static]

Parses one of the option flags in the options list on the vfs-mount Config.prc line.

Definition at line 1266 of file virtualFileSystem.cxx.

Referenced by parse_options().

void VirtualFileSystem::parse_options ( const string &  options,
int &  flags,
string &  password 
) [static]

Parses all of the option flags in the options list on the vfs-mount Config.prc line.

Definition at line 1243 of file virtualFileSystem.cxx.

References parse_option().

Referenced by get_global_ptr().

bool VirtualFileSystem::read_file ( const Filename filename,
string &  result,
bool  auto_unwrap 
) const [inline]

Convenience function; fills the string up with the data from the indicated file, if it exists and can be read.

Returns true on success, false otherwise.

If auto_unwrap is true, an explicitly-named .pz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 153 of file virtualFileSystem.I.

string VirtualFileSystem::read_file ( const Filename filename,
bool  auto_unwrap 
) const [inline]

Convenience function; returns the entire contents of the indicated file as a string.

If auto_unwrap is true, an explicitly-named .pz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 118 of file virtualFileSystem.I.

Referenced by ColladaLoader::read().

bool VirtualFileSystem::read_file ( const Filename filename,
pvector< unsigned char > &  result,
bool  auto_unwrap 
) const [inline]

Convenience function; fills the pvector up with the data from the indicated file, if it exists and can be read.

Returns true on success, false otherwise.

If auto_unwrap is true, an explicitly-named .pz file is automatically decompressed and the decompressed contents are returned. This is different than vfs-implicit-pz, which will automatically decompress a file if the extension .pz is *not* given.

Definition at line 172 of file virtualFileSystem.I.

bool VirtualFileSystem::rename_file ( const Filename orig_filename,
const Filename new_filename 
)

Attempts to move or rename the indicated file or directory.

If the original file is an ordinary file, it will quietly replace any already-existing file in the new filename (but not a directory). If the original file is a directory, the new filename must not already exist.

If the file is a directory, the new filename must be within the same mount point. If the file is an ordinary file, the new filename may be anywhere; but if it is not within the same mount point then the rename operation is automatically performed as a two-step copy-and-delete operation.

Definition at line 662 of file virtualFileSystem.cxx.

Referenced by BamCache::store().

bool VirtualFileSystem::resolve_filename ( Filename filename,
const DSearchPath searchpath,
const string &  default_extension = string() 
) const

Searches the given search path for the filename.

If it is found, updates the filename to the full pathname found and returns true; otherwise, returns false.

Definition at line 712 of file virtualFileSystem.cxx.

References exists(), Filename::get_extension(), and Filename::is_local().

Referenced by SpeedTreeNode::add_from_stf(), PathReplace::full_convert_path(), AudioManager::get_dls_pathname(), Texture::make_this_from_bam(), PathReplace::match_path(), EggData::resolve_egg_filename(), and EggGroupNode::resolve_filenames().

void VirtualFileSystem::scan_mount_points ( vector_string &  names,
const Filename path 
) const

Adds to names a list of all the mount points in use that are one directory below path, if any.

That is, these are the external files or directories mounted directly to the indicated path.

The names vector is filled with a set of basenames, the basename part of the mount point.

Definition at line 1203 of file virtualFileSystem.cxx.

References Filename::get_fullpath(), VirtualFileMount::get_mount_point(), Filename::is_local(), and mount().

int VirtualFileSystem::unmount ( Multifile multifile)

Unmounts all appearances of the indicated Multifile from the file system.

Returns the number of appearances unmounted.

Definition at line 231 of file virtualFileSystem.cxx.

References VirtualFileMount::get_mount_point(), VirtualFileMountMultifile::get_multifile(), TypedObject::is_exact_type(), and mount().

int VirtualFileSystem::unmount ( const Filename physical_filename)

Unmounts all appearances of the indicated directory name or multifile name from the file system.

Returns the number of appearances unmounted.

Definition at line 276 of file virtualFileSystem.cxx.

References VirtualFileMount::get_mount_point(), VirtualFileMountMultifile::get_multifile(), Multifile::get_multifile_name(), VirtualFileMountSystem::get_physical_filename(), TypedObject::is_exact_type(), and mount().

int VirtualFileSystem::unmount ( VirtualFileMount mount)

Unmounts the indicated VirtualFileMount object from the file system.

Returns the number of appearances unmounted.

Definition at line 338 of file virtualFileSystem.cxx.

References VirtualFileMount::get_mount_point(), and mount().

int VirtualFileSystem::unmount_all ( )

Unmounts all files from the file system.

Returns the number of systems unmounted.

Definition at line 412 of file virtualFileSystem.cxx.

References VirtualFileMount::get_mount_point(), and mount().

int VirtualFileSystem::unmount_point ( const Filename mount_point)

Unmounts all systems attached to the given mount point from the file system.

Returns the number of appearances unmounted.

Definition at line 374 of file virtualFileSystem.cxx.

References VirtualFileMount::get_mount_point(), and mount().

void VirtualFileSystem::write ( ostream &  out) const

Print debugging information.

(e.g. from Python or gdb prompt).

Definition at line 800 of file virtualFileSystem.cxx.

References mount().

bool VirtualFileSystem::write_file ( const Filename filename,
const string &  data,
bool  auto_wrap 
) [inline]

Convenience function; writes the entire contents of the indicated file as a string.

If auto_wrap is true, an explicitly-named .pz file is automatically compressed while writing.

Definition at line 135 of file virtualFileSystem.I.

bool VirtualFileSystem::write_file ( const Filename filename,
const unsigned char *  data,
size_t  data_size,
bool  auto_wrap 
) [inline]

Convenience function; writes the entire contents of the indicated file as a block of data.

If auto_wrap is true, an explicitly-named .pz file is automatically compressed while writing.

Definition at line 187 of file virtualFileSystem.I.


The documentation for this class was generated from the following files:
 All Classes Functions Variables Enumerations