Cafu Engine
FileMan.hpp
1 /*
2 Cafu Engine, http://www.cafu.de/
3 Copyright (c) Carsten Fuchs and other contributors.
4 This project is licensed under the terms of the MIT license.
5 */
6 
7 #ifndef CAFU_FILESYS_FILEMAN_HPP_INCLUDED
8 #define CAFU_FILESYS_FILEMAN_HPP_INCLUDED
9 
10 #include <string>
11 
12 
13 namespace cf
14 {
15  namespace FileSys
16  {
17  class FileSystemT;
18  class FileI;
19  class InFileI;
20 
21  enum FileSystemTypeT
22  {
23  FS_TYPE_LOCAL_PATH,
24  FS_TYPE_ZIP_ARCHIVE
25  };
26 
27 
28  /// This class provides an interface to a file manager.
29  /// The interface is specified as an ABC in order to be able to share it across exe/dll boundaries.
30  class FileManI
31  {
32  public:
33 
34  /// The destructor.
35  /// This ABC does neither have nor need a destructor, because no implementation will ever be deleted via a pointer to a FileManI.
36  /// (The implementations are singletons after all.) See the Singleton pattern and the C++ FAQ 21.05 (the "precise rule") for more information.
37  /// g++ however issues a warning with no such destructor, so I provide one anyway and am safe.
38  virtual ~FileManI() { }
39 
40  /// "Mounts" (or "registers") a new file system into the scope of the file manager.
41  /// For example, you can register paths on a local hard-disk, compressed archives and HTTP connections as file systems.
42  /// @param Type The type of the file system to be mounted.
43  /// @param Descr A description/specification of the file system to be mounted, for example "Games/DeathMatch/", "MyArchive.zip", etc.
44  /// @param MountPoint The mount point of the file system, i.e. the path where the contents of the file system is attached to.
45  /// @param Password The password string that might be required to access the specified file system (e.g. encrypted zip archives).
46  /// @returns a handle to the mounted file system, or NULL on error. Note that the handle is "opaque" for the user code.
47  /// That is, it can do nothing with it but check it for NULL in order to learn if an error occurred, and pass it to Unregister() later.
48  /// Also note that a mount failure (getting a NULL result) here is not necessarily reason enough to terminate the entire application -
49  /// the file manager is robust enough to deal with the situation (i.e. you can pass NULL to Unregister()), but of course opening files
50  /// that are supposed to be in the file system that failed to mount will not succeed.
51  virtual FileSystemT* MountFileSystem(FileSystemTypeT Type, const std::string& Descr, const std::string& MountPoint, const std::string& Password="")=0;
52 
53  /// "Unmounts" (or "unregisters") a file system from the file manager.
54  /// @param FileSystem The handle to the file system that was obtained by the call to MountFileSystem.
55  virtual void Unmount(FileSystemT* FileSystem)=0;
56 
57  /// Opens the file with the given name for reading.
58  /// The registered file systems are probed in opposite order in which they have been registered for opening the file.
59  /// @param FileName The name of the file to be opened within one of the previously registered file systems.
60  /// @returns The pointer to the file or NULL if the file could not be opened.
61  virtual InFileI* OpenRead(const std::string& FileName)=0;
62 
63  /// Closes the given file.
64  virtual void Close(FileI* File)=0;
65  };
66 
67 
68  /// A global pointer to an implementation of the FileManI interface.
69  ///
70  /// Each module (exe or dll) that uses this pointer must somewhere provide exactly one definition for it (none is provided by the FileSys library).
71  /// That is, typically the main.cpp or similar file of each exe and dll must contain a line like
72  /// cf::FileSys::FileManI* cf::FileSys::FileMan=NULL;
73  /// or else the module will not link successfully due to an undefined symbol.
74  ///
75  /// Exe files will then want to reset this pointer to an instance of a FileManImplT during their initialization
76  /// e.g. by code like: cf::FileSys::FileMan=new cf::FileSys::FileManImplT;
77  /// Note that the FileManImplT ctor may require that other interfaces (e.g. the MatSys) have been inited first.
78  ///
79  /// Dlls typically get one of their init functions called immediately after they have been loaded.
80  /// By doing so, the exe passes a pointer to its above instance to the dll, which in turn copies it to its FileMan variable.
81  extern FileManI* FileMan;
82  }
83 }
84 
85 #endif
virtual void Close(FileI *File)=0
Closes the given file.
Definition: File.hpp:55
Definition: FileSys.hpp:42
virtual InFileI * OpenRead(const std::string &FileName)=0
Opens the file with the given name for reading.
virtual ~FileManI()
The destructor.
Definition: FileMan.hpp:38
virtual void Unmount(FileSystemT *FileSystem)=0
"Unmounts" (or "unregisters") a file system from the file manager.
Definition: File.hpp:23
virtual FileSystemT * MountFileSystem(FileSystemTypeT Type, const std::string &Descr, const std::string &MountPoint, const std::string &Password="")=0
"Mounts" (or "registers") a new file system into the scope of the file manager.
This class provides an interface to a file manager.
Definition: FileMan.hpp:30