Differential D3728 Diff 16678 ps/trunk/source/lib/file/vfs/vfs.h

Changeset View

Standalone View

ps/trunk/source/lib/file/vfs/vfs.h

/* Copyright (C) 2017 Wildfire Games.		/* Copyright (C) 2021 Wildfire Games.
*		*
* Permission is hereby granted, free of charge, to any person obtaining		* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the		* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including		* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,		* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to		* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to		* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:		* the following conditions:
Show All 16 Lines
*/		*/

#ifndef INCLUDED_VFS		#ifndef INCLUDED_VFS
#define INCLUDED_VFS		#define INCLUDED_VFS

#include "lib/file/file_system.h" // CFileInfo		#include "lib/file/file_system.h" // CFileInfo
#include "lib/file/vfs/vfs_path.h"		#include "lib/file/vfs/vfs_path.h"

		constexpr size_t VFS_MIN_PRIORITY = 0;
		constexpr size_t VFS_MAX_PRIORITY = std::numeric_limits<size_t>::max();

namespace ERR		namespace ERR
{		{
const Status VFS_DIR_NOT_FOUND = -110100;		const Status VFS_DIR_NOT_FOUND = -110100;
const Status VFS_FILE_NOT_FOUND = -110101;		const Status VFS_FILE_NOT_FOUND = -110101;
const Status VFS_ALREADY_MOUNTED = -110102;		const Status VFS_ALREADY_MOUNTED = -110102;
}		}

// (recursive mounting and mounting archives are no longer optional since they don't hurt)		// (recursive mounting and mounting archives are no longer optional since they don't hurt)
Show All 18 Lines	enum VfsMountFlags
VFS_MOUNT_MUST_EXIST = 4,		VFS_MOUNT_MUST_EXIST = 4,

/**		/**
* keep the files named "*.DELETED" visible in the VFS directories.		* keep the files named "*.DELETED" visible in the VFS directories.
* the standard behavior of hiding the file with the same name minus the		* the standard behavior of hiding the file with the same name minus the
* ".DELETED" suffix will still apply.		* ".DELETED" suffix will still apply.
* (the default behavior is to hide both the suffixed and unsuffixed files)		* (the default behavior is to hide both the suffixed and unsuffixed files)
**/		**/
VFS_MOUNT_KEEP_DELETED = 8,		VFS_MOUNT_KEEP_DELETED = 8

/**
* mark a directory replaceable, so that when writing a file to this path
* new real directories will be created instead of reusing already existing
* ones mounted at a subpath of the VFS path.
* (the default behaviour is to write to the real directory associated
* with the VFS directory that was last mounted to this path (or subpath))
**/
VFS_MOUNT_REPLACEABLE = 16
};		};

