| 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 |
**/ |
