| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|---|
| 2 | <html xmlns="http://www.w3.org/1999/xhtml">
|
|---|
| 3 | <head>
|
|---|
| 4 | <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|---|
| 5 | <title>QuaZIP: Usage</title>
|
|---|
| 6 | <link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|---|
| 7 | <link href="doxygen.css" rel="stylesheet" type="text/css"/>
|
|---|
| 8 | </head>
|
|---|
| 9 | <body>
|
|---|
| 10 | <!-- Generated by Doxygen 1.7.4 -->
|
|---|
| 11 | <div id="top">
|
|---|
| 12 | <div id="titlearea">
|
|---|
| 13 | <table cellspacing="0" cellpadding="0">
|
|---|
| 14 | <tbody>
|
|---|
| 15 | <tr style="height: 56px;">
|
|---|
| 16 | <td style="padding-left: 0.5em;">
|
|---|
| 17 | <div id="projectname">QuaZIP <span id="projectnumber">quazip-0-7-2</span></div>
|
|---|
| 18 | </td>
|
|---|
| 19 | </tr>
|
|---|
| 20 | </tbody>
|
|---|
| 21 | </table>
|
|---|
| 22 | </div>
|
|---|
| 23 | <div id="navrow1" class="tabs">
|
|---|
| 24 | <ul class="tablist">
|
|---|
| 25 | <li><a href="index.html"><span>Main Page</span></a></li>
|
|---|
| 26 | <li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
|
|---|
| 27 | <li><a href="annotated.html"><span>Classes</span></a></li>
|
|---|
| 28 | <li><a href="files.html"><span>Files</span></a></li>
|
|---|
| 29 | <li><a href="dirs.html"><span>Directories</span></a></li>
|
|---|
| 30 | </ul>
|
|---|
| 31 | </div>
|
|---|
| 32 | </div>
|
|---|
| 33 | <div class="header">
|
|---|
| 34 | <div class="headertitle">
|
|---|
| 35 | <div class="title">Usage </div> </div>
|
|---|
| 36 | </div>
|
|---|
| 37 | <div class="contents">
|
|---|
| 38 | <div class="textblock"><p>This page provides general information on QuaZIP usage. See classes <a class="el" href="classQuaZip.html" title="ZIP archive.">QuaZip</a> and <a class="el" href="classQuaZipFile.html" title="A file inside ZIP archive.">QuaZipFile</a> 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.</p>
|
|---|
| 39 | <p><a class="el" href="classQuaZip.html" title="ZIP archive.">QuaZip</a> is a class representing ZIP archive, <a class="el" href="classQuaZipFile.html" title="A file inside ZIP archive.">QuaZipFile</a> represents a file inside archive and subclasses <a class="elRef" doxygen="qtcore.tags:http://doc.qt.io/qt-5//" href="http://doc.qt.io/qt-5/qiodevice.html">QIODevice</a> as well. One limitation is that there can be only one instance of <a class="el" href="classQuaZipFile.html" title="A file inside ZIP archive.">QuaZipFile</a> per <a class="el" href="classQuaZip.html" title="ZIP archive.">QuaZip</a> 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.</p>
|
|---|
| 40 | <h2><a class="anchor" id="terminology"></a>
|
|---|
| 41 | Terminology</h2>
|
|---|
| 42 | <p>"QuaZIP" means whole this library, while "QuaZip" (note the lower case) is just one class in it.</p>
|
|---|
| 43 | <p>"ZIP/UNZIP API" or "minizip" means the original API of the Gilles Vollant's ZIP/UNZIP package. It was slightly modified to better integrate with <a class="elRef" doxygen="qtcore.tags:http://doc.qt.io/qt-5//" href="http://doc.qt.io/qt-5/qt.html">Qt</a>. 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.</p>
|
|---|
| 44 | <p>"ZIP", "ZIP archive" or "ZIP file" means any ZIP archive. Typically this is a plain file with ".zip" (or ".ZIP") file name suffix, but it can also be any seekable <a class="elRef" doxygen="qtcore.tags:http://doc.qt.io/qt-5//" href="http://doc.qt.io/qt-5/qiodevice.html">QIODevice</a> (say, <a class="elRef" doxygen="qtcore.tags:http://doc.qt.io/qt-5//" href="http://doc.qt.io/qt-5/qbuffer.html">QBuffer</a>, but not QTcpSocket).</p>
|
|---|
| 45 | <p>"A file inside archive", "a file inside ZIP" or something like that means file either being read or written from/to some ZIP archive.</p>
|
|---|
| 46 | <h2><a class="anchor" id="error-handling"></a>
|
|---|
| 47 | Error handling</h2>
|
|---|
| 48 | <p>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 "ZIP open mode" concept because read and write modes are completely separated. On the other hand, to avoid creating classes like "QuaZipReader", "QuaZipWriter" or something like that, QuaZIP introduces "ZIP open mode" concept instead, thus making it possible to use one class (<a class="el" href="classQuaZip.html" title="ZIP archive.">QuaZip</a>) for both reading and writing. But this leads to additional open mode checks which are not done in ZIP/UNZIP package.</p>
|
|---|
| 49 | <p>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:</p>
|
|---|
| 50 | <ul>
|
|---|
| 51 | <li>Both <a class="el" href="classQuaZip.html" title="ZIP archive.">QuaZip</a> and <a class="el" href="classQuaZipFile.html" title="A file inside ZIP archive.">QuaZipFile</a> 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 <code>const</code> and do not access ZIP archive in any way. Some, on the other hand, <em>do</em> access ZIP archive, but do not reset or set error code. For example, <a class="el" href="classQuaZipFile.html#a90fd55dab83eca7f95df50b2c41b7f22" title="Returns current position in the file.">QuaZipFile::pos()</a> function. Such functions are explicitly marked in the documentation.</li>
|
|---|
| 52 | <li>Most functions have their own way to report errors, by returning a null string, negative value or <code>false</code>. If such a function returns error value, call getZipError() to get more information about error. See "zip.h" and "unzip.h" of the ZIP/UNZIP package for error codes.</li>
|
|---|
| 53 | <li>If the function returns error-stating value (like <code>false</code>), 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.</li>
|
|---|
| 54 | </ul>
|
|---|
| 55 | <p>I know that this is somewhat messy, but I could not find a better way to do all the error handling. </p>
|
|---|
| 56 | </div></div>
|
|---|
| 57 | <hr class="footer"/><address class="footer"><small>Generated on Sun Apr 3 2016 08:26:24 for QuaZIP by 
|
|---|
| 58 | <a href="http://www.doxygen.org/index.html">
|
|---|
| 59 | <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
|
|---|
| 60 | </body>
|
|---|
| 61 | </html>
|
|---|
