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