irr/include/IFileArchive.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt/ Thomas Alten
   2 // This file is part of the "Irrlicht Engine".
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h
   4
   5 #pragma once
   6
   7 #include "IReadFile.h"
   8 #include "IFileList.h"
   9
  10 namespace irr
  11 {
  12
  13 namespace io
  14 {
  15
  16 //! FileSystemType: which filesystem should be used for e.g. browsing
  17 enum EFileSystemType
  18 {
  19         FILESYSTEM_NATIVE = 0, // Native OS FileSystem
  20         FILESYSTEM_VIRTUAL     // Virtual FileSystem
  21 };
  22
  23 //! Contains the different types of archives
  24 enum E_FILE_ARCHIVE_TYPE
  25 {
  26         //! A PKZIP archive
  27         EFAT_ZIP = MAKE_IRR_ID('Z', 'I', 'P', 0),
  28
  29         //! A gzip archive
  30         EFAT_GZIP = MAKE_IRR_ID('g', 'z', 'i', 'p'),
  31
  32         //! An Android asset file archive
  33         EFAT_ANDROID_ASSET = MAKE_IRR_ID('A', 'S', 'S', 'E'),
  34
  35         //! The type of this archive is unknown
  36         EFAT_UNKNOWN = MAKE_IRR_ID('u', 'n', 'k', 'n')
  37 };
  38
  39 //! The FileArchive manages archives and provides access to files inside them.
  40 class IFileArchive : public virtual IReferenceCounted
  41 {
  42 public:
  43         //! Opens a file based on its name
  44         /** Creates and returns a new IReadFile for a file in the archive.
  45         \param filename The file to open
  46         \return Returns A pointer to the created file on success,
  47         or 0 on failure. */
  48         virtual IReadFile *createAndOpenFile(const path &filename) = 0;
  49
  50         //! Opens a file based on its position in the file list.
  51         /** Creates and returns
  52         \param index The zero based index of the file.
  53         \return Returns a pointer to the created file on success, or 0 on failure. */
  54         virtual IReadFile *createAndOpenFile(u32 index) = 0;
  55
  56         //! Returns the complete file tree
  57         /** \return Returns the complete directory tree for the archive,
  58         including all files and folders */
  59         virtual const IFileList *getFileList() const = 0;
  60
  61         //! get the archive type
  62         virtual E_FILE_ARCHIVE_TYPE getType() const { return EFAT_UNKNOWN; }
  63
  64         //! return the name (id) of the file Archive
  65         virtual const io::path &getArchiveName() const = 0;
  66
  67         //! Add a directory in the archive and all it's files to the FileList
  68         /** Only needed for file-archives which have no information about their own
  69         directory structure. In that case the user must add directories manually.
  70         Currently this is necessary for archives of type EFAT_ANDROID_ASSET.
  71         The root-path itself is already set by the engine.
  72         If directories are not added manually opening files might still work,
  73         but checks if file exists will fail.
  74         */
  75         virtual void addDirectoryToFileList(const io::path &filename) {}
  76
  77         //! An optionally used password string
  78         /** This variable is publicly accessible from the interface in order to
  79         avoid single access patterns to this place, and hence allow some more
  80         obscurity.
  81         */
  82         core::stringc Password;
  83 };
  84
  85 //! Class which is able to create an archive from a file.
  86 /** If you want the Irrlicht Engine be able to load archives of
  87 currently unsupported file formats (e.g .wad), then implement
  88 this and add your new Archive loader with
  89 IFileSystem::addArchiveLoader() to the engine. */
  90 class IArchiveLoader : public virtual IReferenceCounted
  91 {
  92 public:
  93         //! Check if the file might be loaded by this class
  94         /** Check based on the file extension (e.g. ".zip")
  95         \param filename Name of file to check.
  96         \return True if file seems to be loadable. */
  97         virtual bool isALoadableFileFormat(const path &filename) const = 0;
  98
  99         //! Check if the file might be loaded by this class
 100         /** This check may look into the file.
 101         \param file File handle to check.
 102         \return True if file seems to be loadable. */
 103         virtual bool isALoadableFileFormat(io::IReadFile *file) const = 0;
 104
 105         //! Check to see if the loader can create archives of this type.
 106         /** Check based on the archive type.
 107         \param fileType The archive type to check.
 108         \return True if the archive loader supports this type, false if not */
 109         virtual bool isALoadableFileFormat(E_FILE_ARCHIVE_TYPE fileType) const = 0;
 110
 111         //! Creates an archive from the filename
 112         /** \param filename File to use.
 113         \param ignoreCase Searching is performed without regarding the case
 114         \param ignorePaths Files are searched for without checking for the directories
 115         \return Pointer to newly created archive, or 0 upon error. */
 116         virtual IFileArchive *createArchive(const path &filename, bool ignoreCase, bool ignorePaths) const = 0;
 117
 118         //! Creates an archive from the file
 119         /** \param file File handle to use.
 120         \param ignoreCase Searching is performed without regarding the case
 121         \param ignorePaths Files are searched for without checking for the directories
 122         \return Pointer to newly created archive, or 0 upon error. */
 123         virtual IFileArchive *createArchive(io::IReadFile *file, bool ignoreCase, bool ignorePaths) const = 0;
 124 };
 125
 126 } // end namespace io
 127 } // end namespace irr