2
0

IFileSystem.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265
  1. // Copyright (C) 2002-2012 Nikolaus Gebhardt
  2. // This file is part of the "Irrlicht Engine".
  3. // For conditions of distribution and use, see copyright notice in irrlicht.h
  4. #pragma once
  5. #include "IReferenceCounted.h"
  6. #include "IFileArchive.h"
  7. namespace irr
  8. {
  9. namespace video
  10. {
  11. class IVideoDriver;
  12. } // end namespace video
  13. namespace io
  14. {
  15. class IReadFile;
  16. class IWriteFile;
  17. class IFileList;
  18. class IAttributes;
  19. //! The FileSystem manages files and archives and provides access to them.
  20. /** It manages where files are, so that modules which use the the IO do not
  21. need to know where every file is located. A file could be in a .zip-Archive or
  22. as file on disk, using the IFileSystem makes no difference to this. */
  23. class IFileSystem : public virtual IReferenceCounted
  24. {
  25. public:
  26. //! Opens a file for read access.
  27. /** \param filename: Name of file to open.
  28. \return Pointer to the created file interface.
  29. The returned pointer should be dropped when no longer needed.
  30. See IReferenceCounted::drop() for more information. */
  31. virtual IReadFile *createAndOpenFile(const path &filename) = 0;
  32. //! Creates an IReadFile interface for accessing memory like a file.
  33. /** This allows you to use a pointer to memory where an IReadFile is requested.
  34. \param memory: A pointer to the start of the file in memory
  35. \param len: The length of the memory in bytes
  36. \param fileName: The name given to this file
  37. \param deleteMemoryWhenDropped: True if the memory should be deleted
  38. along with the IReadFile when it is dropped.
  39. \return Pointer to the created file interface.
  40. The returned pointer should be dropped when no longer needed.
  41. See IReferenceCounted::drop() for more information.
  42. */
  43. virtual IReadFile *createMemoryReadFile(const void *memory, s32 len, const path &fileName, bool deleteMemoryWhenDropped = false) = 0;
  44. //! Creates an IReadFile interface for accessing files inside files.
  45. /** This is useful e.g. for archives.
  46. \param fileName: The name given to this file
  47. \param alreadyOpenedFile: Pointer to the enclosing file
  48. \param pos: Start of the file inside alreadyOpenedFile
  49. \param areaSize: The length of the file
  50. \return A pointer to the created file interface.
  51. The returned pointer should be dropped when no longer needed.
  52. See IReferenceCounted::drop() for more information.
  53. */
  54. virtual IReadFile *createLimitReadFile(const path &fileName,
  55. IReadFile *alreadyOpenedFile, long pos, long areaSize) = 0;
  56. //! Creates an IWriteFile interface for accessing memory like a file.
  57. /** This allows you to use a pointer to memory where an IWriteFile is requested.
  58. You are responsible for allocating enough memory.
  59. \param memory: A pointer to the start of the file in memory (allocated by you)
  60. \param len: The length of the memory in bytes
  61. \param fileName: The name given to this file
  62. \param deleteMemoryWhenDropped: True if the memory should be deleted
  63. along with the IWriteFile when it is dropped.
  64. \return Pointer to the created file interface.
  65. The returned pointer should be dropped when no longer needed.
  66. See IReferenceCounted::drop() for more information.
  67. */
  68. virtual IWriteFile *createMemoryWriteFile(void *memory, s32 len, const path &fileName, bool deleteMemoryWhenDropped = false) = 0;
  69. //! Opens a file for write access.
  70. /** \param filename: Name of file to open.
  71. \param append: If the file already exist, all write operations are
  72. appended to the file.
  73. \return Pointer to the created file interface. 0 is returned, if the
  74. file could not created or opened for writing.
  75. The returned pointer should be dropped when no longer needed.
  76. See IReferenceCounted::drop() for more information. */
  77. virtual IWriteFile *createAndWriteFile(const path &filename, bool append = false) = 0;
  78. //! Adds an archive to the file system.
  79. /** After calling this, the Irrlicht Engine will also search and open
  80. files directly from this archive. This is useful for hiding data from
  81. the end user, speeding up file access and making it possible to access
  82. for example Quake3 .pk3 files, which are just renamed .zip files. By
  83. default Irrlicht supports ZIP, PAK, TAR, PNK, and directories as
  84. archives. You can provide your own archive types by implementing
  85. IArchiveLoader and passing an instance to addArchiveLoader.
  86. Irrlicht supports AES-encrypted zip files, and the advanced compression
  87. techniques lzma and bzip2.
  88. \param filename: Filename of the archive to add to the file system.
  89. \param ignoreCase: If set to true, files in the archive can be accessed without
  90. writing all letters in the right case.
  91. \param ignorePaths: If set to true, files in the added archive can be accessed
  92. without its complete path.
  93. \param archiveType: If no specific E_FILE_ARCHIVE_TYPE is selected then
  94. the type of archive will depend on the extension of the file name. If
  95. you use a different extension then you can use this parameter to force
  96. a specific type of archive.
  97. \param password An optional password, which is used in case of encrypted archives.
  98. \param retArchive A pointer that will be set to the archive that is added.
  99. \return True if the archive was added successfully, false if not. */
  100. virtual bool addFileArchive(const path &filename, bool ignoreCase = true,
  101. bool ignorePaths = true,
  102. E_FILE_ARCHIVE_TYPE archiveType = EFAT_UNKNOWN,
  103. const core::stringc &password = "",
  104. IFileArchive **retArchive = 0) = 0;
  105. //! Adds an archive to the file system.
  106. /** After calling this, the Irrlicht Engine will also search and open
  107. files directly from this archive. This is useful for hiding data from
  108. the end user, speeding up file access and making it possible to access
  109. for example Quake3 .pk3 files, which are just renamed .zip files. By
  110. default Irrlicht supports ZIP, PAK, TAR, PNK, and directories as
  111. archives. You can provide your own archive types by implementing
  112. IArchiveLoader and passing an instance to addArchiveLoader.
  113. Irrlicht supports AES-encrypted zip files, and the advanced compression
  114. techniques lzma and bzip2.
  115. If you want to add a directory as an archive, prefix its name with a
  116. slash in order to let Irrlicht recognize it as a folder mount (mypath/).
  117. Using this technique one can build up a search order, because archives
  118. are read first, and can be used more easily with relative filenames.
  119. \param file: Archive to add to the file system.
  120. \param ignoreCase: If set to true, files in the archive can be accessed without
  121. writing all letters in the right case.
  122. \param ignorePaths: If set to true, files in the added archive can be accessed
  123. without its complete path.
  124. \param archiveType: If no specific E_FILE_ARCHIVE_TYPE is selected then
  125. the type of archive will depend on the extension of the file name. If
  126. you use a different extension then you can use this parameter to force
  127. a specific type of archive.
  128. \param password An optional password, which is used in case of encrypted archives.
  129. \param retArchive A pointer that will be set to the archive that is added.
  130. \return True if the archive was added successfully, false if not. */
  131. virtual bool addFileArchive(IReadFile *file, bool ignoreCase = true,
  132. bool ignorePaths = true,
  133. E_FILE_ARCHIVE_TYPE archiveType = EFAT_UNKNOWN,
  134. const core::stringc &password = "",
  135. IFileArchive **retArchive = 0) = 0;
  136. //! Adds an archive to the file system.
  137. /** \param archive: The archive to add to the file system.
  138. \return True if the archive was added successfully, false if not. */
  139. virtual bool addFileArchive(IFileArchive *archive) = 0;
  140. //! Get the number of archives currently attached to the file system
  141. virtual u32 getFileArchiveCount() const = 0;
  142. //! Removes an archive from the file system.
  143. /** This will close the archive and free any file handles, but will not
  144. close resources which have already been loaded and are now cached, for
  145. example textures and meshes.
  146. \param index: The index of the archive to remove
  147. \return True on success, false on failure */
  148. virtual bool removeFileArchive(u32 index) = 0;
  149. //! Removes an archive from the file system.
  150. /** This will close the archive and free any file handles, but will not
  151. close resources which have already been loaded and are now cached, for
  152. example textures and meshes. Note that a relative filename might be
  153. interpreted differently on each call, depending on the current working
  154. directory. In case you want to remove an archive that was added using
  155. a relative path name, you have to change to the same working directory
  156. again. This means, that the filename given on creation is not an
  157. identifier for the archive, but just a usual filename that is used for
  158. locating the archive to work with.
  159. \param filename The archive pointed to by the name will be removed
  160. \return True on success, false on failure */
  161. virtual bool removeFileArchive(const path &filename) = 0;
  162. //! Removes an archive from the file system.
  163. /** This will close the archive and free any file handles, but will not
  164. close resources which have already been loaded and are now cached, for
  165. example textures and meshes.
  166. \param archive The archive to remove.
  167. \return True on success, false on failure */
  168. virtual bool removeFileArchive(const IFileArchive *archive) = 0;
  169. //! Changes the search order of attached archives.
  170. /**
  171. \param sourceIndex: The index of the archive to change
  172. \param relative: The relative change in position, archives with a lower index are searched first */
  173. virtual bool moveFileArchive(u32 sourceIndex, s32 relative) = 0;
  174. //! Get the archive at a given index.
  175. virtual IFileArchive *getFileArchive(u32 index) = 0;
  176. //! Adds an external archive loader to the engine.
  177. /** Use this function to add support for new archive types to the
  178. engine, for example proprietary or encrypted file storage. */
  179. virtual void addArchiveLoader(IArchiveLoader *loader) = 0;
  180. //! Gets the number of archive loaders currently added
  181. virtual u32 getArchiveLoaderCount() const = 0;
  182. //! Retrieve the given archive loader
  183. /** \param index The index of the loader to retrieve. This parameter is an 0-based
  184. array index.
  185. \return A pointer to the specified loader, 0 if the index is incorrect. */
  186. virtual IArchiveLoader *getArchiveLoader(u32 index) const = 0;
  187. //! Get the current working directory.
  188. /** \return Current working directory as a string. */
  189. virtual const path &getWorkingDirectory() = 0;
  190. //! Changes the current working directory.
  191. /** \param newDirectory: A string specifying the new working directory.
  192. The string is operating system dependent. Under Windows it has
  193. the form "<drive>:\<directory>\<sudirectory>\<..>". An example would be: "C:\Windows\"
  194. \return True if successful, otherwise false. */
  195. virtual bool changeWorkingDirectoryTo(const path &newDirectory) = 0;
  196. //! Converts a relative path to an absolute (unique) path, resolving symbolic links if required
  197. /** \param filename Possibly relative file or directory name to query.
  198. \result Absolute filename which points to the same file. */
  199. virtual path getAbsolutePath(const path &filename) const = 0;
  200. //! Get the directory a file is located in.
  201. /** \param filename: The file to get the directory from.
  202. \return String containing the directory of the file. */
  203. virtual path getFileDir(const path &filename) const = 0;
  204. //! Get the base part of a filename, i.e. the name without the directory part.
  205. /** If no directory is prefixed, the full name is returned.
  206. \param filename: The file to get the basename from
  207. \param keepExtension True if filename with extension is returned otherwise everything
  208. after the final '.' is removed as well. */
  209. virtual path getFileBasename(const path &filename, bool keepExtension = true) const = 0;
  210. //! flatten a path and file name for example: "/you/me/../." becomes "/you"
  211. virtual path &flattenFilename(path &directory, const path &root = "/") const = 0;
  212. //! Get the relative filename, relative to the given directory
  213. virtual path getRelativeFilename(const path &filename, const path &directory) const = 0;
  214. //! Creates a list of files and directories in the current working directory and returns it.
  215. /** \return a Pointer to the created IFileList is returned. After the list has been used
  216. it has to be deleted using its IFileList::drop() method.
  217. See IReferenceCounted::drop() for more information. */
  218. virtual IFileList *createFileList() = 0;
  219. //! Creates an empty filelist
  220. /** \return a Pointer to the created IFileList is returned. After the list has been used
  221. it has to be deleted using its IFileList::drop() method.
  222. See IReferenceCounted::drop() for more information. */
  223. virtual IFileList *createEmptyFileList(const io::path &path, bool ignoreCase, bool ignorePaths) = 0;
  224. //! Set the active type of file system.
  225. virtual EFileSystemType setFileListSystem(EFileSystemType listType) = 0;
  226. //! Determines if a file exists and could be opened.
  227. /** \param filename is the string identifying the file which should be tested for existence.
  228. \return True if file exists, and false if it does not exist or an error occurred. */
  229. virtual bool existFile(const path &filename) const = 0;
  230. };
  231. } // end namespace io
  232. } // end namespace irr