| 1 | /** \page usage Usage
|
|---|
| 2 | *
|
|---|
| 3 | * This page provides general information on QuaZIP usage. See classes
|
|---|
| 4 | * QuaZip and QuaZipFile for the detailed documentation on what can
|
|---|
| 5 | * QuaZIP do and what it can not. Also, reading comments in the zip.h and
|
|---|
| 6 | * unzip.h files (taken from the original ZIP/UNZIP package) is always a
|
|---|
| 7 | * good idea too. After all, QuaZIP is just a wrapper with a few
|
|---|
| 8 | * convenience extensions and reimplementations.
|
|---|
| 9 | *
|
|---|
| 10 | * QuaZip is a class representing ZIP archive, QuaZipFile represents a
|
|---|
| 11 | * file inside archive and subclasses QIODevice as well. One limitation
|
|---|
| 12 | * is that there can be only one instance of QuaZipFile per QuaZip
|
|---|
| 13 | * instance, which kind of makes it confusing why there are two classes
|
|---|
| 14 | * instead of one. This is actually no more than an API design mistake.
|
|---|
| 15 | *
|
|---|
| 16 | * \section terminology Terminology
|
|---|
| 17 | *
|
|---|
| 18 | * "QuaZIP" means whole this library, while "QuaZip" (note the
|
|---|
| 19 | * lower case) is just one class in it.
|
|---|
| 20 | *
|
|---|
| 21 | * "ZIP/UNZIP API" or "minizip" means the original API of the Gilles
|
|---|
| 22 | * Vollant's ZIP/UNZIP package. It was slightly modified to better
|
|---|
| 23 | * integrate with Qt. These modifications are not source or binary
|
|---|
| 24 | * compatible with the official minizip release, which means you can't
|
|---|
| 25 | * just drop the newer minizip version into QuaZIP sources and make it
|
|---|
| 26 | * work.
|
|---|
| 27 | *
|
|---|
| 28 | * "ZIP", "ZIP archive" or "ZIP file" means any ZIP archive. Typically
|
|---|
| 29 | * this is a plain file with ".zip" (or ".ZIP") file name suffix, but it
|
|---|
| 30 | * can also be any seekable QIODevice (say, QBuffer, but not
|
|---|
| 31 | * QTcpSocket).
|
|---|
| 32 | *
|
|---|
| 33 | * "A file inside archive", "a file inside ZIP" or something like that
|
|---|
| 34 | * means file either being read or written from/to some ZIP archive.
|
|---|
| 35 | *
|
|---|
| 36 | * \section error-handling Error handling
|
|---|
| 37 | *
|
|---|
| 38 | * Almost any call to ZIP/UNZIP API return some error code. Most of the
|
|---|
| 39 | * original API's error checking could be done in this wrapper as well,
|
|---|
| 40 | * but it would cause unnecessary code bloating without any benefit. So,
|
|---|
| 41 | * QuaZIP only checks for situations that ZIP/UNZIP API can not check
|
|---|
| 42 | * for. For example, ZIP/UNZIP API has no "ZIP open mode" concept
|
|---|
| 43 | * because read and write modes are completely separated. On the other
|
|---|
| 44 | * hand, to avoid creating classes like "QuaZipReader", "QuaZipWriter"
|
|---|
| 45 | * or something like that, QuaZIP introduces "ZIP open mode" concept
|
|---|
| 46 | * instead, thus making it possible to use one class (QuaZip) for both
|
|---|
| 47 | * reading and writing. But this leads to additional open mode checks
|
|---|
| 48 | * which are not done in ZIP/UNZIP package.
|
|---|
| 49 | *
|
|---|
| 50 | * Therefore, error checking is two-level (QuaZIP's level and ZIP/UNZIP
|
|---|
| 51 | * API level), which sometimes can be confusing, so here are some
|
|---|
| 52 | * advices on how the error checking should be properly done:
|
|---|
| 53 | *
|
|---|
| 54 | * - Both QuaZip and QuaZipFile have getZipError() function, which return
|
|---|
| 55 | * error code of the last ZIP/UNZIP API call. Most function calls
|
|---|
| 56 | * reset error code to UNZ_OK on success and set error code on
|
|---|
| 57 | * failure. Some functions do not reset error code. Most of them are
|
|---|
| 58 | * \c const and do not access ZIP archive in any way. Some, on the
|
|---|
| 59 | * other hand, \em do access ZIP archive, but do not reset or set
|
|---|
| 60 | * error code. For example, QuaZipFile::pos() function. Such functions
|
|---|
| 61 | * are explicitly marked in the documentation.
|
|---|
| 62 | * - Most functions have their own way to report errors, by returning a
|
|---|
| 63 | * null string, negative value or \c false. If such a function returns
|
|---|
| 64 | * error value, call getZipError() to get more information about
|
|---|
| 65 | * error. See "zip.h" and "unzip.h" of the ZIP/UNZIP package for error
|
|---|
| 66 | * codes.
|
|---|
| 67 | * - If the function returns error-stating value (like \c false), but
|
|---|
| 68 | * getZipError() returns UNZ_OK, it means that you did something
|
|---|
| 69 | * obviously wrong. For example, tried to write in the archive open
|
|---|
| 70 | * for reading or not open at all. You better just not do that!
|
|---|
| 71 | * Most functions also issue a warning using qWarning() function in
|
|---|
| 72 | * such cases. See documentation for a specific function for details
|
|---|
| 73 | * on when it should not be called.
|
|---|
| 74 | *
|
|---|
| 75 | * I know that this is somewhat messy, but I could not find a better way
|
|---|
| 76 | * to do all the error handling.
|
|---|
| 77 | **/
|
|---|
