1 /* ScummVM - Graphic Adventure Engine 2 * 3 * ScummVM is the legal property of its developers, whose names 4 * are too numerous to list here. Please refer to the COPYRIGHT 5 * file distributed with this source distribution. 6 * 7 * This program is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU General Public License 9 * as published by the Free Software Foundation; either version 2 10 * of the License, or (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 20 * 21 */ 22 23 #ifndef COMMON_FILE_H 24 #define COMMON_FILE_H 25 26 #include "common/scummsys.h" 27 #include "common/fs.h" 28 #include "common/noncopyable.h" 29 #include "common/str.h" 30 #include "common/stream.h" 31 32 namespace Common { 33 34 /** 35 * @defgroup common_files Files 36 * @ingroup common 37 * 38 * @brief API for operations on files. 39 * 40 * @{ 41 */ 42 43 class Archive; 44 45 /** 46 * @todo vital to document this core class properly!!! For both users and implementors 47 */ 48 class File : public SeekableReadStream, public NonCopyable { 49 protected: 50 /** File handle to the actual file; 0 if no file is open. */ 51 SeekableReadStream *_handle; 52 53 /** The name of this file, kept for debugging purposes. */ 54 String _name; 55 56 public: 57 File(); 58 virtual ~File(); 59 60 /** 61 * Check if a given file exists in any of the current default paths, 62 * as defined by SearchMan. 63 * 64 * @param filename The file to check for. 65 * @return True if the file exists, false otherwise. 66 */ 67 static bool exists(const Path &filename); 68 69 /** 70 * Try to open the file with the given file name, by searching SearchMan. 71 * @note Must not be called if this file is already open (i.e. if isOpen returns true). 72 * 73 * @param filename Name of the file to open. 74 * @return True if the file was opened successfully, false otherwise. 75 */ 76 virtual bool open(const Path &filename); 77 78 /** 79 * Try to open the file with the given file name from within the given archive. 80 * @note Must not be called if this file is already open (i.e. if isOpen returns true). 81 * 82 * @param filename Name of the file to open. 83 * @param archive Archive in which to search for the file. 84 * @return True if the file was opened successfully, false otherwise. 85 */ 86 virtual bool open(const Path &filename, Archive &archive); 87 88 /** 89 * Try to open the file corresponding to the given node. Will check whether the 90 * node actually refers to an existing file (and not a directory), and handle 91 * those cases gracefully. 92 * @note Must not be called if this file already is open (i.e. if isOpen returns true). 93 * 94 * @param node The node to consider. 95 * @return True if the file was opened successfully, false otherwise. 96 */ 97 virtual bool open(const FSNode &node); 98 99 /** 100 * Try to 'open' the given stream. That is, wrap around it, and if the stream 101 * is a NULL pointer, gracefully treat this as if opening failed. 102 * @note Must not be called if this file already is open (i.e. if isOpen returns true). 103 * 104 * @param stream Pointer to a SeekableReadStream, or 0. 105 * @param name String describing the 'file' corresponding to the stream. 106 * @return True if the stream was non-zero, false otherwise. 107 */ 108 virtual bool open(SeekableReadStream *stream, const String &name); 109 110 /** 111 * Close the file, if open. 112 */ 113 virtual void close(); 114 115 /** 116 * Check if the object opened a file successfully. 117 * 118 * @return True if any file is opened, false otherwise. 119 */ 120 bool isOpen() const; 121 122 /** 123 * Return the file name of the opened file for debugging purposes. 124 * 125 * @return The file name of the opened file. 126 */ getName()127 const char *getName() const { return _name.c_str(); } 128 129 bool err() const override; /*!< Implement abstract Stream method. */ 130 void clearErr() override; /*!< Implement abstract Stream method. */ 131 bool eos() const override; /*!< Implement abstract SeekableReadStream method. */ 132 133 int64 pos() const override; /*!< Implement abstract SeekableReadStream method. */ 134 int64 size() const override; /*!< Implement abstract SeekableReadStream method. */ 135 bool seek(int64 offs, int whence = SEEK_SET) override; /*!< Implement abstract SeekableReadStream method. */ 136 uint32 read(void *dataPtr, uint32 dataSize) override; /*!< Implement abstract SeekableReadStream method. */ 137 }; 138 139 140 /** 141 * @todo Document this class 142 * 143 * Some design ideas: 144 * - automatically drop all files into dumps/ dir? Might not be desired in all cases 145 */ 146 class DumpFile : public SeekableWriteStream, public NonCopyable { 147 protected: 148 /** File handle to the actual file. 0 if no file is open. */ 149 WriteStream *_handle; 150 151 public: 152 DumpFile(); 153 virtual ~DumpFile(); 154 155 virtual bool open(const String &filename, bool createPath = false); 156 virtual bool open(const FSNode &node); 157 158 virtual void close(); 159 160 /** 161 * Check if the object opened a file successfully. 162 * 163 * @return True if any file is opened, false otherwise. 164 */ 165 bool isOpen() const; 166 167 bool err() const override; 168 void clearErr() override; 169 170 virtual uint32 write(const void *dataPtr, uint32 dataSize) override; 171 172 virtual bool flush() override; 173 174 virtual int64 pos() const override; 175 176 virtual bool seek(int64 offset, int whence = SEEK_SET) override; 177 virtual int64 size() const override; 178 }; 179 180 /** @} */ 181 182 } // End of namespace Common 183 184 #endif 185