|
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 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. |
|
12 * |
|
13 * \section terminology Terminology |
|
14 * |
|
15 * "QuaZIP" means whole this library, while "QuaZip" (not case |
|
16 * difference) is just one class in it. |
|
17 * |
|
18 * "ZIP/UNZIP API" means the original API of the Gilles Vollant's |
|
19 * ZIP/UNZIP package. I did not alter it in any way to make it easier to |
|
20 * port to the future ZIP/UNZIP versions. |
|
21 * |
|
22 * "ZIP", "ZIP archive" or "ZIP file" means any ZIP archive. Typically |
|
23 * this is a plain file with ".zip" (or ".ZIP") file name suffix. |
|
24 * |
|
25 * "A file inside archive", "a file inside ZIP" or something like that |
|
26 * means file either being read or written from/to some ZIP archive. |
|
27 * |
|
28 * \section error-handling Error handling |
|
29 * |
|
30 * Almost any call to ZIP/UNZIP API return some error code. Most of the |
|
31 * original API's error checking could be done in this wrapper as well, |
|
32 * but it would cause unnecessary code bloating without any benefit. So, |
|
33 * QuaZIP only checks for situations that ZIP/UNZIP API can not check |
|
34 * for. For example, ZIP/UNZIP API has no "ZIP open mode" concept |
|
35 * because read and write modes are completely separated. On the other |
|
36 * hand, to avoid creating classes like "QuaZipReader", "QuaZipWriter" |
|
37 * or something like that, QuaZIP introduces "ZIP open mode" concept |
|
38 * instead, thus making it possible to use one class (QuaZip) for both |
|
39 * reading and writing. But this leads to additional open mode checks |
|
40 * which are not done in ZIP/UNZIP package. |
|
41 * |
|
42 * Therefore, error checking is two-level (QuaZIP's level and ZIP/UNZIP |
|
43 * API level), which sometimes can be confusing, so here are some |
|
44 * advices on how the error checking should be properly done: |
|
45 * |
|
46 * - Both QuaZip and QuaZipFile have getZipError() function, which return |
|
47 * error code of the last ZIP/UNZIP API call. Most function calls |
|
48 * reset error code to UNZ_OK on success and set error code on |
|
49 * failure. Some functions do not reset error code. Most of them are |
|
50 * \c const and do not access ZIP archive in any way. Some, on the |
|
51 * other hand, \em do access ZIP archive, but do not reset or set |
|
52 * error code. For example, QuaZipFile::pos() function. Such functions |
|
53 * are explicitly marked in the documentation. |
|
54 * - Most functions have its own way to report errors, by returning a |
|
55 * null string, negative value or \c false. If such a function returns |
|
56 * error value, call getZipError() to get more information about |
|
57 * error. See "zip.h" and "unzip.h" of the ZIP/UNZIP package for error |
|
58 * codes. |
|
59 * - If the function returns error-stating value (like \c false), but |
|
60 * getZipError() returns UNZ_OK, it means that you did something |
|
61 * obviously wrong. For example, tried to write in the archive open |
|
62 * for reading or not open at all. You better just do not do that! |
|
63 * Most functions also issue a warning using qWarning() function in |
|
64 * such cases. See documentation for a specific function for details |
|
65 * on when it should not be called. |
|
66 * |
|
67 * I know that this is somewhat messy, but I could not find a better way |
|
68 * to do all the error handling. |
|
69 **/ |