source: s10k/CommonLibs/quazip-0.7.2/quazip/quazip.h @ 1096

Last change on this file since 1096 was 1096, checked in by s10k, 22 months ago

Added zlib, quazip, basicxmlsyntaxhighlighter, conditionalsemaphore and linenumberdisplay libraries. zlib and quazip are pre-compiled, but you can compile them yourself, just delete the dll files (or equivalent binary files to your OS)

File size: 25.3 KB
Line 
1#ifndef QUA_ZIP_H
2#define QUA_ZIP_H
3
4/*
5Copyright (C) 2005-2014 Sergey A. Tachenov
6
7This file is part of QuaZIP.
8
9QuaZIP is free software: you can redistribute it and/or modify
10it under the terms of the GNU Lesser General Public License as published by
11the Free Software Foundation, either version 2.1 of the License, or
12(at your option) any later version.
13
14QuaZIP is distributed in the hope that it will be useful,
15but WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License
20along with QuaZIP.  If not, see <http://www.gnu.org/licenses/>.
21
22See COPYING file for the full LGPL text.
23
24Original ZIP package is copyrighted by Gilles Vollant, see
25quazip/(un)zip.h files for details, basically it's zlib license.
26 **/
27
28#include <QString>
29#include <QStringList>
30#include <QTextCodec>
31
32#include "zip.h"
33#include "unzip.h"
34
35#include "quazip_global.h"
36#include "quazipfileinfo.h"
37
38// just in case it will be defined in the later versions of the ZIP/UNZIP
39#ifndef UNZ_OPENERROR
40// define additional error code
41#define UNZ_OPENERROR -1000
42#endif
43
44class QuaZipPrivate;
45
46/// ZIP archive.
47/** \class QuaZip quazip.h <quazip/quazip.h>
48 * This class implements basic interface to the ZIP archive. It can be
49 * used to read table contents of the ZIP archive and retreiving
50 * information about the files inside it.
51 *
52 * You can also use this class to open files inside archive by passing
53 * pointer to the instance of this class to the constructor of the
54 * QuaZipFile class. But see QuaZipFile::QuaZipFile(QuaZip*, QObject*)
55 * for the possible pitfalls.
56 *
57 * This class is indended to provide interface to the ZIP subpackage of
58 * the ZIP/UNZIP package as well as to the UNZIP subpackage. But
59 * currently it supports only UNZIP.
60 *
61 * The use of this class is simple - just create instance using
62 * constructor, then set ZIP archive file name using setFile() function
63 * (if you did not passed the name to the constructor), then open() and
64 * then use different functions to work with it! Well, if you are
65 * paranoid, you may also wish to call close before destructing the
66 * instance, to check for errors on close.
67 *
68 * You may also use getUnzFile() and getZipFile() functions to get the
69 * ZIP archive handle and use it with ZIP/UNZIP package API directly.
70 *
71 * This class supports localized file names inside ZIP archive, but you
72 * have to set up proper codec with setCodec() function. By default,
73 * locale codec will be used, which is probably ok for UNIX systems, but
74 * will almost certainly fail with ZIP archives created in Windows. This
75 * is because Windows ZIP programs have strange habit of using DOS
76 * encoding for file names in ZIP archives. For example, ZIP archive
77 * with cyrillic names created in Windows will have file names in \c
78 * IBM866 encoding instead of \c WINDOWS-1251. I think that calling one
79 * function is not much trouble, but for true platform independency it
80 * would be nice to have some mechanism for file name encoding auto
81 * detection using locale information. Does anyone know a good way to do
82 * it?
83 **/
84class QUAZIP_EXPORT QuaZip {
85  friend class QuaZipPrivate;
86  public:
87    /// Useful constants.
88    enum Constants {
89      MAX_FILE_NAME_LENGTH=256 /**< Maximum file name length. Taken from
90                                 \c UNZ_MAXFILENAMEINZIP constant in
91                                 unzip.c. */
92    };
93    /// Open mode of the ZIP file.
94    enum Mode {
95      mdNotOpen, ///< ZIP file is not open. This is the initial mode.
96      mdUnzip, ///< ZIP file is open for reading files inside it.
97      mdCreate, ///< ZIP file was created with open() call.
98      mdAppend, /**< ZIP file was opened in append mode. This refers to
99                  * \c APPEND_STATUS_CREATEAFTER mode in ZIP/UNZIP package
100                  * and means that zip is appended to some existing file
101                  * what is useful when that file contains
102                  * self-extractor code. This is obviously \em not what
103                  * you whant to use to add files to the existing ZIP
104                  * archive.
105                  **/
106      mdAdd ///< ZIP file was opened for adding files in the archive.
107    };
108    /// Case sensitivity for the file names.
109    /** This is what you specify when accessing files in the archive.
110     * Works perfectly fine with any characters thanks to Qt's great
111     * unicode support. This is different from ZIP/UNZIP API, where
112     * only US-ASCII characters was supported.
113     **/
114    enum CaseSensitivity {
115      csDefault=0, ///< Default for platform. Case sensitive for UNIX, not for Windows.
116      csSensitive=1, ///< Case sensitive.
117      csInsensitive=2 ///< Case insensitive.
118    };
119    /// Returns the actual case sensitivity for the specified QuaZIP one.
120    /**
121      \param cs The value to convert.
122      \returns If CaseSensitivity::csDefault, then returns the default
123      file name case sensitivity for the platform. Otherwise, just
124      returns the appropriate value from the Qt::CaseSensitivity enum.
125      */
126    static Qt::CaseSensitivity convertCaseSensitivity(
127            CaseSensitivity cs);
128  private:
129    QuaZipPrivate *p;
130    // not (and will not be) implemented
131    QuaZip(const QuaZip& that);
132    // not (and will not be) implemented
133    QuaZip& operator=(const QuaZip& that);
134  public:
135    /// Constructs QuaZip object.
136    /** Call setName() before opening constructed object. */
137    QuaZip();
138    /// Constructs QuaZip object associated with ZIP file \a zipName.
139    QuaZip(const QString& zipName);
140    /// Constructs QuaZip object associated with ZIP file represented by \a ioDevice.
141    /** The IO device must be seekable, otherwise an error will occur when opening. */
142    QuaZip(QIODevice *ioDevice);
143    /// Destroys QuaZip object.
144    /** Calls close() if necessary. */
145    ~QuaZip();
146    /// Opens ZIP file.
147    /**
148     * Argument \a mode specifies open mode of the ZIP archive. See Mode
149     * for details. Note that there is zipOpen2() function in the
150     * ZIP/UNZIP API which accepts \a globalcomment argument, but it
151     * does not use it anywhere, so this open() function does not have this
152     * argument. See setComment() if you need to set global comment.
153     *
154     * If the ZIP file is accessed via explicitly set QIODevice, then
155     * this device is opened in the necessary mode. If the device was
156     * already opened by some other means, then QuaZIP checks if the
157     * open mode is compatible to the mode needed for the requested operation.
158     * If necessary, seeking is performed to position the device properly.
159     *
160     * \return \c true if successful, \c false otherwise.
161     *
162     * \note ZIP/UNZIP API open calls do not return error code - they
163     * just return \c NULL indicating an error. But to make things
164     * easier, quazip.h header defines additional error code \c
165     * UNZ_ERROROPEN and getZipError() will return it if the open call
166     * of the ZIP/UNZIP API returns \c NULL.
167     *
168     * Argument \a ioApi specifies IO function set for ZIP/UNZIP
169     * package to use. See unzip.h, zip.h and ioapi.h for details. Note
170     * that IO API for QuaZip is different from the original package.
171     * The file path argument was changed to be of type \c voidpf, and
172     * QuaZip passes a QIODevice pointer there. This QIODevice is either
173     * set explicitly via setIoDevice() or the QuaZip(QIODevice*)
174     * constructor, or it is created internally when opening the archive
175     * by its file name. The default API (qioapi.cpp) just delegates
176     * everything to the QIODevice API. Not only this allows to use a
177     * QIODevice instead of file name, but also has a nice side effect
178     * of raising the file size limit from 2G to 4G (in non-zip64 archives).
179     *
180     * \note If the zip64 support is needed, the ioApi argument \em must be NULL
181     * because due to the backwards compatibility issues it can be used to
182     * provide a 32-bit API only.
183     *
184     * \note If the \ref QuaZip::setAutoClose() "no-auto-close" feature is used,
185     * then the \a ioApi argument \em should be NULL because the old API
186     * doesn't support the 'fake close' operation, causing slight memory leaks
187     * and other possible troubles (like closing the output device in case
188     * when an error occurs during opening).
189     *
190     * In short: just forget about the \a ioApi argument and you'll be
191     * fine.
192     **/
193    bool open(Mode mode, zlib_filefunc_def *ioApi =NULL);
194    /// Closes ZIP file.
195    /** Call getZipError() to determine if the close was successful.
196     *
197     * If the file was opened by name, then the underlying QIODevice is closed
198     * and deleted.
199     *
200     * If the underlying QIODevice was set explicitly using setIoDevice() or
201     * the appropriate constructor, then it is closed if the auto-close flag
202     * is set (which it is by default). Call setAutoClose() to clear the
203     * auto-close flag if this behavior is undesirable.
204     *
205     * Since Qt 5.1, the QSaveFile was introduced. It breaks the QIODevice API
206     * by making close() private and crashing the application if it is called
207     * from the base class where it is public. It is an excellent example
208     * of poor design that illustrates why you should never ever break
209     * an is-a relationship between the base class and a subclass. QuaZIP
210     * works around this bug by checking if the QIODevice is an instance
211     * of QSaveFile, using qobject_cast<>, and if it is, calls
212     * QSaveFile::commit() instead of close(). It is a really ugly hack,
213     * but at least it makes your programs work instead of crashing. Note that
214     * if the auto-close flag is cleared, then this is a non-issue, and
215     * commit() isn't called.
216      */
217    void close();
218    /// Sets the codec used to encode/decode file names inside archive.
219    /** This is necessary to access files in the ZIP archive created
220     * under Windows with non-latin characters in file names. For
221     * example, file names with cyrillic letters will be in \c IBM866
222     * encoding.
223     **/
224    void setFileNameCodec(QTextCodec *fileNameCodec);
225    /// Sets the codec used to encode/decode file names inside archive.
226    /** \overload
227     * Equivalent to calling setFileNameCodec(QTextCodec::codecForName(codecName));
228     **/
229    void setFileNameCodec(const char *fileNameCodecName);
230    /// Returns the codec used to encode/decode comments inside archive.
231    QTextCodec* getFileNameCodec() const;
232    /// Sets the codec used to encode/decode comments inside archive.
233    /** This codec defaults to locale codec, which is probably ok.
234     **/
235    void setCommentCodec(QTextCodec *commentCodec);
236    /// Sets the codec used to encode/decode comments inside archive.
237    /** \overload
238     * Equivalent to calling setCommentCodec(QTextCodec::codecForName(codecName));
239     **/
240    void setCommentCodec(const char *commentCodecName);
241    /// Returns the codec used to encode/decode comments inside archive.
242    QTextCodec* getCommentCodec() const;
243    /// Returns the name of the ZIP file.
244    /** Returns null string if no ZIP file name has been set, for
245     * example when the QuaZip instance is set up to use a QIODevice
246     * instead.
247     * \sa setZipName(), setIoDevice(), getIoDevice()
248     **/
249    QString getZipName() const;
250    /// Sets the name of the ZIP file.
251    /** Does nothing if the ZIP file is open.
252     *
253     * Does not reset error code returned by getZipError().
254     * \sa setIoDevice(), getIoDevice(), getZipName()
255     **/
256    void setZipName(const QString& zipName);
257    /// Returns the device representing this ZIP file.
258    /** Returns null string if no device has been set explicitly, for
259     * example when opening a ZIP file by name.
260     * \sa setIoDevice(), getZipName(), setZipName()
261     **/
262    QIODevice *getIoDevice() const;
263    /// Sets the device representing the ZIP file.
264    /** Does nothing if the ZIP file is open.
265     *
266     * Does not reset error code returned by getZipError().
267     * \sa getIoDevice(), getZipName(), setZipName()
268     **/
269    void setIoDevice(QIODevice *ioDevice);
270    /// Returns the mode in which ZIP file was opened.
271    Mode getMode() const;
272    /// Returns \c true if ZIP file is open, \c false otherwise.
273    bool isOpen() const;
274    /// Returns the error code of the last operation.
275    /** Returns \c UNZ_OK if the last operation was successful.
276     *
277     * Error code resets to \c UNZ_OK every time you call any function
278     * that accesses something inside ZIP archive, even if it is \c
279     * const (like getEntriesCount()). open() and close() calls reset
280     * error code too. See documentation for the specific functions for
281     * details on error detection.
282     **/
283    int getZipError() const;
284    /// Returns number of the entries in the ZIP central directory.
285    /** Returns negative error code in the case of error. The same error
286     * code will be returned by subsequent getZipError() call.
287     **/
288    int getEntriesCount() const;
289    /// Returns global comment in the ZIP file.
290    QString getComment() const;
291    /// Sets the global comment in the ZIP file.
292    /** The comment will be written to the archive on close operation.
293     * QuaZip makes a distinction between a null QByteArray() comment
294     * and an empty &quot;&quot; comment in the QuaZip::mdAdd mode.
295     * A null comment is the default and it means &quot;don't change
296     * the comment&quot;. An empty comment removes the original comment.
297     *
298     * \sa open()
299     **/
300    void setComment(const QString& comment);
301    /// Sets the current file to the first file in the archive.
302    /** Returns \c true on success, \c false otherwise. Call
303     * getZipError() to get the error code.
304     **/
305    bool goToFirstFile();
306    /// Sets the current file to the next file in the archive.
307    /** Returns \c true on success, \c false otherwise. Call
308     * getZipError() to determine if there was an error.
309     *
310     * Should be used only in QuaZip::mdUnzip mode.
311     *
312     * \note If the end of file was reached, getZipError() will return
313     * \c UNZ_OK instead of \c UNZ_END_OF_LIST_OF_FILE. This is to make
314     * things like this easier:
315     * \code
316     * for(bool more=zip.goToFirstFile(); more; more=zip.goToNextFile()) {
317     *   // do something
318     * }
319     * if(zip.getZipError()==UNZ_OK) {
320     *   // ok, there was no error
321     * }
322     * \endcode
323     **/
324    bool goToNextFile();
325    /// Sets current file by its name.
326    /** Returns \c true if successful, \c false otherwise. Argument \a
327     * cs specifies case sensitivity of the file name. Call
328     * getZipError() in the case of a failure to get error code.
329     *
330     * This is not a wrapper to unzLocateFile() function. That is
331     * because I had to implement locale-specific case-insensitive
332     * comparison.
333     *
334     * Here are the differences from the original implementation:
335     *
336     * - If the file was not found, error code is \c UNZ_OK, not \c
337     *   UNZ_END_OF_LIST_OF_FILE (see also goToNextFile()).
338     * - If this function fails, it unsets the current file rather than
339     *   resetting it back to what it was before the call.
340     *
341     * If \a fileName is null string then this function unsets the
342     * current file and return \c true. Note that you should close the
343     * file first if it is open! See
344     * QuaZipFile::QuaZipFile(QuaZip*,QObject*) for the details.
345     *
346     * Should be used only in QuaZip::mdUnzip mode.
347     *
348     * \sa setFileNameCodec(), CaseSensitivity
349     **/
350    bool setCurrentFile(const QString& fileName, CaseSensitivity cs =csDefault);
351    /// Returns \c true if the current file has been set.
352    bool hasCurrentFile() const;
353    /// Retrieves information about the current file.
354    /** Fills the structure pointed by \a info. Returns \c true on
355     * success, \c false otherwise. In the latter case structure pointed
356     * by \a info remains untouched. If there was an error,
357     * getZipError() returns error code.
358     *
359     * Should be used only in QuaZip::mdUnzip mode.
360     *
361     * Does nothing and returns \c false in any of the following cases.
362     * - ZIP is not open;
363     * - ZIP does not have current file.
364     *
365     * In both cases getZipError() returns \c UNZ_OK since there
366     * is no ZIP/UNZIP API call.
367     *
368     * This overload doesn't support zip64, but will work OK on zip64 archives
369     * except that if one of the sizes (compressed or uncompressed) is greater
370     * than 0xFFFFFFFFu, it will be set to exactly 0xFFFFFFFFu.
371     *
372     * \sa getCurrentFileInfo(QuaZipFileInfo64* info)const
373     * \sa QuaZipFileInfo64::toQuaZipFileInfo(QuaZipFileInfo&)const
374     **/
375    bool getCurrentFileInfo(QuaZipFileInfo* info)const;
376    /// Retrieves information about the current file.
377    /** \overload
378     *
379     * This function supports zip64. If the archive doesn't use zip64, it is
380     * completely equivalent to getCurrentFileInfo(QuaZipFileInfo* info)
381     * except for the argument type.
382     *
383     * \sa
384     **/
385    bool getCurrentFileInfo(QuaZipFileInfo64* info)const;
386    /// Returns the current file name.
387    /** Equivalent to calling getCurrentFileInfo() and then getting \c
388     * name field of the QuaZipFileInfo structure, but faster and more
389     * convenient.
390     *
391     * Should be used only in QuaZip::mdUnzip mode.
392     **/
393    QString getCurrentFileName()const;
394    /// Returns \c unzFile handle.
395    /** You can use this handle to directly call UNZIP part of the
396     * ZIP/UNZIP package functions (see unzip.h).
397     *
398     * \warning When using the handle returned by this function, please
399     * keep in mind that QuaZip class is unable to detect any changes
400     * you make in the ZIP file state (e. g. changing current file, or
401     * closing the handle). So please do not do anything with this
402     * handle that is possible to do with the functions of this class.
403     * Or at least return the handle in the original state before
404     * calling some another function of this class (including implicit
405     * destructor calls and calls from the QuaZipFile objects that refer
406     * to this QuaZip instance!). So if you have changed the current
407     * file in the ZIP archive - then change it back or you may
408     * experience some strange behavior or even crashes.
409     **/
410    unzFile getUnzFile();
411    /// Returns \c zipFile handle.
412    /** You can use this handle to directly call ZIP part of the
413     * ZIP/UNZIP package functions (see zip.h). Warnings about the
414     * getUnzFile() function also apply to this function.
415     **/
416    zipFile getZipFile();
417    /// Changes the data descriptor writing mode.
418    /**
419      According to the ZIP format specification, a file inside archive
420      may have a data descriptor immediately following the file
421      data. This is reflected by a special flag in the local file header
422      and in the central directory. By default, QuaZIP sets this flag
423      and writes the data descriptor unless both method and level were
424      set to 0, in which case it operates in 1.0-compatible mode and
425      never writes data descriptors.
426
427      By setting this flag to false, it is possible to disable data
428      descriptor writing, thus increasing compatibility with archive
429      readers that don't understand this feature of the ZIP file format.
430
431      Setting this flag affects all the QuaZipFile instances that are
432      opened after this flag is set.
433
434      The data descriptor writing mode is enabled by default.
435
436      Note that if the ZIP archive is written into a QIODevice for which
437      QIODevice::isSequential() returns \c true, then the data descriptor
438      is mandatory and will be written even if this flag is set to false.
439
440      \param enabled If \c true, enable local descriptor writing,
441      disable it otherwise.
442
443      \sa QuaZipFile::isDataDescriptorWritingEnabled()
444      */
445    void setDataDescriptorWritingEnabled(bool enabled);
446    /// Returns the data descriptor default writing mode.
447    /**
448      \sa setDataDescriptorWritingEnabled()
449      */
450    bool isDataDescriptorWritingEnabled() const;
451    /// Returns a list of files inside the archive.
452    /**
453      \return A list of file names or an empty list if there
454      was an error or if the archive is empty (call getZipError() to
455      figure out which).
456      \sa getFileInfoList()
457      */
458    QStringList getFileNameList() const;
459    /// Returns information list about all files inside the archive.
460    /**
461      \return A list of QuaZipFileInfo objects or an empty list if there
462      was an error or if the archive is empty (call getZipError() to
463      figure out which).
464
465      This function doesn't support zip64, but will still work with zip64
466      archives, converting results using QuaZipFileInfo64::toQuaZipFileInfo().
467      If all file sizes are below 4 GB, it will work just fine.
468
469      \sa getFileNameList()
470      \sa getFileInfoList64()
471      */
472    QList<QuaZipFileInfo> getFileInfoList() const;
473    /// Returns information list about all files inside the archive.
474    /**
475      \overload
476
477      This function supports zip64.
478
479      \sa getFileNameList()
480      \sa getFileInfoList()
481      */
482    QList<QuaZipFileInfo64> getFileInfoList64() const;
483    /// Enables the zip64 mode.
484    /**
485     * @param zip64 If \c true, the zip64 mode is enabled, disabled otherwise.
486     *
487     * Once this is enabled, all new files (until the mode is disabled again)
488     * will be created in the zip64 mode, thus enabling the ability to write
489     * files larger than 4 GB. By default, the zip64 mode is off due to
490     * compatibility reasons.
491     *
492     * Note that this does not affect the ability to read zip64 archives in any
493     * way.
494     *
495     * \sa isZip64Enabled()
496     */
497    void setZip64Enabled(bool zip64);
498    /// Returns whether the zip64 mode is enabled.
499    /**
500     * @return \c true if and only if the zip64 mode is enabled.
501     *
502     * \sa setZip64Enabled()
503     */
504    bool isZip64Enabled() const;
505    /// Returns the auto-close flag.
506    /**
507      @sa setAutoClose()
508      */
509    bool isAutoClose() const;
510    /// Sets or unsets the auto-close flag.
511    /**
512      By default, QuaZIP opens the underlying QIODevice when open() is called,
513      and closes it when close() is called. In some cases, when the device
514      is set explicitly using setIoDevice(), it may be desirable to
515      leave the device open. If the auto-close flag is unset using this method,
516      then the device isn't closed automatically if it was set explicitly.
517
518      If it is needed to clear this flag, it is recommended to do so before
519      opening the archive because otherwise QuaZIP may close the device
520      during the open() call if an error is encountered after the device
521      is opened.
522
523      If the device was not set explicitly, but rather the setZipName() or
524      the appropriate constructor was used to set the ZIP file name instead,
525      then the auto-close flag has no effect, and the internal device
526      is closed nevertheless because there is no other way to close it.
527
528      @sa isAutoClose()
529      @sa setIoDevice()
530      */
531    void setAutoClose(bool autoClose) const;
532    /// Sets the default file name codec to use.
533    /**
534     * The default codec is used by the constructors, so calling this function
535     * won't affect the QuaZip instances already created at that moment.
536     *
537     * The codec specified here can be overriden by calling setFileNameCodec().
538     * If neither function is called, QTextCodec::codecForLocale() will be used
539     * to decode or encode file names. Use this function with caution if
540     * the application uses other libraries that depend on QuaZIP. Those
541     * libraries can either call this function by themselves, thus overriding
542     * your setting or can rely on the default encoding, thus failing
543     * mysteriously if you change it. For these reasons, it isn't recommended
544     * to use this function if you are developing a library, not an application.
545     * Instead, ask your library users to call it in case they need specific
546     * encoding.
547     *
548     * In most cases, using setFileNameCodec() instead is the right choice.
549     * However, if you depend on third-party code that uses QuaZIP, then the
550     * reasons stated above can actually become a reason to use this function
551     * in case the third-party code in question fails because it doesn't
552     * understand the encoding you need and doesn't provide a way to specify it.
553     * This applies to the JlCompress class as well, as it was contributed and
554     * doesn't support explicit encoding parameters.
555     *
556     * In short: use setFileNameCodec() when you can, resort to
557     * setDefaultFileNameCodec() when you don't have access to the QuaZip
558     * instance.
559     *
560     * @param codec The codec to use by default. If NULL, resets to default.
561     */
562    static void setDefaultFileNameCodec(QTextCodec *codec);
563    /**
564     * @overload
565     * Equivalent to calling
566     * setDefltFileNameCodec(QTextCodec::codecForName(codecName)).
567     */
568    static void setDefaultFileNameCodec(const char *codecName);
569};
570
571#endif
Note: See TracBrowser for help on using the repository browser.