quazip-0.7.2/quazip/quazipfile.h

#ifndef QUA_ZIPFILE_H
#define QUA_ZIPFILE_H

/*
Copyright (C) 2005-2014 Sergey A. Tachenov

This file is part of QuaZIP.

QuaZIP is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 2.1 of the License, or
(at your option) any later version.

QuaZIP is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with QuaZIP.  If not, see <http://www.gnu.org/licenses/>.

See COPYING file for the full LGPL text.

Original ZIP package is copyrighted by Gilles Vollant, see
quazip/(un)zip.h files for details, basically it's zlib license.
 **/

#include <QIODevice>

#include "quazip_global.h"
#include "quazip.h"
#include "quazipnewinfo.h"

class QuaZipFilePrivate;

/// A file inside ZIP archive.
/** \class QuaZipFile quazipfile.h <quazip/quazipfile.h>
 * This is the most interesting class. Not only it provides C++
 * interface to the ZIP/UNZIP package, but also integrates it with Qt by
 * subclassing QIODevice. This makes possible to access files inside ZIP
 * archive using QTextStream or QDataStream, for example. Actually, this
 * is the main purpose of the whole QuaZIP library.
 *
 * You can either use existing QuaZip instance to create instance of
 * this class or pass ZIP archive file name to this class, in which case
 * it will create internal QuaZip object. See constructors' descriptions
 * for details. Writing is only possible with the existing instance.
 *
 * Note that due to the underlying library's limitation it is not
 * possible to use multiple QuaZipFile instances to open several files
 * in the same archive at the same time. If you need to write to
 * multiple files in parallel, then you should write to temporary files
 * first, then pack them all at once when you have finished writing. If
 * you need to read multiple files inside the same archive in parallel,
 * you should extract them all into a temporary directory first.
 *
 * \section quazipfile-sequential Sequential or random-access?
 *
 * At the first thought, QuaZipFile has fixed size, the start and the
 * end and should be therefore considered random-access device. But
 * there is one major obstacle to making it random-access: ZIP/UNZIP API
 * does not support seek() operation and the only way to implement it is
 * through reopening the file and re-reading to the required position,
 * but this is prohibitively slow.
 *
 * Therefore, QuaZipFile is considered to be a sequential device. This
 * has advantage of availability of the ungetChar() operation (QIODevice
 * does not implement it properly for non-sequential devices unless they
 * support seek()). Disadvantage is a somewhat strange behaviour of the
 * size() and pos() functions. This should be kept in mind while using
 * this class.
 *
 **/
