2010-02-08 17:23:39 +01:00
|
|
|
/* Copyright (c) 2010 Wildfire Games
|
2009-04-18 19:00:33 +02:00
|
|
|
*
|
2010-02-08 17:23:39 +01:00
|
|
|
* Permission is hereby granted, free of charge, to any person obtaining
|
|
|
|
* a copy of this software and associated documentation files (the
|
|
|
|
* "Software"), to deal in the Software without restriction, including
|
|
|
|
* without limitation the rights to use, copy, modify, merge, publish,
|
|
|
|
* distribute, sublicense, and/or sell copies of the Software, and to
|
|
|
|
* permit persons to whom the Software is furnished to do so, subject to
|
|
|
|
* the following conditions:
|
|
|
|
*
|
|
|
|
* The above copyright notice and this permission notice shall be included
|
|
|
|
* in all copies or substantial portions of the Software.
|
|
|
|
*
|
|
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
|
|
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
|
|
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
|
|
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
|
|
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
|
|
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
|
|
|
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
2009-04-18 19:00:33 +02:00
|
|
|
*/
|
|
|
|
|
2009-04-18 19:51:05 +02:00
|
|
|
/*
|
|
|
|
* Virtual File System API - allows transparent access to files in
|
2009-11-04 23:35:54 +01:00
|
|
|
* archives, modding via multiple mount points and hotloading.
|
2009-04-18 18:14:48 +02:00
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef INCLUDED_VFS
|
|
|
|
#define INCLUDED_VFS
|
|
|
|
|
|
|
|
#include "lib/file/file_system.h" // FileInfo
|
|
|
|
#include "lib/file/vfs/vfs_path.h"
|
|
|
|
|
|
|
|
namespace ERR
|
|
|
|
{
|
|
|
|
const LibError VFS_DIR_NOT_FOUND = -110100;
|
|
|
|
const LibError VFS_FILE_NOT_FOUND = -110101;
|
|
|
|
const LibError VFS_ALREADY_MOUNTED = -110102;
|
|
|
|
}
|
|
|
|
|
|
|
|
// (recursive mounting and mounting archives are no longer optional since they don't hurt)
|
|
|
|
enum VfsMountFlags
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* all real directories mounted during this operation will be watched
|
|
|
|
* for changes. this flag is provided to avoid watches in output-only
|
|
|
|
* directories, e.g. screenshots/ (only causes unnecessary overhead).
|
|
|
|
**/
|
|
|
|
VFS_MOUNT_WATCH = 1,
|
|
|
|
|
|
|
|
/**
|
|
|
|
* anything mounted from here should be included when building archives.
|
|
|
|
**/
|
2010-03-20 19:12:48 +01:00
|
|
|
VFS_MOUNT_ARCHIVABLE = 2,
|
|
|
|
|
|
|
|
/**
|
|
|
|
* return ERR::VFS_DIR_NOT_FOUND if the given real path doesn't exist.
|
|
|
|
* (the default behaviour is to create all real directories in the path)
|
|
|
|
**/
|
|
|
|
VFS_MOUNT_MUST_EXIST = 4
|
2009-04-18 18:14:48 +02:00
|
|
|
};
|
|
|
|
|
|
|
|
struct IVFS
|
|
|
|
{
|
2009-08-24 23:04:01 +02:00
|
|
|
virtual ~IVFS() {}
|
|
|
|
|
2009-04-18 18:14:48 +02:00
|
|
|
/**
|
|
|
|
* mount a directory into the VFS.
|
|
|
|
*
|
|
|
|
* @param mountPoint (will be created if it does not already exist)
|
|
|
|
* @param path real directory path
|
2010-07-29 17:55:41 +02:00
|
|
|
* @param flags
|
|
|
|
* @param priority
|
2009-04-18 18:14:48 +02:00
|
|
|
* @return LibError.
|
|
|
|
*
|
|
|
|
* if files are encountered that already exist in the VFS (sub)directories,
|
|
|
|
* the most recent / highest priority/precedence version is preferred.
|
|
|
|
*
|
|
|
|
* if files with archive extensions are seen, their contents are added
|
|
|
|
* as well.
|
|
|
|
**/
|
2011-03-23 14:36:20 +01:00
|
|
|
virtual LibError Mount(const VfsPath& mountPoint, const OsPath& path, size_t flags = 0, size_t priority = 0) = 0;
|
2009-04-18 18:14:48 +02:00
|
|
|
|
|
|
|
/**
|
2010-07-29 17:55:41 +02:00
|
|
|
* Retrieve information about a file (similar to POSIX stat).
|
2009-11-06 02:30:16 +01:00
|
|
|
*
|
2010-07-29 17:55:41 +02:00
|
|
|
* @param pathname
|
|
|
|
* @param pfileInfo receives information about the file. Passing NULL
|
|
|
|
* suppresses warnings if the file doesn't exist.
|
2009-04-18 18:14:48 +02:00
|
|
|
*
|
|
|
|
* @return LibError.
|
|
|
|
**/
|
|
|
|
virtual LibError GetFileInfo(const VfsPath& pathname, FileInfo* pfileInfo) const = 0;
|
|
|
|
|
2010-09-10 22:29:38 +02:00
|
|
|
/**
|
|
|
|
* Retrieve mount priority for a file.
|
|
|
|
*
|
|
|
|
* @param pathname
|
|
|
|
* @param ppriority receives priority value, if the file can be found.
|
|
|
|
*
|
|
|
|
* @return LibError.
|
|
|
|
**/
|
|
|
|
virtual LibError GetFilePriority(const VfsPath& pathname, size_t* ppriority) const = 0;
|
|
|
|
|
2009-04-18 18:14:48 +02:00
|
|
|
/**
|
2010-07-29 17:55:41 +02:00
|
|
|
* Retrieve lists of all files and subdirectories in a directory.
|
2009-04-18 18:14:48 +02:00
|
|
|
*
|
|
|
|
* @return LibError.
|
|
|
|
*
|
2010-07-29 17:55:41 +02:00
|
|
|
* Rationale:
|
2009-04-18 18:14:48 +02:00
|
|
|
* - this interface avoids having to lock the directory while an
|
|
|
|
* iterator is extant.
|
|
|
|
* - we cannot efficiently provide routines for returning files and
|
|
|
|
* subdirectories separately due to the underlying POSIX interface.
|
|
|
|
**/
|
2009-11-04 18:26:54 +01:00
|
|
|
virtual LibError GetDirectoryEntries(const VfsPath& path, FileInfos* fileInfos, DirectoryNames* subdirectoryNames) const = 0;
|
2009-04-18 18:14:48 +02:00
|
|
|
|
|
|
|
/**
|
2010-07-29 17:55:41 +02:00
|
|
|
* Create a file with the given contents.
|
|
|
|
* @param pathname
|
|
|
|
* @param fileContents
|
2009-04-18 18:14:48 +02:00
|
|
|
* @param size [bytes] of the contents, will match that of the file.
|
|
|
|
* @return LibError.
|
|
|
|
*
|
|
|
|
* rationale: disallowing partial writes simplifies file cache coherency
|
2009-11-04 23:35:54 +01:00
|
|
|
* (we need only invalidate cached data when closing a newly written file).
|
2009-04-18 18:14:48 +02:00
|
|
|
**/
|
|
|
|
virtual LibError CreateFile(const VfsPath& pathname, const shared_ptr<u8>& fileContents, size_t size) = 0;
|
|
|
|
|
|
|
|
/**
|
2010-07-29 17:55:41 +02:00
|
|
|
* Read an entire file into memory.
|
2009-04-18 18:14:48 +02:00
|
|
|
*
|
2010-07-29 17:55:41 +02:00
|
|
|
* @param pathname
|
2009-04-18 18:14:48 +02:00
|
|
|
* @param fileContents receives a smart pointer to the contents.
|
2010-07-29 17:55:41 +02:00
|
|
|
* CAVEAT: this will be taken from the file cache if the VFS was
|
|
|
|
* created with cacheSize != 0 and size < cacheSize. There is no
|
|
|
|
* provision for Copy-on-Write, which means that such buffers
|
|
|
|
* must not be modified (this is enforced via mprotect).
|
2009-04-18 18:14:48 +02:00
|
|
|
* @param size receives the size [bytes] of the file contents.
|
|
|
|
* @return LibError.
|
|
|
|
**/
|
|
|
|
virtual LibError LoadFile(const VfsPath& pathname, shared_ptr<u8>& fileContents, size_t& size) = 0;
|
|
|
|
|
|
|
|
/**
|
2009-11-06 02:30:16 +01:00
|
|
|
* @return a string representation of all files and directories.
|
2009-04-18 18:14:48 +02:00
|
|
|
**/
|
2009-11-04 18:26:54 +01:00
|
|
|
virtual std::wstring TextRepresentation() const = 0;
|
2009-04-18 18:14:48 +02:00
|
|
|
|
|
|
|
/**
|
2009-11-06 02:30:16 +01:00
|
|
|
* retrieve the real (POSIX) pathname underlying a VFS file.
|
|
|
|
*
|
|
|
|
* this is useful for passing paths to external libraries.
|
2009-04-18 18:14:48 +02:00
|
|
|
**/
|
2011-03-23 14:36:20 +01:00
|
|
|
virtual LibError GetRealPath(const VfsPath& pathname, OsPath& realPathname) = 0;
|
2009-04-18 18:14:48 +02:00
|
|
|
|
|
|
|
/**
|
2009-11-06 02:30:16 +01:00
|
|
|
* retrieve the VFS pathname that corresponds to a real file.
|
|
|
|
*
|
|
|
|
* this is useful for reacting to file change notifications.
|
2009-04-18 18:14:48 +02:00
|
|
|
*
|
2009-11-06 02:30:16 +01:00
|
|
|
* the current implementation requires time proportional to the
|
|
|
|
* number of directories; this could be accelerated by only checking
|
|
|
|
* directories below a mount point with a matching real path.
|
2009-04-18 18:14:48 +02:00
|
|
|
**/
|
2011-03-23 14:36:20 +01:00
|
|
|
virtual LibError GetVirtualPath(const OsPath& realPathname, VfsPath& pathname) = 0;
|
2009-11-06 12:50:04 +01:00
|
|
|
|
2009-11-04 23:35:54 +01:00
|
|
|
/**
|
2009-11-06 12:50:04 +01:00
|
|
|
* indicate that a file has changed; remove its data from the cache and
|
|
|
|
* arrange for its directory to be updated.
|
2009-11-04 23:35:54 +01:00
|
|
|
**/
|
2009-11-06 12:50:04 +01:00
|
|
|
virtual LibError Invalidate(const VfsPath& pathname) = 0;
|
2009-11-06 02:30:16 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* empty the contents of the filesystem.
|
|
|
|
* this is typically only necessary when changing the set of
|
|
|
|
* mounted directories, e.g. when switching mods.
|
|
|
|
* NB: open files are not affected.
|
|
|
|
**/
|
|
|
|
virtual void Clear() = 0;
|
2009-04-18 18:14:48 +02:00
|
|
|
};
|
|
|
|
|
|
|
|
typedef shared_ptr<IVFS> PIVFS;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* create an instance of a Virtual File System.
|
|
|
|
*
|
|
|
|
* @param cacheSize size [bytes] of memory to reserve for a file cache,
|
|
|
|
* or zero to disable it. if small enough to fit, file contents are
|
|
|
|
* stored here until no references remain and they are evicted.
|
|
|
|
*
|
|
|
|
* note: there is no limitation to a single instance, it may make sense
|
|
|
|
* to create and destroy VFS instances during each unit test.
|
|
|
|
**/
|
|
|
|
LIB_API PIVFS CreateVfs(size_t cacheSize);
|
|
|
|
|
|
|
|
#endif // #ifndef INCLUDED_VFS
|