1 #ifndef QUA_ZIPFILE_H

     2 #define QUA_ZIPFILE_H

     3 

     4 /*

     5 Copyright (C) 2005-2011 Sergey A. Tachenov

     6 

     7 This program is free software; you can redistribute it and/or modify it

     8 under the terms of the GNU Lesser General Public License as published by

     9 the Free Software Foundation; either version 2 of the License, or (at

    10 your option) any later version.

    11 

    12 This program is distributed in the hope that it will be useful, but

    13 WITHOUT ANY WARRANTY; without even the implied warranty of

    14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser

    15 General Public License for more details.

    16 

    17 You should have received a copy of the GNU Lesser General Public License

    18 along with this program; if not, write to the Free Software Foundation,

    19 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

    20 

    21 See COPYING file for the full LGPL text.

    22 

    23 Original ZIP package is copyrighted by Gilles Vollant, see

    24 quazip/(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 

    33 class 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  **/

    73 class 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