QuaZIP quazip-0-9
Usage

This page provides general information on QuaZIP usage. See classes QuaZip and QuaZipFile for the detailed documentation on what can QuaZIP do and what it can not. Also, reading comments in the zip.h and unzip.h files (taken from the original ZIP/UNZIP package) is always a good idea too. After all, QuaZIP is just a wrapper with a few convenience extensions and reimplementations.

QuaZip is a class representing ZIP archive, QuaZipFile represents a file inside archive and subclasses QIODevice as well. One limitation is that there can be only one instance of QuaZipFile per QuaZip instance, which kind of makes it confusing why there are two classes instead of one. This is actually no more than an API design mistake kept for backwards compatibility.

The JlCompress class provides some high-level convenience static methods which may be very useful if all you need is just to “unzip a file” or something like that.

Terminology

“QuaZIP” means the whole library, while “QuaZip” (note the lower case) is just one class in it.

“ZIP/UNZIP API” or “Minizip” means the original API of the Gilles Vollant's ZIP/UNZIP package. It was slightly modified to better integrate with Qt. These modifications are not source or binary compatible with the official Minizip release, which means you can't just drop the newer Minizip version into QuaZIP sources and make it work.

“ZIP”, “ZIP archive” or “ZIP file” means any ZIP archive. Typically this is a plain file with “.zip” (or “.ZIP”) file name suffix, but it can also be any seekable QIODevice (say, QBuffer, but not QTcpSocket).

“A file inside archive”, “a file inside ZIP” or something like that means file either being read or written from/to some ZIP archive.

General usage

In general, the process looks like this:

  1. Open or create an archive with a QuaZip instance.
  2. Open or create a file in the archive with a QuaZipFile instance.
  3. Perform reading or writing.
  4. Close the QuaZipFile instance.
  5. Repeat steps 2–4 for other files if needed.
  6. Close the QuaZIP instance.

See the “qztest” subdirectory for examples. TestQuaZipFile::zipUnzip() is a good place to start.

Error handling

Almost any call to ZIP/UNZIP API return some error code. Most of the original API's error checking could be done in this wrapper as well, but it would cause unnecessary code bloating without any benefit. So, QuaZIP only checks for situations that ZIP/UNZIP API can not check for. For example, ZIP/UNZIP API has no “ZIP open mode” concept because read and write modes are completely separated. On the other hand, to avoid creating classes like “QuaZipReader”, “QuaZipWriter” or something like that, QuaZIP introduces “ZIP open mode” concept instead, thus making it possible to use one class (QuaZip) for both reading and writing. But this leads to additional open mode checks which are not done in ZIP/UNZIP package.

Therefore, error checking is two-level (QuaZIP's level and ZIP/UNZIP API level), which sometimes can be confusing, so here are some advices on how the error checking should be properly done:

I know that this is somewhat messy, but I could not find a better way to do all the error handling.