source: Vago/Libs/quazip-0.7.2/quazip/doc/usage.dox@ 1069

Last change on this file since 1069 was 1050, checked in by s10k, 8 years ago
File size: 4.0 KB
RevLine 
[1050]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 **/
Note: See TracBrowser for help on using the repository browser.