// (member functions are thread-safe after the instance has been		// (member functions are thread-safe after the instance has been
// constructed - each acquires a mutex.)		// constructed - each acquires a mutex.)
struct IVFS		struct IVFS
{		{
virtual ~IVFS() {}		virtual ~IVFS() {}

/**		/**
* mount a directory into the VFS.		* mount a directory into the VFS.
*		*
* @param mountPoint (will be created if it does not already exist)		* @param mountPoint (will be created if it does not already exist)
* @param path real directory path		* @param path real directory path
* @param flags		* @param flags
* @param priority		* @param priority
* @return Status.		* @return Status.
*		*
* if files are encountered that already exist in the VFS (sub)directories,		* if files are encountered that already exist in the VFS (sub)directories,
* the most recent / highest priority/precedence version is preferred.		* the most recent / highest priority/precedence version is preferred.
*		*
		* Note that the 'real directory' associated with a VFS Path
		* will be relative to the highest priority subdirectory in the path,
		* and that in case of equal priority, the order is _undefined_,
		* and will depend on the exact order of populate() calls.
		*
* if files with archive extensions are seen, their contents are added		* if files with archive extensions are seen, their contents are added
* as well.		* as well.
**/		**/
virtual Status Mount(const VfsPath& mountPoint, const OsPath& path, size_t flags = 0, size_t priority = 0) = 0;		virtual Status Mount(const VfsPath& mountPoint, const OsPath& path, size_t flags = 0, size_t priority = 0) = 0;

/**		/**
* Retrieve information about a file (similar to POSIX stat).		* Retrieve information about a file (similar to POSIX stat).
*		*
Show All 33 Lines	struct IVFS
* @param pathname		* @param pathname
* @param fileContents		* @param fileContents
* @param size [bytes] of the contents, will match that of the file.		* @param size [bytes] of the contents, will match that of the file.
* @return Status.		* @return Status.
**/		**/
virtual Status CreateFile(const VfsPath& pathname, const shared_ptr<u8>& fileContents, size_t size) = 0;		virtual Status CreateFile(const VfsPath& pathname, const shared_ptr<u8>& fileContents, size_t size) = 0;

/**		/**
* Replace a file with the given contents.
*
* @see CreateFile
*
* Used to replace a file if it is already present (even if the file is not
* in the attached vfs directory). Calls CreateFile if the file doesn't yet
* exist.
**/
virtual Status ReplaceFile(const VfsPath& pathname, const shared_ptr<u8>& fileContents, size_t size) = 0;

/**
* Read an entire file into memory.		* Read an entire file into memory.
*		*
* @param pathname		* @param pathname
* @param fileContents receives a smart pointer to the contents.		* @param fileContents receives a smart pointer to the contents.
* @param size receives the size [bytes] of the file contents.		* @param size receives the size [bytes] of the file contents.
* @return Status.		* @return Status.
**/		**/
virtual Status LoadFile(const VfsPath& pathname, shared_ptr<u8>& fileContents, size_t& size) = 0;		virtual Status LoadFile(const VfsPath& pathname, shared_ptr<u8>& fileContents, size_t& size) = 0;

/**		/**
* @return a string representation of all files and directories.		* @return a string representation of all files and directories.
**/		**/
virtual std::wstring TextRepresentation() const = 0;		virtual std::wstring TextRepresentation() const = 0;

/**		/**
* retrieve the real (POSIX) pathname underlying a VFS file.		* Retrieve the POSIX pathname a VFS file was loaded from.
		* This is distinct from the current 'real' path, since that depends on the parent directory's real path,
		* which may have been overwritten by a mod or another call to Mount().
*		*
* this is useful for passing paths to external libraries.		* This is used by the caching to split by mod, and you also ought to call this to delete a file.
		* (note that deleting has other issues, see below).
**/		**/
virtual Status GetRealPath(const VfsPath& pathname, OsPath& realPathname) = 0;		virtual Status GetOriginalPath(const VfsPath& filename, OsPath& loadedPathname) = 0;

/**		/**
* retrieve the real (POSIX) pathname underlying a VFS directory.		* Retrieve the real (POSIX) pathname underlying a VFS file.
*		* This is useful for passing paths to external libraries.
* this is useful for passing paths to external libraries.		* Note that this returns the real path relative to the highest priority VFS subpath.
		* @param createMissingDirectories - if true, create subdirectories on the file system as required.
		* (this defaults to true because, in general, this function is then used to create new files).
		**/
		virtual Status GetRealPath(const VfsPath& pathname, OsPath& realPathname, bool createMissingDirectories = true) = 0;

		/**
		* Retrieve the real (POSIX) pathname underlying a VFS directory.
		* This is useful for passing paths to external libraries.
		* Note that this returns the real path relative to the highest priority VFS subpath.
		* @param createMissingDirectories - if true, create subdirectories on the file system as required.
		* (this defaults to true because, in general, this function is then used to create new files).
**/		**/
virtual Status GetDirectoryRealPath(const VfsPath& pathname, OsPath& realPathname) = 0;		virtual Status GetDirectoryRealPath(const VfsPath& pathname, OsPath& realPathname, bool createMissingDirectories = true) = 0;

/**		/**
* retrieve the VFS pathname that corresponds to a real file.		* retrieve the VFS pathname that corresponds to a real file.
*		*
* this is useful for reacting to file change notifications.		* this is useful for reacting to file change notifications.
*		*
* the current implementation requires time proportional to the		* the current implementation requires time proportional to the
* number of directories; this could be accelerated by only checking		* number of directories; this could be accelerated by only checking
Show All 36 Lines