1 #ifndef QUA_ZIPFILE_H 2 #define QUA_ZIPFILE_H 3 4 /* 5 Copyright (C) 2005-2014 Sergey A. Tachenov 6 7 This file is part of QuaZIP. 8 9 QuaZIP is free software: you can redistribute it and/or modify 10 it under the terms of the GNU Lesser General Public License as published by 11 the Free Software Foundation, either version 2.1 of the License, or 12 (at your option) any later version. 13 14 QuaZIP is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public License 20 along with QuaZIP. If not, see <http://www.gnu.org/licenses/>. 21 22 See COPYING file for the full LGPL text. 23 24 Original ZIP package is copyrighted by Gilles Vollant, see 25 quazip/(un)zip.h files for details, basically it's zlib license. 26 **/ 27 28 #include <QIODevice> 29 30 #include "quazip_global.h" 31 #include "quazip.h" 32 #include "quazipnewinfo.h" 33 34 class QuaZipFilePrivate; 35 36 /// A file inside ZIP archive. 37 /** \class QuaZipFile quazipfile.h <quazip/quazipfile.h> 38 * This is the most interesting class. Not only it provides C++ 39 * interface to the ZIP/UNZIP package, but also integrates it with Qt by 40 * subclassing QIODevice. This makes possible to access files inside ZIP 41 * archive using QTextStream or QDataStream, for example. Actually, this 42 * is the main purpose of the whole QuaZIP library. 43 * 44 * You can either use existing QuaZip instance to create instance of 45 * this class or pass ZIP archive file name to this class, in which case 46 * it will create internal QuaZip object. See constructors' descriptions 47 * for details. Writing is only possible with the existing instance. 48 * 49 * Note that due to the underlying library's limitation it is not 50 * possible to use multiple QuaZipFile instances to open several files 51 * in the same archive at the same time. If you need to write to 52 * multiple files in parallel, then you should write to temporary files 53 * first, then pack them all at once when you have finished writing. If 54 * you need to read multiple files inside the same archive in parallel, 55 * you should extract them all into a temporary directory first. 56 * 57 * \section quazipfile-sequential Sequential or random-access? 58 * 59 * At the first thought, QuaZipFile has fixed size, the start and the 60 * end and should be therefore considered random-access device. But 61 * there is one major obstacle to making it random-access: ZIP/UNZIP API 62 * does not support seek() operation and the only way to implement it is 63 * through reopening the file and re-reading to the required position, 64 * but this is prohibitively slow. 65 * 66 * Therefore, QuaZipFile is considered to be a sequential device. This 67 * has advantage of availability of the ungetChar() operation (QIODevice 68 * does not implement it properly for non-sequential devices unless they 69 * support seek()). Disadvantage is a somewhat strange behaviour of the 70 * size() and pos() functions. This should be kept in mind while using 71 * this class. 72 * 73 **/ 74 class QUAZIP_EXPORT QuaZipFile: public QIODevice { 75 friend class QuaZipFilePrivate; 76 Q_OBJECT 77 private: 78 QuaZipFilePrivate *p; 79 // these are not supported nor implemented 80 QuaZipFile(const QuaZipFile& that); 81 QuaZipFile& operator=(const QuaZipFile& that); 82 protected: 83 /// Implementation of the QIODevice::readData(). 84 qint64 readData(char *data, qint64 maxSize); 85 /// Implementation of the QIODevice::writeData(). 86 qint64 writeData(const char *data, qint64 maxSize); 87 public: 88 /// Constructs a QuaZipFile instance. 89 /** You should use setZipName() and setFileName() or setZip() before 90 * trying to call open() on the constructed object. 91 **/ 92 QuaZipFile(); 93 /// Constructs a QuaZipFile instance. 94 /** \a parent argument specifies this object's parent object. 95 * 96 * You should use setZipName() and setFileName() or setZip() before 97 * trying to call open() on the constructed object. 98 **/ 99 QuaZipFile(QObject *parent); 100 /// Constructs a QuaZipFile instance. 101 /** \a parent argument specifies this object's parent object and \a 102 * zipName specifies ZIP archive file name. 103 * 104 * You should use setFileName() before trying to call open() on the 105 * constructed object. 106 * 107 * QuaZipFile constructed by this constructor can be used for read 108 * only access. Use QuaZipFile(QuaZip*,QObject*) for writing. 109 **/ 110 QuaZipFile(const QString& zipName, QObject *parent =NULL); 111 /// Constructs a QuaZipFile instance. 112 /** \a parent argument specifies this object's parent object, \a 113 * zipName specifies ZIP archive file name and \a fileName and \a cs 114 * specify a name of the file to open inside archive. 115 * 116 * QuaZipFile constructed by this constructor can be used for read 117 * only access. Use QuaZipFile(QuaZip*,QObject*) for writing. 118 * 119 * \sa QuaZip::setCurrentFile() 120 **/ 121 QuaZipFile(const QString& zipName, const QString& fileName, 122 QuaZip::CaseSensitivity cs =QuaZip::csDefault, QObject *parent =NULL); 123 /// Constructs a QuaZipFile instance. 124 /** \a parent argument specifies this object's parent object. 125 * 126 * \a zip is the pointer to the existing QuaZip object. This 127 * QuaZipFile object then can be used to read current file in the 128 * \a zip or to write to the file inside it. 129 * 130 * \warning Using this constructor for reading current file can be 131 * tricky. Let's take the following example: 132 * \code 133 * QuaZip zip("archive.zip"); 134 * zip.open(QuaZip::mdUnzip); 135 * zip.setCurrentFile("file-in-archive"); 136 * QuaZipFile file(&zip); 137 * file.open(QIODevice::ReadOnly); 138 * // ok, now we can read from the file 139 * file.read(somewhere, some); 140 * zip.setCurrentFile("another-file-in-archive"); // oops... 141 * QuaZipFile anotherFile(&zip); 142 * anotherFile.open(QIODevice::ReadOnly); 143 * anotherFile.read(somewhere, some); // this is still ok... 144 * file.read(somewhere, some); // and this is NOT 145 * \endcode 146 * So, what exactly happens here? When we change current file in the 147 * \c zip archive, \c file that references it becomes invalid 148 * (actually, as far as I understand ZIP/UNZIP sources, it becomes 149 * closed, but QuaZipFile has no means to detect it). 150 * 151 * Summary: do not close \c zip object or change its current file as 152 * long as QuaZipFile is open. Even better - use another constructors 153 * which create internal QuaZip instances, one per object, and 154 * therefore do not cause unnecessary trouble. This constructor may 155 * be useful, though, if you already have a QuaZip instance and do 156 * not want to access several files at once. Good example: 157 * \code 158 * QuaZip zip("archive.zip"); 159 * zip.open(QuaZip::mdUnzip); 160 * // first, we need some information about archive itself 161 * QByteArray comment=zip.getComment(); 162 * // and now we are going to access files inside it 163 * QuaZipFile file(&zip); 164 * for(bool more=zip.goToFirstFile(); more; more=zip.goToNextFile()) { 165 * file.open(QIODevice::ReadOnly); 166 * // do something cool with file here 167 * file.close(); // do not forget to close! 168 * } 169 * zip.close(); 170 * \endcode 171 **/ 172 QuaZipFile(QuaZip *zip, QObject *parent =NULL); 173 /// Destroys a QuaZipFile instance. 174 /** Closes file if open, destructs internal QuaZip object (if it 175 * exists and \em is internal, of course). 176 **/ 177 virtual ~QuaZipFile(); 178 /// Returns the ZIP archive file name. 179 /** If this object was created by passing QuaZip pointer to the 180 * constructor, this function will return that QuaZip's file name 181 * (or null string if that object does not have file name yet). 182 * 183 * Otherwise, returns associated ZIP archive file name or null 184 * string if there are no name set yet. 185 * 186 * \sa setZipName() getFileName() 187 **/ 188 QString getZipName()const; 189 /// Returns a pointer to the associated QuaZip object. 190 /** Returns \c NULL if there is no associated QuaZip or it is 191 * internal (so you will not mess with it). 192 **/ 193 QuaZip* getZip()const; 194 /// Returns file name. 195 /** This function returns file name you passed to this object either 196 * by using 197 * QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*) 198 * or by calling setFileName(). Real name of the file may differ in 199 * case if you used case-insensitivity. 200 * 201 * Returns null string if there is no file name set yet. This is the 202 * case when this QuaZipFile operates on the existing QuaZip object 203 * (constructor QuaZipFile(QuaZip*,QObject*) or setZip() was used). 204 * 205 * \sa getActualFileName 206 **/ 207 QString getFileName() const; 208 /// Returns case sensitivity of the file name. 209 /** This function returns case sensitivity argument you passed to 210 * this object either by using 211 * QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*) 212 * or by calling setFileName(). 213 * 214 * Returns unpredictable value if getFileName() returns null string 215 * (this is the case when you did not used setFileName() or 216 * constructor above). 217 * 218 * \sa getFileName 219 **/ 220 QuaZip::CaseSensitivity getCaseSensitivity() const; 221 /// Returns the actual file name in the archive. 222 /** This is \em not a ZIP archive file name, but a name of file inside 223 * archive. It is not necessary the same name that you have passed 224 * to the 225 * QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*), 226 * setFileName() or QuaZip::setCurrentFile() - this is the real file 227 * name inside archive, so it may differ in case if the file name 228 * search was case-insensitive. 229 * 230 * Equivalent to calling getCurrentFileName() on the associated 231 * QuaZip object. Returns null string if there is no associated 232 * QuaZip object or if it does not have a current file yet. And this 233 * is the case if you called setFileName() but did not open the 234 * file yet. So this is perfectly fine: 235 * \code 236 * QuaZipFile file("somezip.zip"); 237 * file.setFileName("somefile"); 238 * QString name=file.getName(); // name=="somefile" 239 * QString actual=file.getActualFileName(); // actual is null string 240 * file.open(QIODevice::ReadOnly); 241 * QString actual=file.getActualFileName(); // actual can be "SoMeFiLe" on Windows 242 * \endcode 243 * 244 * \sa getZipName(), getFileName(), QuaZip::CaseSensitivity 245 **/ 246 QString getActualFileName()const; 247 /// Sets the ZIP archive file name. 248 /** Automatically creates internal QuaZip object and destroys 249 * previously created internal QuaZip object, if any. 250 * 251 * Will do nothing if this file is already open. You must close() it 252 * first. 253 **/ 254 void setZipName(const QString& zipName); 255 /// Returns \c true if the file was opened in raw mode. 256 /** If the file is not open, the returned value is undefined. 257 * 258 * \sa open(OpenMode,int*,int*,bool,const char*) 259 **/ 260 bool isRaw() const; 261 /// Binds to the existing QuaZip instance. 262 /** This function destroys internal QuaZip object, if any, and makes 263 * this QuaZipFile to use current file in the \a zip object for any 264 * further operations. See QuaZipFile(QuaZip*,QObject*) for the 265 * possible pitfalls. 266 * 267 * Will do nothing if the file is currently open. You must close() 268 * it first. 269 **/ 270 void setZip(QuaZip *zip); 271 /// Sets the file name. 272 /** Will do nothing if at least one of the following conditions is 273 * met: 274 * - ZIP name has not been set yet (getZipName() returns null 275 * string). 276 * - This QuaZipFile is associated with external QuaZip. In this 277 * case you should call that QuaZip's setCurrentFile() function 278 * instead! 279 * - File is already open so setting the name is meaningless. 280 * 281 * \sa QuaZip::setCurrentFile 282 **/ 283 void setFileName(const QString& fileName, QuaZip::CaseSensitivity cs =QuaZip::csDefault); 284 /// Opens a file for reading. 285 /** Returns \c true on success, \c false otherwise. 286 * Call getZipError() to get error code. 287 * 288 * \note Since ZIP/UNZIP API provides buffered reading only, 289 * QuaZipFile does not support unbuffered reading. So do not pass 290 * QIODevice::Unbuffered flag in \a mode, or open will fail. 291 **/ 292 virtual bool open(OpenMode mode); 293 /// Opens a file for reading. 294 /** \overload 295 * Argument \a password specifies a password to decrypt the file. If 296 * it is NULL then this function behaves just like open(OpenMode). 297 **/ open(OpenMode mode,const char * password)298 inline bool open(OpenMode mode, const char *password) 299 {return open(mode, NULL, NULL, false, password);} 300 /// Opens a file for reading. 301 /** \overload 302 * Argument \a password specifies a password to decrypt the file. 303 * 304 * An integers pointed by \a method and \a level will receive codes 305 * of the compression method and level used. See unzip.h. 306 * 307 * If raw is \c true then no decompression is performed. 308 * 309 * \a method should not be \c NULL. \a level can be \c NULL if you 310 * don't want to know the compression level. 311 **/ 312 bool open(OpenMode mode, int *method, int *level, bool raw, const char *password =NULL); 313 /// Opens a file for writing. 314 /** \a info argument specifies information about file. It should at 315 * least specify a correct file name. Also, it is a good idea to 316 * specify correct timestamp (by default, current time will be 317 * used). See QuaZipNewInfo. 318 * 319 * The \a password argument specifies the password for crypting. Pass NULL 320 * if you don't need any crypting. The \a crc argument was supposed 321 * to be used for crypting too, but then it turned out that it's 322 * false information, so you need to set it to 0 unless you want to 323 * use the raw mode (see below). 324 * 325 * Arguments \a method and \a level specify compression method and 326 * level. The only method supported is Z_DEFLATED, but you may also 327 * specify 0 for no compression. If all of the files in the archive 328 * use both method 0 and either level 0 is explicitly specified or 329 * data descriptor writing is disabled with 330 * QuaZip::setDataDescriptorWritingEnabled(), then the 331 * resulting archive is supposed to be compatible with the 1.0 ZIP 332 * format version, should you need that. Except for this, \a level 333 * has no other effects with method 0. 334 * 335 * If \a raw is \c true, no compression is performed. In this case, 336 * \a crc and uncompressedSize field of the \a info are required. 337 * 338 * Arguments \a windowBits, \a memLevel, \a strategy provide zlib 339 * algorithms tuning. See deflateInit2() in zlib. 340 **/ 341 bool open(OpenMode mode, const QuaZipNewInfo& info, 342 const char *password =NULL, quint32 crc =0, 343 int method =Z_DEFLATED, int level =Z_DEFAULT_COMPRESSION, bool raw =false, 344 int windowBits =-MAX_WBITS, int memLevel =DEF_MEM_LEVEL, int strategy =Z_DEFAULT_STRATEGY); 345 /// Returns \c true, but \ref quazipfile-sequential "beware"! 346 virtual bool isSequential()const; 347 /// Returns current position in the file. 348 /** Implementation of the QIODevice::pos(). When reading, this 349 * function is a wrapper to the ZIP/UNZIP unztell(), therefore it is 350 * unable to keep track of the ungetChar() calls (which is 351 * non-virtual and therefore is dangerous to reimplement). So if you 352 * are using ungetChar() feature of the QIODevice, this function 353 * reports incorrect value until you get back characters which you 354 * ungot. 355 * 356 * When writing, pos() returns number of bytes already written 357 * (uncompressed unless you use raw mode). 358 * 359 * \note Although 360 * \ref quazipfile-sequential "QuaZipFile is a sequential device" 361 * and therefore pos() should always return zero, it does not, 362 * because it would be misguiding. Keep this in mind. 363 * 364 * This function returns -1 if the file or archive is not open. 365 * 366 * Error code returned by getZipError() is not affected by this 367 * function call. 368 **/ 369 virtual qint64 pos()const; 370 /// Returns \c true if the end of file was reached. 371 /** This function returns \c false in the case of error. This means 372 * that you called this function on either not open file, or a file 373 * in the not open archive or even on a QuaZipFile instance that 374 * does not even have QuaZip instance associated. Do not do that 375 * because there is no means to determine whether \c false is 376 * returned because of error or because end of file was reached. 377 * Well, on the other side you may interpret \c false return value 378 * as "there is no file open to check for end of file and there is 379 * no end of file therefore". 380 * 381 * When writing, this function always returns \c true (because you 382 * are always writing to the end of file). 383 * 384 * Error code returned by getZipError() is not affected by this 385 * function call. 386 **/ 387 virtual bool atEnd()const; 388 /// Returns file size. 389 /** This function returns csize() if the file is open for reading in 390 * raw mode, usize() if it is open for reading in normal mode and 391 * pos() if it is open for writing. 392 * 393 * Returns -1 on error, call getZipError() to get error code. 394 * 395 * \note This function returns file size despite that 396 * \ref quazipfile-sequential "QuaZipFile is considered to be sequential device", 397 * for which size() should return bytesAvailable() instead. But its 398 * name would be very misguiding otherwise, so just keep in mind 399 * this inconsistence. 400 **/ 401 virtual qint64 size()const; 402 /// Returns compressed file size. 403 /** Equivalent to calling getFileInfo() and then getting 404 * compressedSize field, but more convenient and faster. 405 * 406 * File must be open for reading before calling this function. 407 * 408 * Returns -1 on error, call getZipError() to get error code. 409 **/ 410 qint64 csize()const; 411 /// Returns uncompressed file size. 412 /** Equivalent to calling getFileInfo() and then getting 413 * uncompressedSize field, but more convenient and faster. See 414 * getFileInfo() for a warning. 415 * 416 * File must be open for reading before calling this function. 417 * 418 * Returns -1 on error, call getZipError() to get error code. 419 **/ 420 qint64 usize()const; 421 /// Gets information about current file. 422 /** This function does the same thing as calling 423 * QuaZip::getCurrentFileInfo() on the associated QuaZip object, 424 * but you can not call getCurrentFileInfo() if the associated 425 * QuaZip is internal (because you do not have access to it), while 426 * you still can call this function in that case. 427 * 428 * File must be open for reading before calling this function. 429 * 430 * \return \c false in the case of an error. 431 * 432 * This function doesn't support zip64, but will still work fine on zip64 433 * archives if file sizes are below 4 GB, otherwise the values will be set 434 * as if converted using QuaZipFileInfo64::toQuaZipFileInfo(). 435 * 436 * \sa getFileInfo(QuaZipFileInfo64*) 437 **/ 438 bool getFileInfo(QuaZipFileInfo *info); 439 /// Gets information about current file with zip64 support. 440 /** 441 * @overload 442 * 443 * \sa getFileInfo(QuaZipFileInfo*) 444 */ 445 bool getFileInfo(QuaZipFileInfo64 *info); 446 /// Closes the file. 447 /** Call getZipError() to determine if the close was successful. 448 **/ 449 virtual void close(); 450 /// Returns the error code returned by the last ZIP/UNZIP API call. 451 int getZipError() const; 452 /// Returns the number of bytes available for reading. 453 virtual qint64 bytesAvailable() const; 454 }; 455 456 #endif 457