class QUAZIP_EXPORT QuaZipFile: public QIODevice {
  friend class QuaZipFilePrivate;
  Q_OBJECT
  private:
    QuaZipFilePrivate *p;
    // these are not supported nor implemented
    QuaZipFile(const QuaZipFile& that);
    QuaZipFile& operator=(const QuaZipFile& that);
  protected:
    /// Implementation of the QIODevice::readData().
    qint64 readData(char *data, qint64 maxSize);
    /// Implementation of the QIODevice::writeData().
    qint64 writeData(const char *data, qint64 maxSize);
  public:
    /// Constructs a QuaZipFile instance.
    /** You should use setZipName() and setFileName() or setZip() before
     * trying to call open() on the constructed object.
     **/
    QuaZipFile();
    /// Constructs a QuaZipFile instance.
    /** \a parent argument specifies this object's parent object.
     *
     * You should use setZipName() and setFileName() or setZip() before
     * trying to call open() on the constructed object.
     **/
    QuaZipFile(QObject *parent);
    /// Constructs a QuaZipFile instance.
    /** \a parent argument specifies this object's parent object and \a
     * zipName specifies ZIP archive file name.
     *
     * You should use setFileName() before trying to call open() on the
     * constructed object.
     *
     * QuaZipFile constructed by this constructor can be used for read
     * only access. Use QuaZipFile(QuaZip*,QObject*) for writing.
     **/
    QuaZipFile(const QString& zipName, QObject *parent =NULL);
    /// Constructs a QuaZipFile instance.
    /** \a parent argument specifies this object's parent object, \a
     * zipName specifies ZIP archive file name and \a fileName and \a cs
     * specify a name of the file to open inside archive.
     *
     * QuaZipFile constructed by this constructor can be used for read
     * only access. Use QuaZipFile(QuaZip*,QObject*) for writing.
     *
     * \sa QuaZip::setCurrentFile()
     **/
    QuaZipFile(const QString& zipName, const QString& fileName,
        QuaZip::CaseSensitivity cs =QuaZip::csDefault, QObject *parent =NULL);
    /// Constructs a QuaZipFile instance.
    /** \a parent argument specifies this object's parent object.
     *
     * \a zip is the pointer to the existing QuaZip object. This
     * QuaZipFile object then can be used to read current file in the
     * \a zip or to write to the file inside it.
     *
     * \warning Using this constructor for reading current file can be
     * tricky. Let's take the following example:
     * \code
     * QuaZip zip("archive.zip");
     * zip.open(QuaZip::mdUnzip);
     * zip.setCurrentFile("file-in-archive");
     * QuaZipFile file(&zip);
     * file.open(QIODevice::ReadOnly);
     * // ok, now we can read from the file
     * file.read(somewhere, some);
     * zip.setCurrentFile("another-file-in-archive"); // oops...
     * QuaZipFile anotherFile(&zip);
     * anotherFile.open(QIODevice::ReadOnly);
     * anotherFile.read(somewhere, some); // this is still ok...
     * file.read(somewhere, some); // and this is NOT
     * \endcode
     * So, what exactly happens here? When we change current file in the
     * \c zip archive, \c file that references it becomes invalid
     * (actually, as far as I understand ZIP/UNZIP sources, it becomes
     * closed, but QuaZipFile has no means to detect it).
     *
     * Summary: do not close \c zip object or change its current file as
     * long as QuaZipFile is open. Even better - use another constructors
     * which create internal QuaZip instances, one per object, and
     * therefore do not cause unnecessary trouble. This constructor may
     * be useful, though, if you already have a QuaZip instance and do
     * not want to access several files at once. Good example:
     * \code
     * QuaZip zip("archive.zip");
     * zip.open(QuaZip::mdUnzip);
     * // first, we need some information about archive itself
     * QByteArray comment=zip.getComment();
     * // and now we are going to access files inside it
     * QuaZipFile file(&zip);
     * for(bool more=zip.goToFirstFile(); more; more=zip.goToNextFile()) {
     *   file.open(QIODevice::ReadOnly);
     *   // do something cool with file here
     *   file.close(); // do not forget to close!
     * }
     * zip.close();
     * \endcode
     **/
    QuaZipFile(QuaZip *zip, QObject *parent =NULL);
    /// Destroys a QuaZipFile instance.
    /** Closes file if open, destructs internal QuaZip object (if it
     * exists and \em is internal, of course).
     **/
    virtual ~QuaZipFile();
    /// Returns the ZIP archive file name.
    /** If this object was created by passing QuaZip pointer to the
     * constructor, this function will return that QuaZip's file name
     * (or null string if that object does not have file name yet).
     *
     * Otherwise, returns associated ZIP archive file name or null
     * string if there are no name set yet.
     *
     * \sa setZipName() getFileName()
     **/
    QString getZipName()const;
    /// Returns a pointer to the associated QuaZip object.
    /** Returns \c NULL if there is no associated QuaZip or it is
     * internal (so you will not mess with it).
     **/
    QuaZip* getZip()const;
    /// Returns file name.
    /** This function returns file name you passed to this object either
     * by using
     * QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*)
     * or by calling setFileName(). Real name of the file may differ in
     * case if you used case-insensitivity.
     *
     * Returns null string if there is no file name set yet. This is the
     * case when this QuaZipFile operates on the existing QuaZip object
     * (constructor QuaZipFile(QuaZip*,QObject*) or setZip() was used).
     * 
     * \sa getActualFileName
     **/
    QString getFileName() const;
    /// Returns case sensitivity of the file name.
    /** This function returns case sensitivity argument you passed to
     * this object either by using
     * QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*)
     * or by calling setFileName().
     *
     * Returns unpredictable value if getFileName() returns null string
     * (this is the case when you did not used setFileName() or
     * constructor above).
     *
     * \sa getFileName
     **/
    QuaZip::CaseSensitivity getCaseSensitivity() const;
    /// Returns the actual file name in the archive.
    /** This is \em not a ZIP archive file name, but a name of file inside
     * archive. It is not necessary the same name that you have passed
     * to the
     * QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*),
     * setFileName() or QuaZip::setCurrentFile() - this is the real file
     * name inside archive, so it may differ in case if the file name
     * search was case-insensitive.
     *
     * Equivalent to calling getCurrentFileName() on the associated
     * QuaZip object. Returns null string if there is no associated
     * QuaZip object or if it does not have a current file yet. And this
     * is the case if you called setFileName() but did not open the
     * file yet. So this is perfectly fine:
     * \code
     * QuaZipFile file("somezip.zip");
     * file.setFileName("somefile");
     * QString name=file.getName(); // name=="somefile"
     * QString actual=file.getActualFileName(); // actual is null string
     * file.open(QIODevice::ReadOnly);
     * QString actual=file.getActualFileName(); // actual can be "SoMeFiLe" on Windows
     * \endcode
     *
     * \sa getZipName(), getFileName(), QuaZip::CaseSensitivity
     **/
    QString getActualFileName()const;
    /// Sets the ZIP archive file name.
    /** Automatically creates internal QuaZip object and destroys
     * previously created internal QuaZip object, if any.
     *
     * Will do nothing if this file is already open. You must close() it
     * first.
     **/
    void setZipName(const QString& zipName);
    /// Returns \c true if the file was opened in raw mode.
    /** If the file is not open, the returned value is undefined.
     *
     * \sa open(OpenMode,int*,int*,bool,const char*)
     **/
    bool isRaw() const;
    /// Binds to the existing QuaZip instance.
    /** This function destroys internal QuaZip object, if any, and makes
     * this QuaZipFile to use current file in the \a zip object for any
     * further operations. See QuaZipFile(QuaZip*,QObject*) for the
     * possible pitfalls.
     *
     * Will do nothing if the file is currently open. You must close()
     * it first.
     **/
    void setZip(QuaZip *zip);
    /// Sets the file name.
    /** Will do nothing if at least one of the following conditions is
     * met:
     * - ZIP name has not been set yet (getZipName() returns null
     *   string).
     * - This QuaZipFile is associated with external QuaZip. In this
     *   case you should call that QuaZip's setCurrentFile() function
     *   instead!
     * - File is already open so setting the name is meaningless.
     *
     * \sa QuaZip::setCurrentFile
     **/
    void setFileName(const QString& fileName, QuaZip::CaseSensitivity cs =QuaZip::csDefault);
    /// Opens a file for reading.
    /** Returns \c true on success, \c false otherwise.
     * Call getZipError() to get error code.
     *
     * \note Since ZIP/UNZIP API provides buffered reading only,
     * QuaZipFile does not support unbuffered reading. So do not pass
     * QIODevice::Unbuffered flag in \a mode, or open will fail.
     **/
    virtual bool open(OpenMode mode);
    /// Opens a file for reading.
    /** \overload
     * Argument \a password specifies a password to decrypt the file. If
     * it is NULL then this function behaves just like open(OpenMode).
     **/
    inline bool open(OpenMode mode, const char *password)
    {return open(mode, NULL, NULL, false, password);}
    /// Opens a file for reading.
    /** \overload
     * Argument \a password specifies a password to decrypt the file.
     *
     * An integers pointed by \a method and \a level will receive codes
     * of the compression method and level used. See unzip.h.
     *
     * If raw is \c true then no decompression is performed.
     *
     * \a method should not be \c NULL. \a level can be \c NULL if you
     * don't want to know the compression level.
     **/
    bool open(OpenMode mode, int *method, int *level, bool raw, const char *password =NULL);
    /// Opens a file for writing.
    /** \a info argument specifies information about file. It should at
     * least specify a correct file name. Also, it is a good idea to
     * specify correct timestamp (by default, current time will be
     * used). See QuaZipNewInfo.
     *
     * The \a password argument specifies the password for crypting. Pass NULL
     * if you don't need any crypting. The \a crc argument was supposed
     * to be used for crypting too, but then it turned out that it's
     * false information, so you need to set it to 0 unless you want to
     * use the raw mode (see below).
     *
     * Arguments \a method and \a level specify compression method and
     * level. The only method supported is Z_DEFLATED, but you may also
     * specify 0 for no compression. If all of the files in the archive
     * use both method 0 and either level 0 is explicitly specified or
     * data descriptor writing is disabled with
     * QuaZip::setDataDescriptorWritingEnabled(), then the
     * resulting archive is supposed to be compatible with the 1.0 ZIP
     * format version, should you need that. Except for this, \a level
     * has no other effects with method 0.
     *
     * If \a raw is \c true, no compression is performed. In this case,
     * \a crc and uncompressedSize field of the \a info are required.
     *
     * Arguments \a windowBits, \a memLevel, \a strategy provide zlib
     * algorithms tuning. See deflateInit2() in zlib.
     **/
    bool open(OpenMode mode, const QuaZipNewInfo& info,
        const char *password =NULL, quint32 crc =0,
        int method =Z_DEFLATED, int level =Z_DEFAULT_COMPRESSION, bool raw =false,
        int windowBits =-MAX_WBITS, int memLevel =DEF_MEM_LEVEL, int strategy =Z_DEFAULT_STRATEGY);
    /// Returns \c true, but \ref quazipfile-sequential "beware"!
    virtual bool isSequential()const;
    /// Returns current position in the file.
    /** Implementation of the QIODevice::pos(). When reading, this
     * function is a wrapper to the ZIP/UNZIP unztell(), therefore it is
     * unable to keep track of the ungetChar() calls (which is
     * non-virtual and therefore is dangerous to reimplement). So if you
     * are using ungetChar() feature of the QIODevice, this function
     * reports incorrect value until you get back characters which you
     * ungot.
     *
     * When writing, pos() returns number of bytes already written
     * (uncompressed unless you use raw mode).
     *
     * \note Although
     * \ref quazipfile-sequential "QuaZipFile is a sequential device"
     * and therefore pos() should always return zero, it does not,
     * because it would be misguiding. Keep this in mind.
     *
     * This function returns -1 if the file or archive is not open.
     *
     * Error code returned by getZipError() is not affected by this
     * function call.
     **/
    virtual qint64 pos()const;
    /// Returns \c true if the end of file was reached.
    /** This function returns \c false in the case of error. This means
     * that you called this function on either not open file, or a file
     * in the not open archive or even on a QuaZipFile instance that
     * does not even have QuaZip instance associated. Do not do that
     * because there is no means to determine whether \c false is
     * returned because of error or because end of file was reached.
     * Well, on the other side you may interpret \c false return value
     * as "there is no file open to check for end of file and there is
     * no end of file therefore".
     *
     * When writing, this function always returns \c true (because you
     * are always writing to the end of file).
     *
     * Error code returned by getZipError() is not affected by this
     * function call.
     **/
    virtual bool atEnd()const;
    /// Returns file size.
    /** This function returns csize() if the file is open for reading in
     * raw mode, usize() if it is open for reading in normal mode and
     * pos() if it is open for writing.
     *
     * Returns -1 on error, call getZipError() to get error code.
     *
     * \note This function returns file size despite that
     * \ref quazipfile-sequential "QuaZipFile is considered to be sequential device",
     * for which size() should return bytesAvailable() instead. But its
     * name would be very misguiding otherwise, so just keep in mind
     * this inconsistence.
     **/
    virtual qint64 size()const;
    /// Returns compressed file size.
    /** Equivalent to calling getFileInfo() and then getting
     * compressedSize field, but more convenient and faster.
     *
     * File must be open for reading before calling this function.
     *
     * Returns -1 on error, call getZipError() to get error code.
     **/
    qint64 csize()const;
    /// Returns uncompressed file size.
    /** Equivalent to calling getFileInfo() and then getting
     * uncompressedSize field, but more convenient and faster. See
     * getFileInfo() for a warning.
     *
     * File must be open for reading before calling this function.
     *
     * Returns -1 on error, call getZipError() to get error code.
     **/
    qint64 usize()const;
    /// Gets information about current file.
    /** This function does the same thing as calling
     * QuaZip::getCurrentFileInfo() on the associated QuaZip object,
     * but you can not call getCurrentFileInfo() if the associated
     * QuaZip is internal (because you do not have access to it), while
     * you still can call this function in that case.
     *
     * File must be open for reading before calling this function.
     *
     * \return \c false in the case of an error.
     *
     * This function doesn't support zip64, but will still work fine on zip64
     * archives if file sizes are below 4 GB, otherwise the values will be set
     * as if converted using QuaZipFileInfo64::toQuaZipFileInfo().
     *
     * \sa getFileInfo(QuaZipFileInfo64*)
     **/
    bool getFileInfo(QuaZipFileInfo *info);
    /// Gets information about current file with zip64 support.
    /**
     * @overload
     *
     * \sa getFileInfo(QuaZipFileInfo*)
     */
    bool getFileInfo(QuaZipFileInfo64 *info);
    /// Closes the file.
    /** Call getZipError() to determine if the close was successful.
     **/
    virtual void close();
    /// Returns the error code returned by the last ZIP/UNZIP API call.
    int getZipError() const;
    /// Returns the number of bytes available for reading.
    virtual qint64 bytesAvailable() const;
};

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