1 // Copyright (C) 2002-2012 Nikolaus Gebhardt
\r
2 // This file is part of the "Irrlicht Engine".
\r
3 // For conditions of distribution and use, see copyright notice in irrlicht.h
\r
5 #ifndef __I_FILE_SYSTEM_H_INCLUDED__
\r
6 #define __I_FILE_SYSTEM_H_INCLUDED__
\r
8 #include "IReferenceCounted.h"
\r
9 #include "IFileArchive.h"
\r
16 } // end namespace video
\r
26 //! The FileSystem manages files and archives and provides access to them.
\r
27 /** It manages where files are, so that modules which use the the IO do not
\r
28 need to know where every file is located. A file could be in a .zip-Archive or
\r
29 as file on disk, using the IFileSystem makes no difference to this. */
\r
30 class IFileSystem : public virtual IReferenceCounted
\r
34 //! Opens a file for read access.
\r
35 /** \param filename: Name of file to open.
\r
36 \return Pointer to the created file interface.
\r
37 The returned pointer should be dropped when no longer needed.
\r
38 See IReferenceCounted::drop() for more information. */
\r
39 virtual IReadFile* createAndOpenFile(const path& filename) =0;
\r
41 //! Creates an IReadFile interface for accessing memory like a file.
\r
42 /** This allows you to use a pointer to memory where an IReadFile is requested.
\r
43 \param memory: A pointer to the start of the file in memory
\r
44 \param len: The length of the memory in bytes
\r
45 \param fileName: The name given to this file
\r
46 \param deleteMemoryWhenDropped: True if the memory should be deleted
\r
47 along with the IReadFile when it is dropped.
\r
48 \return Pointer to the created file interface.
\r
49 The returned pointer should be dropped when no longer needed.
\r
50 See IReferenceCounted::drop() for more information.
\r
52 virtual IReadFile* createMemoryReadFile(const void* memory, s32 len, const path& fileName, bool deleteMemoryWhenDropped=false) =0;
\r
54 //! Creates an IReadFile interface for accessing files inside files.
\r
55 /** This is useful e.g. for archives.
\r
56 \param fileName: The name given to this file
\r
57 \param alreadyOpenedFile: Pointer to the enclosing file
\r
58 \param pos: Start of the file inside alreadyOpenedFile
\r
59 \param areaSize: The length of the file
\r
60 \return A pointer to the created file interface.
\r
61 The returned pointer should be dropped when no longer needed.
\r
62 See IReferenceCounted::drop() for more information.
\r
64 virtual IReadFile* createLimitReadFile(const path& fileName,
\r
65 IReadFile* alreadyOpenedFile, long pos, long areaSize) =0;
\r
67 //! Creates an IWriteFile interface for accessing memory like a file.
\r
68 /** This allows you to use a pointer to memory where an IWriteFile is requested.
\r
69 You are responsible for allocating enough memory.
\r
70 \param memory: A pointer to the start of the file in memory (allocated by you)
\r
71 \param len: The length of the memory in bytes
\r
72 \param fileName: The name given to this file
\r
73 \param deleteMemoryWhenDropped: True if the memory should be deleted
\r
74 along with the IWriteFile when it is dropped.
\r
75 \return Pointer to the created file interface.
\r
76 The returned pointer should be dropped when no longer needed.
\r
77 See IReferenceCounted::drop() for more information.
\r
79 virtual IWriteFile* createMemoryWriteFile(void* memory, s32 len, const path& fileName, bool deleteMemoryWhenDropped=false) =0;
\r
82 //! Opens a file for write access.
\r
83 /** \param filename: Name of file to open.
\r
84 \param append: If the file already exist, all write operations are
\r
85 appended to the file.
\r
86 \return Pointer to the created file interface. 0 is returned, if the
\r
87 file could not created or opened for writing.
\r
88 The returned pointer should be dropped when no longer needed.
\r
89 See IReferenceCounted::drop() for more information. */
\r
90 virtual IWriteFile* createAndWriteFile(const path& filename, bool append=false) =0;
\r
92 //! Adds an archive to the file system.
\r
93 /** After calling this, the Irrlicht Engine will also search and open
\r
94 files directly from this archive. This is useful for hiding data from
\r
95 the end user, speeding up file access and making it possible to access
\r
96 for example Quake3 .pk3 files, which are just renamed .zip files. By
\r
97 default Irrlicht supports ZIP, PAK, TAR, PNK, and directories as
\r
98 archives. You can provide your own archive types by implementing
\r
99 IArchiveLoader and passing an instance to addArchiveLoader.
\r
100 Irrlicht supports AES-encrypted zip files, and the advanced compression
\r
101 techniques lzma and bzip2.
\r
102 \param filename: Filename of the archive to add to the file system.
\r
103 \param ignoreCase: If set to true, files in the archive can be accessed without
\r
104 writing all letters in the right case.
\r
105 \param ignorePaths: If set to true, files in the added archive can be accessed
\r
106 without its complete path.
\r
107 \param archiveType: If no specific E_FILE_ARCHIVE_TYPE is selected then
\r
108 the type of archive will depend on the extension of the file name. If
\r
109 you use a different extension then you can use this parameter to force
\r
110 a specific type of archive.
\r
111 \param password An optional password, which is used in case of encrypted archives.
\r
112 \param retArchive A pointer that will be set to the archive that is added.
\r
113 \return True if the archive was added successfully, false if not. */
\r
114 virtual bool addFileArchive(const path& filename, bool ignoreCase=true,
\r
115 bool ignorePaths=true,
\r
116 E_FILE_ARCHIVE_TYPE archiveType=EFAT_UNKNOWN,
\r
117 const core::stringc& password="",
\r
118 IFileArchive** retArchive=0) =0;
\r
120 //! Adds an archive to the file system.
\r
121 /** After calling this, the Irrlicht Engine will also search and open
\r
122 files directly from this archive. This is useful for hiding data from
\r
123 the end user, speeding up file access and making it possible to access
\r
124 for example Quake3 .pk3 files, which are just renamed .zip files. By
\r
125 default Irrlicht supports ZIP, PAK, TAR, PNK, and directories as
\r
126 archives. You can provide your own archive types by implementing
\r
127 IArchiveLoader and passing an instance to addArchiveLoader.
\r
128 Irrlicht supports AES-encrypted zip files, and the advanced compression
\r
129 techniques lzma and bzip2.
\r
130 If you want to add a directory as an archive, prefix its name with a
\r
131 slash in order to let Irrlicht recognize it as a folder mount (mypath/).
\r
132 Using this technique one can build up a search order, because archives
\r
133 are read first, and can be used more easily with relative filenames.
\r
134 \param file: Archive to add to the file system.
\r
135 \param ignoreCase: If set to true, files in the archive can be accessed without
\r
136 writing all letters in the right case.
\r
137 \param ignorePaths: If set to true, files in the added archive can be accessed
\r
138 without its complete path.
\r
139 \param archiveType: If no specific E_FILE_ARCHIVE_TYPE is selected then
\r
140 the type of archive will depend on the extension of the file name. If
\r
141 you use a different extension then you can use this parameter to force
\r
142 a specific type of archive.
\r
143 \param password An optional password, which is used in case of encrypted archives.
\r
144 \param retArchive A pointer that will be set to the archive that is added.
\r
145 \return True if the archive was added successfully, false if not. */
\r
146 virtual bool addFileArchive(IReadFile* file, bool ignoreCase=true,
\r
147 bool ignorePaths=true,
\r
148 E_FILE_ARCHIVE_TYPE archiveType=EFAT_UNKNOWN,
\r
149 const core::stringc& password="",
\r
150 IFileArchive** retArchive=0) =0;
\r
152 //! Adds an archive to the file system.
\r
153 /** \param archive: The archive to add to the file system.
\r
154 \return True if the archive was added successfully, false if not. */
\r
155 virtual bool addFileArchive(IFileArchive* archive) =0;
\r
157 //! Get the number of archives currently attached to the file system
\r
158 virtual u32 getFileArchiveCount() const =0;
\r
160 //! Removes an archive from the file system.
\r
161 /** This will close the archive and free any file handles, but will not
\r
162 close resources which have already been loaded and are now cached, for
\r
163 example textures and meshes.
\r
164 \param index: The index of the archive to remove
\r
165 \return True on success, false on failure */
\r
166 virtual bool removeFileArchive(u32 index) =0;
\r
168 //! Removes an archive from the file system.
\r
169 /** This will close the archive and free any file handles, but will not
\r
170 close resources which have already been loaded and are now cached, for
\r
171 example textures and meshes. Note that a relative filename might be
\r
172 interpreted differently on each call, depending on the current working
\r
173 directory. In case you want to remove an archive that was added using
\r
174 a relative path name, you have to change to the same working directory
\r
175 again. This means, that the filename given on creation is not an
\r
176 identifier for the archive, but just a usual filename that is used for
\r
177 locating the archive to work with.
\r
178 \param filename The archive pointed to by the name will be removed
\r
179 \return True on success, false on failure */
\r
180 virtual bool removeFileArchive(const path& filename) =0;
\r
182 //! Removes an archive from the file system.
\r
183 /** This will close the archive and free any file handles, but will not
\r
184 close resources which have already been loaded and are now cached, for
\r
185 example textures and meshes.
\r
186 \param archive The archive to remove.
\r
187 \return True on success, false on failure */
\r
188 virtual bool removeFileArchive(const IFileArchive* archive) =0;
\r
190 //! Changes the search order of attached archives.
\r
192 \param sourceIndex: The index of the archive to change
\r
193 \param relative: The relative change in position, archives with a lower index are searched first */
\r
194 virtual bool moveFileArchive(u32 sourceIndex, s32 relative) =0;
\r
196 //! Get the archive at a given index.
\r
197 virtual IFileArchive* getFileArchive(u32 index) =0;
\r
199 //! Adds an external archive loader to the engine.
\r
200 /** Use this function to add support for new archive types to the
\r
201 engine, for example proprietary or encrypted file storage. */
\r
202 virtual void addArchiveLoader(IArchiveLoader* loader) =0;
\r
204 //! Gets the number of archive loaders currently added
\r
205 virtual u32 getArchiveLoaderCount() const = 0;
\r
207 //! Retrieve the given archive loader
\r
208 /** \param index The index of the loader to retrieve. This parameter is an 0-based
\r
210 \return A pointer to the specified loader, 0 if the index is incorrect. */
\r
211 virtual IArchiveLoader* getArchiveLoader(u32 index) const = 0;
\r
213 //! Adds a zip archive to the file system.
\r
214 /** \deprecated This function is provided for compatibility
\r
215 with older versions of Irrlicht and may be removed in Irrlicht 1.9,
\r
216 you should use addFileArchive instead.
\r
217 After calling this, the Irrlicht Engine will search and open files directly from this archive too.
\r
218 This is useful for hiding data from the end user, speeding up file access and making it possible to
\r
219 access for example Quake3 .pk3 files, which are no different than .zip files.
\r
220 \param filename: Filename of the zip archive to add to the file system.
\r
221 \param ignoreCase: If set to true, files in the archive can be accessed without
\r
222 writing all letters in the right case.
\r
223 \param ignorePaths: If set to true, files in the added archive can be accessed
\r
224 without its complete path.
\r
225 \return True if the archive was added successfully, false if not. */
\r
226 _IRR_DEPRECATED_ virtual bool addZipFileArchive(const c8* filename, bool ignoreCase=true, bool ignorePaths=true)
\r
228 return addFileArchive(filename, ignoreCase, ignorePaths, EFAT_ZIP);
\r
231 //! Adds an unzipped archive (or basedirectory with subdirectories..) to the file system.
\r
232 /** \deprecated This function is provided for compatibility
\r
233 with older versions of Irrlicht and may be removed in Irrlicht 1.9,
\r
234 you should use addFileArchive instead.
\r
235 Useful for handling data which will be in a zip file
\r
236 \param filename: Filename of the unzipped zip archive base directory to add to the file system.
\r
237 \param ignoreCase: If set to true, files in the archive can be accessed without
\r
238 writing all letters in the right case.
\r
239 \param ignorePaths: If set to true, files in the added archive can be accessed
\r
240 without its complete path.
\r
241 \return True if the archive was added successful, false if not. */
\r
242 _IRR_DEPRECATED_ virtual bool addFolderFileArchive(const c8* filename, bool ignoreCase=true, bool ignorePaths=true)
\r
244 return addFileArchive(filename, ignoreCase, ignorePaths, EFAT_FOLDER);
\r
247 //! Adds a pak archive to the file system.
\r
248 /** \deprecated This function is provided for compatibility
\r
249 with older versions of Irrlicht and may be removed in Irrlicht 1.9,
\r
250 you should use addFileArchive instead.
\r
251 After calling this, the Irrlicht Engine will search and open files directly from this archive too.
\r
252 This is useful for hiding data from the end user, speeding up file access and making it possible to
\r
253 access for example Quake2/KingPin/Hexen2 .pak files
\r
254 \param filename: Filename of the pak archive to add to the file system.
\r
255 \param ignoreCase: If set to true, files in the archive can be accessed without
\r
256 writing all letters in the right case.
\r
257 \param ignorePaths: If set to true, files in the added archive can be accessed
\r
258 without its complete path.(should not use with Quake2 paks
\r
259 \return True if the archive was added successful, false if not. */
\r
260 _IRR_DEPRECATED_ virtual bool addPakFileArchive(const c8* filename, bool ignoreCase=true, bool ignorePaths=true)
\r
262 return addFileArchive(filename, ignoreCase, ignorePaths, EFAT_PAK);
\r
265 //! Get the current working directory.
\r
266 /** \return Current working directory as a string. */
\r
267 virtual const path& getWorkingDirectory() =0;
\r
269 //! Changes the current working directory.
\r
270 /** \param newDirectory: A string specifying the new working directory.
\r
271 The string is operating system dependent. Under Windows it has
\r
272 the form "<drive>:\<directory>\<sudirectory>\<..>". An example would be: "C:\Windows\"
\r
273 \return True if successful, otherwise false. */
\r
274 virtual bool changeWorkingDirectoryTo(const path& newDirectory) =0;
\r
276 //! Converts a relative path to an absolute (unique) path, resolving symbolic links if required
\r
277 /** \param filename Possibly relative file or directory name to query.
\r
278 \result Absolute filename which points to the same file. */
\r
279 virtual path getAbsolutePath(const path& filename) const =0;
\r
281 //! Get the directory a file is located in.
\r
282 /** \param filename: The file to get the directory from.
\r
283 \return String containing the directory of the file. */
\r
284 virtual path getFileDir(const path& filename) const =0;
\r
286 //! Get the base part of a filename, i.e. the name without the directory part.
\r
287 /** If no directory is prefixed, the full name is returned.
\r
288 \param filename: The file to get the basename from
\r
289 \param keepExtension True if filename with extension is returned otherwise everything
\r
290 after the final '.' is removed as well. */
\r
291 virtual path getFileBasename(const path& filename, bool keepExtension=true) const =0;
\r
293 //! flatten a path and file name for example: "/you/me/../." becomes "/you"
\r
294 virtual path& flattenFilename(path& directory, const path& root="/") const =0;
\r
296 //! Get the relative filename, relative to the given directory
\r
297 virtual path getRelativeFilename(const path& filename, const path& directory) const =0;
\r
299 //! Creates a list of files and directories in the current working directory and returns it.
\r
300 /** \return a Pointer to the created IFileList is returned. After the list has been used
\r
301 it has to be deleted using its IFileList::drop() method.
\r
302 See IReferenceCounted::drop() for more information. */
\r
303 virtual IFileList* createFileList() =0;
\r
305 //! Creates an empty filelist
\r
306 /** \return a Pointer to the created IFileList is returned. After the list has been used
\r
307 it has to be deleted using its IFileList::drop() method.
\r
308 See IReferenceCounted::drop() for more information. */
\r
309 virtual IFileList* createEmptyFileList(const io::path& path, bool ignoreCase, bool ignorePaths) =0;
\r
311 //! Set the active type of file system.
\r
312 virtual EFileSystemType setFileListSystem(EFileSystemType listType) =0;
\r
314 //! Determines if a file exists and could be opened.
\r
315 /** \param filename is the string identifying the file which should be tested for existence.
\r
316 \return True if file exists, and false if it does not exist or an error occurred. */
\r
317 virtual bool existFile(const path& filename) const =0;
\r
321 } // end namespace io
\r
322 } // end namespace irr
\r
projects / irrlicht.git / blob