misc/quazip/quazip.h
changeset 5752 ea95ee97c805
child 7889 57b117d441b9
equal deleted inserted replaced
5750:6bbf7aee2cdf 5752:ea95ee97c805
       
     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