misc/quazip/quazipfile.h
changeset 7889 57b117d441b9
parent 5752 ea95ee97c805
--- a/misc/quazip/quazipfile.h	Mon Oct 29 17:38:54 2012 -0400
+++ b/misc/quazip/quazipfile.h	Mon Oct 29 18:20:08 2012 -0400
@@ -1,433 +1,433 @@
-#ifndef QUA_ZIPFILE_H
-#define QUA_ZIPFILE_H
-
-/*
-Copyright (C) 2005-2011 Sergey A. Tachenov
-
-This program 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 of the License, or (at
-your option) any later version.
-
-This program 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 this program; if not, write to the Free Software Foundation,
-Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-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.
-     *
-     * Arguments \a password and \a crc provide necessary information
-     * for crypting. Note that you should specify both of them if you
-     * need crypting. If you do not, pass \c NULL as password, but you
-     * still need to specify \a crc if you are going to use raw mode
-     * (see below).
-     *
-     * Arguments \a method and \a level specify compression method and
-     * level.
-     *
-     * 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.
-     *
-     * Returns \c false in the case of an error.
-     **/
-    bool getFileInfo(QuaZipFileInfo *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;
-};
-
-#endif
+#ifndef QUA_ZIPFILE_H
+#define QUA_ZIPFILE_H
+
+/*
+Copyright (C) 2005-2011 Sergey A. Tachenov
+
+This program 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 of the License, or (at
+your option) any later version.
+
+This program 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 this program; if not, write to the Free Software Foundation,
+Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+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.
+     *
+     * Arguments \a password and \a crc provide necessary information
+     * for crypting. Note that you should specify both of them if you
+     * need crypting. If you do not, pass \c NULL as password, but you
+     * still need to specify \a crc if you are going to use raw mode
+     * (see below).
+     *
+     * Arguments \a method and \a level specify compression method and
+     * level.
+     *
+     * 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.
+     *
+     * Returns \c false in the case of an error.
+     **/
+    bool getFileInfo(QuaZipFileInfo *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;
+};
+
+#endif