1 #ifndef QUA_ZIP_H

     2 #define QUA_ZIP_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 <QString>

    28 #include <QTextCodec>

    29 

    30 #include "zip.h"

    31 #include "unzip.h"

    32 

    33 #include "quazip_global.h"

    34 #include "quazipfileinfo.h"

    35 

    36 // just in case it will be defined in the later versions of the ZIP/UNZIP

    37 #ifndef UNZ_OPENERROR

    38 // define additional error code

    39 #define UNZ_OPENERROR -1000

    40 #endif

    41 

    42 class QuaZipPrivate;

    43 

    44 /// ZIP archive.

    45 /** \class QuaZip quazip.h <quazip/quazip.h>

    46  * This class implements basic interface to the ZIP archive. It can be

    47  * used to read table contents of the ZIP archive and retreiving

    48  * information about the files inside it.

    49  *

    50  * You can also use this class to open files inside archive by passing

    51  * pointer to the instance of this class to the constructor of the

    52  * QuaZipFile class. But see QuaZipFile::QuaZipFile(QuaZip*, QObject*)

    53  * for the possible pitfalls.

    54  *

    55  * This class is indended to provide interface to the ZIP subpackage of

    56  * the ZIP/UNZIP package as well as to the UNZIP subpackage. But

    57  * currently it supports only UNZIP.

    58  *

    59  * The use of this class is simple - just create instance using

    60  * constructor, then set ZIP archive file name using setFile() function

    61  * (if you did not passed the name to the constructor), then open() and

    62  * then use different functions to work with it! Well, if you are

    63  * paranoid, you may also wish to call close before destructing the

    64  * instance, to check for errors on close.

    65  *

    66  * You may also use getUnzFile() and getZipFile() functions to get the

    67  * ZIP archive handle and use it with ZIP/UNZIP package API directly.

    68  *

    69  * This class supports localized file names inside ZIP archive, but you

    70  * have to set up proper codec with setCodec() function. By default,

    71  * locale codec will be used, which is probably ok for UNIX systems, but

    72  * will almost certainly fail with ZIP archives created in Windows. This

    73  * is because Windows ZIP programs have strange habit of using DOS

    74  * encoding for file names in ZIP archives. For example, ZIP archive

    75  * with cyrillic names created in Windows will have file names in \c

    76  * IBM866 encoding instead of \c WINDOWS-1251. I think that calling one

    77  * function is not much trouble, but for true platform independency it

    78  * would be nice to have some mechanism for file name encoding auto

    79  * detection using locale information. Does anyone know a good way to do

    80  * it?

    81  **/

    82 class QUAZIP_EXPORT QuaZip {

    83   friend class QuaZipPrivate;

    84   public:

    85     /// Useful constants.

    86     enum Constants {

    87       MAX_FILE_NAME_LENGTH=256 /**< Maximum file name length. Taken from

    88                                  \c UNZ_MAXFILENAMEINZIP constant in

    89                                  unzip.c. */

    90     };

    91     /// Open mode of the ZIP file.

    92     enum Mode {

    93       mdNotOpen, ///< ZIP file is not open. This is the initial mode.

    94       mdUnzip, ///< ZIP file is open for reading files inside it.

    95       mdCreate, ///< ZIP file was created with open() call.

    96       mdAppend, /**< ZIP file was opened in append mode. This refers to

    97                   * \c APPEND_STATUS_CREATEAFTER mode in ZIP/UNZIP package

    98                   * and means that zip is appended to some existing file

    99                   * what is useful when that file contains

   100                   * self-extractor code. This is obviously \em not what

   101                   * you whant to use to add files to the existing ZIP

   102                   * archive.

   103                   **/

   104       mdAdd ///< ZIP file was opened for adding files in the archive.

   105     };

   106     /// Case sensitivity for the file names.

   107     /** This is what you specify when accessing files in the archive.

   108      * Works perfectly fine with any characters thanks to Qt's great

   109      * unicode support. This is different from ZIP/UNZIP API, where

   110      * only US-ASCII characters was supported.

   111      **/

   112     enum CaseSensitivity {

   113       csDefault=0, ///< Default for platform. Case sensitive for UNIX, not for Windows.

   114       csSensitive=1, ///< Case sensitive.

   115       csInsensitive=2 ///< Case insensitive.

   116     };

   117   private:

   118     QuaZipPrivate *p;

   119     // not (and will not be) implemented

   120     QuaZip(const QuaZip& that);

   121     // not (and will not be) implemented

   122     QuaZip& operator=(const QuaZip& that);

   123   public:

   124     /// Constructs QuaZip object.

   125     /** Call setName() before opening constructed object. */

   126     QuaZip();

   127     /// Constructs QuaZip object associated with ZIP file \a zipName.

   128     QuaZip(const QString& zipName);

   129     /// Constructs QuaZip object associated with ZIP file represented by \a ioDevice.

   130     /** The IO device must be seekable, otherwise an error will occur when opening. */

   131     QuaZip(QIODevice *ioDevice);

   132     /// Destroys QuaZip object.

   133     /** Calls close() if necessary. */

   134     ~QuaZip();

   135     /// Opens ZIP file.

   136     /**

   137      * Argument \a mode specifies open mode of the ZIP archive. See Mode

   138      * for details. Note that there is zipOpen2() function in the

   139      * ZIP/UNZIP API which accepts \a globalcomment argument, but it

   140      * does not use it anywhere, so this open() function does not have this

   141      * argument. See setComment() if you need to set global comment.

   142      *

   143      * If the ZIP file is accessed via explicitly set QIODevice, then

   144      * this device is opened in the necessary mode. If the device was

   145      * already opened by some other means, then the behaviour is defined by

   146      * the device implementation, but generally it is not a very good

   147      * idea. For example, QFile will at least issue a warning.

   148      *

   149      * \return \c true if successful, \c false otherwise.

   150      *

   151      * \note ZIP/UNZIP API open calls do not return error code - they

   152      * just return \c NULL indicating an error. But to make things

   153      * easier, quazip.h header defines additional error code \c

   154      * UNZ_ERROROPEN and getZipError() will return it if the open call

   155      * of the ZIP/UNZIP API returns \c NULL.

   156      *

   157      * Argument \a ioApi specifies IO function set for ZIP/UNZIP

   158      * package to use. See unzip.h, zip.h and ioapi.h for details. Note

   159      * that IO API for QuaZip is different from the original package.

   160      * The file path argument was changed to be of type \c voidpf, and

   161      * QuaZip passes a QIODevice pointer there. This QIODevice is either

   162      * set explicitly via setIoDevice() or the QuaZip(QIODevice*)

   163      * constructor, or it is created internally when opening the archive

   164      * by its file name. The default API (qioapi.cpp) just delegates

   165      * everything to the QIODevice API. Not only this allows to use a

   166      * QIODevice instead of file name, but also has a nice side effect

   167      * of raising the file size limit from 2G to 4G.

   168      *

   169      * In short: just forget about the \a ioApi argument and you'll be

   170      * fine.

   171      **/

   172     bool open(Mode mode, zlib_filefunc_def *ioApi =NULL);

   173     /// Closes ZIP file.

   174     /** Call getZipError() to determine if the close was successful. The

   175      * underlying QIODevice is also closed, regardless of whether it was

   176      * set explicitly or not. */

   177     void close();

   178     /// Sets the codec used to encode/decode file names inside archive.

   179     /** This is necessary to access files in the ZIP archive created

   180      * under Windows with non-latin characters in file names. For

   181      * example, file names with cyrillic letters will be in \c IBM866

   182      * encoding.

   183      **/

   184     void setFileNameCodec(QTextCodec *fileNameCodec);

   185     /// Sets the codec used to encode/decode file names inside archive.

   186     /** \overload

   187      * Equivalent to calling setFileNameCodec(QTextCodec::codecForName(codecName));

   188      **/

   189     void setFileNameCodec(const char *fileNameCodecName);

   190     /// Returns the codec used to encode/decode comments inside archive.

   191     QTextCodec* getFileNameCodec() const;

   192     /// Sets the codec used to encode/decode comments inside archive.

   193     /** This codec defaults to locale codec, which is probably ok.

   194      **/

   195     void setCommentCodec(QTextCodec *commentCodec);

   196     /// Sets the codec used to encode/decode comments inside archive.

   197     /** \overload

   198      * Equivalent to calling setCommentCodec(QTextCodec::codecForName(codecName));

   199      **/

   200     void setCommentCodec(const char *commentCodecName);

   201     /// Returns the codec used to encode/decode comments inside archive.

   202     QTextCodec* getCommentCodec() const;

   203     /// Returns the name of the ZIP file.

   204     /** Returns null string if no ZIP file name has been set, for

   205      * example when the QuaZip instance is set up to use a QIODevice

   206      * instead.

   207      * \sa setZipName(), setIoDevice(), getIoDevice()

   208      **/

   209     QString getZipName() const;

   210     /// Sets the name of the ZIP file.

   211     /** Does nothing if the ZIP file is open.

   212      *

   213      * Does not reset error code returned by getZipError().

   214      * \sa setIoDevice(), getIoDevice(), getZipName()

   215      **/

   216     void setZipName(const QString& zipName);

   217     /// Returns the device representing this ZIP file.

   218     /** Returns null string if no device has been set explicitly, for

   219      * example when opening a ZIP file by name.

   220      * \sa setIoDevice(), getZipName(), setZipName()

   221      **/

   222     QIODevice *getIoDevice() const;

   223     /// Sets the device representing the ZIP file.

   224     /** Does nothing if the ZIP file is open.

   225      *

   226      * Does not reset error code returned by getZipError().

   227      * \sa getIoDevice(), getZipName(), setZipName()

   228      **/

   229     void setIoDevice(QIODevice *ioDevice);

   230     /// Returns the mode in which ZIP file was opened.

   231     Mode getMode() const;

   232     /// Returns \c true if ZIP file is open, \c false otherwise.

   233     bool isOpen() const;

   234     /// Returns the error code of the last operation.

   235     /** Returns \c UNZ_OK if the last operation was successful.

   236      *

   237      * Error code resets to \c UNZ_OK every time you call any function

   238      * that accesses something inside ZIP archive, even if it is \c

   239      * const (like getEntriesCount()). open() and close() calls reset

   240      * error code too. See documentation for the specific functions for

   241      * details on error detection.

   242      **/

   243     int getZipError() const;

   244     /// Returns number of the entries in the ZIP central directory.

   245     /** Returns negative error code in the case of error. The same error

   246      * code will be returned by subsequent getZipError() call.

   247      **/

   248     int getEntriesCount() const;

   249     /// Returns global comment in the ZIP file.

   250     QString getComment() const;

   251     /// Sets global comment in the ZIP file.

   252     /** Comment will be written to the archive on close operation.

   253      *

   254      * \sa open()

   255      **/

   256     void setComment(const QString& comment);

   257     /// Sets the current file to the first file in the archive.

   258     /** Returns \c true on success, \c false otherwise. Call

   259      * getZipError() to get the error code.

   260      **/

   261     bool goToFirstFile();

   262     /// Sets the current file to the next file in the archive.

   263     /** Returns \c true on success, \c false otherwise. Call

   264      * getZipError() to determine if there was an error.

   265      *

   266      * Should be used only in QuaZip::mdUnzip mode.

   267      *

   268      * \note If the end of file was reached, getZipError() will return

   269      * \c UNZ_OK instead of \c UNZ_END_OF_LIST_OF_FILE. This is to make

   270      * things like this easier:

   271      * \code

   272      * for(bool more=zip.goToFirstFile(); more; more=zip.goToNextFile()) {

   273      *   // do something

   274      * }

   275      * if(zip.getZipError()==UNZ_OK) {

   276      *   // ok, there was no error

   277      * }

   278      * \endcode

   279      **/

   280     bool goToNextFile();

   281     /// Sets current file by its name.

   282     /** Returns \c true if successful, \c false otherwise. Argument \a

   283      * cs specifies case sensitivity of the file name. Call

   284      * getZipError() in the case of a failure to get error code.

   285      *

   286      * This is not a wrapper to unzLocateFile() function. That is

   287      * because I had to implement locale-specific case-insensitive

   288      * comparison.

   289      *

   290      * Here are the differences from the original implementation:

   291      *

   292      * - If the file was not found, error code is \c UNZ_OK, not \c

   293      *   UNZ_END_OF_LIST_OF_FILE (see also goToNextFile()).

   294      * - If this function fails, it unsets the current file rather than

   295      *   resetting it back to what it was before the call.

   296      *

   297      * If \a fileName is null string then this function unsets the

   298      * current file and return \c true. Note that you should close the

   299      * file first if it is open! See

   300      * QuaZipFile::QuaZipFile(QuaZip*,QObject*) for the details.

   301      *

   302      * Should be used only in QuaZip::mdUnzip mode.

   303      *

   304      * \sa setFileNameCodec(), CaseSensitivity

   305      **/

   306     bool setCurrentFile(const QString& fileName, CaseSensitivity cs =csDefault);

   307     /// Returns \c true if the current file has been set.

   308     bool hasCurrentFile() const;

   309     /// Retrieves information about the current file.

   310     /** Fills the structure pointed by \a info. Returns \c true on

   311      * success, \c false otherwise. In the latter case structure pointed

   312      * by \a info remains untouched. If there was an error,

   313      * getZipError() returns error code.

   314      *

   315      * Should be used only in QuaZip::mdUnzip mode.

   316      *

   317      * Does nothing and returns \c false in any of the following cases.

   318      * - ZIP is not open;

   319      * - ZIP does not have current file;

   320      * - \a info is \c NULL;

   321      *

   322      * In all these cases getZipError() returns \c UNZ_OK since there

   323      * is no ZIP/UNZIP API call.

   324      **/

   325     bool getCurrentFileInfo(QuaZipFileInfo* info)const;

   326     /// Returns the current file name.

   327     /** Equivalent to calling getCurrentFileInfo() and then getting \c

   328      * name field of the QuaZipFileInfo structure, but faster and more

   329      * convenient.

   330      *

   331      * Should be used only in QuaZip::mdUnzip mode.

   332      **/

   333     QString getCurrentFileName()const;

   334     /// Returns \c unzFile handle.

   335     /** You can use this handle to directly call UNZIP part of the

   336      * ZIP/UNZIP package functions (see unzip.h).

   337      *

   338      * \warning When using the handle returned by this function, please

   339      * keep in mind that QuaZip class is unable to detect any changes

   340      * you make in the ZIP file state (e. g. changing current file, or

   341      * closing the handle). So please do not do anything with this

   342      * handle that is possible to do with the functions of this class.

   343      * Or at least return the handle in the original state before

   344      * calling some another function of this class (including implicit

   345      * destructor calls and calls from the QuaZipFile objects that refer

   346      * to this QuaZip instance!). So if you have changed the current

   347      * file in the ZIP archive - then change it back or you may

   348      * experience some strange behavior or even crashes.

   349      **/

   350     unzFile getUnzFile();

   351     /// Returns \c zipFile handle.

   352     /** You can use this handle to directly call ZIP part of the

   353      * ZIP/UNZIP package functions (see zip.h). Warnings about the

   354      * getUnzFile() function also apply to this function.

   355      **/

   356     zipFile getZipFile();

   357 };

   358 

   359 #endif