source: Vago/Libs/quazip-0.7.2/doc/latex/usage.tex@ 1050

This page provides general information on QuaZIP usage. See classes \doxyref{QuaZip}{p.}{classQuaZip} and \doxyref{QuaZipFile}{p.}{classQuaZipFile} 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.

\doxyref{QuaZip}{p.}{classQuaZip} is a class representing ZIP archive, \doxyref{QuaZipFile}{p.}{classQuaZipFile} represents a file inside archive and subclasses {\bf QIODevice} as well. One limitation is that there can be only one instance of \doxyref{QuaZipFile}{p.}{classQuaZipFile} per \doxyref{QuaZip}{p.}{classQuaZip} 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.\section{Terminology}\label{usage_terminology}
\char`\"{}QuaZIP\char`\"{} means whole this library, while \char`\"{}QuaZip\char`\"{} (note the lower case) is just one class in it.

\char`\"{}ZIP/UNZIP API\char`\"{} or \char`\"{}minizip\char`\"{} means the original API of the Gilles Vollant's ZIP/UNZIP package. It was slightly modified to better integrate with {\bf 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.

\char`\"{}ZIP\char`\"{}, \char`\"{}ZIP archive\char`\"{} or \char`\"{}ZIP file\char`\"{} means any ZIP archive. Typically this is a plain file with \char`\"{}.zip\char`\"{} (or \char`\"{}.ZIP\char`\"{}) file name suffix, but it can also be any seekable {\bf QIODevice} (say, {\bf QBuffer}, but not QTcpSocket).

\char`\"{}A file inside archive\char`\"{}, \char`\"{}a file inside ZIP\char`\"{} or something like that means file either being read or written from/to some ZIP archive.\section{Error handling}\label{usage_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 \char`\"{}ZIP open mode\char`\"{} concept because read and write modes are completely separated. On the other hand, to avoid creating classes like \char`\"{}QuaZipReader\char`\"{}, \char`\"{}QuaZipWriter\char`\"{} or something like that, QuaZIP introduces \char`\"{}ZIP open mode\char`\"{} concept instead, thus making it possible to use one class (\doxyref{QuaZip}{p.}{classQuaZip}) 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:


\begin{DoxyItemize}
\item Both \doxyref{QuaZip}{p.}{classQuaZip} and \doxyref{QuaZipFile}{p.}{classQuaZipFile} have getZipError() function, which return error code of the last ZIP/UNZIP API call. Most function calls reset error code to UNZ\_\-OK on success and set error code on failure. Some functions do not reset error code. Most of them are {\ttfamily const} and do not access ZIP archive in any way. Some, on the other hand, {\itshape do\/} access ZIP archive, but do not reset or set error code. For example, \doxyref{QuaZipFile::pos()}{p.}{classQuaZipFile_a90fd55dab83eca7f95df50b2c41b7f22} function. Such functions are explicitly marked in the documentation.
\item Most functions have their own way to report errors, by returning a null string, negative value or {\ttfamily false}. If such a function returns error value, call getZipError() to get more information about error. See \char`\"{}zip.h\char`\"{} and \char`\"{}unzip.h\char`\"{} of the ZIP/UNZIP package for error codes.
\item If the function returns error-\/stating value (like {\ttfamily false}), but getZipError() returns UNZ\_\-OK, it means that you did something obviously wrong. For example, tried to write in the archive open for reading or not open at all. You better just not do that! Most functions also issue a warning using qWarning() function in such cases. See documentation for a specific function for details on when it should not be called.
\end{DoxyItemize}

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