diff options
Diffstat (limited to 'daemon/quazip/doc')
| -rw-r--r-- | daemon/quazip/doc/faq.dox | 45 | ||||
| -rw-r--r-- | daemon/quazip/doc/index.dox | 177 | ||||
| -rw-r--r-- | daemon/quazip/doc/usage.dox | 77 |
3 files changed, 299 insertions, 0 deletions
diff --git a/daemon/quazip/doc/faq.dox b/daemon/quazip/doc/faq.dox new file mode 100644 index 0000000..68fc52b --- /dev/null +++ b/daemon/quazip/doc/faq.dox @@ -0,0 +1,45 @@ +/** + * \page faq QuaZip FAQ + * + * <!-- + * + * \ref faq-non-QIODevice "Q. Is there any way to use QuaZipFile in Qt where you are supposed to use normal (non-zipped) file, but not through QIODevice API?" + * \ref faq-zip64 "Q. Can QuaZIP handle files larger than 4GB? What about zip64 standard?" + * + * \ref faq-seekable "Q. Can QuaZIP write archives to a sequential QIODevice like QTcpSocket?" + * + * --> + * + * \anchor faq-non-QIODevice Q. Is there any way to use QuaZipFile in Qt + * where you are supposed to use normal (non-zipped) file, but not + * through QIODevice API? + * + * A. Usually not. For example, if you are passing file name to some + * database driver (like SQLite), Qt usually just passes this name down + * to the 3rd-party library, which is usually does not know anything + * about QIODevice and therefore there is no way to pass QuaZipFile as + * normal file. However, if we are talking about some place where you + * pass file name, and then indirectly use QFile to open it, then it is + * a good idea to make overloaded method, which accepts a QIODevice + * pointer. Then you would be able to pass QuaZipFile as well as many + * other nice things such as QBuffer or QProcess. + * + * \anchor faq-zip64 Q. Can QuaZIP handle files larger than 4GB? What + * about zip64 standard? + * + * A. Starting with version 0.6, QuaZIP uses Minizip 1.1 with zip64 + * support which should handle large files perfectly. The zip64 support + * in Minizip looks like it's not 100% conforming to the standard, but + * 3rd party tools seem to have no problem with the resulting archives. + * + * \anchor faq-seekable Q. Can QuaZIP write archives to a sequential QIODevice like QTcpSocket? + * + * A. Not yet. It is not supported by vanilla Minizip (the back-end + * QuaZIP uses), although theoretically possible according to the ZIP + * standard. It would require some Minizip modifications that would + * allow it to detect non-seekable I/O and produce necessary output + * structures. QuaZIP already writes data descriptor which is necessary + * for non-seekable I/O. The only thing that is apparently left is to + * make Minizip fill local headers with correct values and forget about + * seeking after closing the file. + **/ diff --git a/daemon/quazip/doc/index.dox b/daemon/quazip/doc/index.dox new file mode 100644 index 0000000..ae45c5c --- /dev/null +++ b/daemon/quazip/doc/index.dox @@ -0,0 +1,177 @@ +/** + * \mainpage QuaZIP - Qt/C++ wrapper for ZIP/UNZIP package + * +\htmlonly +<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=142688&type=7" style="width:210; height:62; border:none; float:right;" alt="Powered by SourceForge.net" /></a> +\endhtmlonly + * \section overview Overview + * + * QuaZIP is a simple C++ wrapper over <a + * href="http://www.winimage.com/zLibDll/minizip.html">Gilles Vollant's ZIP/UNZIP + * package</a> that can be used to access ZIP archives. It uses <a + * href="http://qt.digia.com/">the Qt toolkit</a>. + * + * If you do not know what Qt is, you have two options: + * - Just forget about QuaZIP. + * - Learn more about Qt by downloading it and/or reading the excellent <a + * href="http://qt-project.org/doc/">official Qt documentation</a> + * + * The choice is yours, but if you are really interested in + * cross-platform (Windows/Linux/BSD/UNIX/Mac/Others) software + * development, I would definitely recommend you the latter ^_^ + * + * QuaZIP allows you to access files inside ZIP archives using QIODevice + * API, and - yes! - that means that you can also use QTextStream, + * QDataStream or whatever you would like to use on your zipped files. + * + * QuaZIP provides complete abstraction of the ZIP/UNZIP API, for both + * reading from and writing to ZIP archives. + * + * \section download Download QuaZIP + * + * Downloads are available from <a + * href="http://sourceforge.net/projects/quazip/">QuaZIP project's page + * at SourceForge.net</a>. + * + * \section platforms Platforms supported + * + * QuaZIP has been currently tested on the following platforms: + * - linux-g++ (Ubuntu 11.10, Qt 4.7.4) + * - freebsd-g++ (Qt 4.0.0 + * - hpux-acc (HP-UX 11.11) + * - hpux-g++ (HP-UX 11.11) + * - win32-g++ (MinGW) + * - win32-msvc2010 (MS VS 2010 Express, Qt 4.8.4) + * - win32-msvc2010 (Qt Creator, Qt 5.0.1) + * - win32-msvc2012 (Qt Creator, Qt 5.2.0) + * - some Symbian version, reportedly + * + * No testing has been officially done on other systems. Of course, patches to + * make it work on any platform that it currently does not work on are + * always welcome! + * + * \section whats-new What is new in this version of QuaZIP? + * + * See the NEWS.txt file supplied with the distribution. + * + * \section Requirements + * + * Just <a href="http://www.zlib.org/">zlib</a> and Qt 4/5. Well, Qt 4 + * depends on zlib anyway, but you will need zlib headers to compile + * QuaZIP. With Qt5 sometimes you need the zlib library as well (on + * Windows, for example). + * + * \section building Building, testing and installing + * + * \note Instructions given in this section assume that you are + * using some UNIX dialect, but the build process should be very similar + * on win32-g++ platform too. On other platforms it's essentially the + * same process, maybe with some qmake adjustments not specific to + * QuaZIP itself. + * + * To build the library, run: +\verbatim +$ cd /wherever/quazip/source/is/quazip-x.y.z/quazip +$ qmake [PREFIX=where-to-install] +$ make +\endverbatim + * + * Make sure that you have Qt 4/5 installed with all required headers and + * utilities (that is, including the 'dev' or 'devel' package on Linux) + * and that you run qmake utility of the Qt 4, not some other version + * you may have already installed (you may need to type full path to + * qmake like /usr/local/qt4/bin/qmake). + * + * To reconfigure (with another PREFIX, for example), just run qmake + * with appropriate arguments again. + * + * If you need to specify additional include path or libraries, use + * qmake features (see qmake reference in the Qt documentation). For + * example: + * +\verbatim +$ qmake LIBS+=-L/usr/local/zlib/lib INCLUDEPATH+=/usr/local/zlib/include +\endverbatim + * (note abscence of "-I" before the include path and the presence of "-L" + * before the lib path) + * + * Also note that you may or may not need to define ZLIB_WINAPI (qmake + * DEFINES+=ZLIB_WINAPI) when linking to zlib on Windows, depending on + * how zlib was built (generally, if using zlibwapi.dll, this define is + * needed). + * + * To install compiled library: +\verbatim +$ make install +\endverbatim + * + * By default, QuaZIP compiles as a DLL/SO, but you have other + * options: + * - Just copy appropriate source files to your project and use them, + * but you need to define QUAZIP_STATIC before including any QuaZIP + * headers (best done as a compiler option). This will save you from + * possible side effects of importing/exporting QuaZIP symbols. + * - Compile it as a static library using CONFIG += staticlib qmake + * option. QUAZIP_STATIC is defined automatically by qmake in this case. + * + * Binary compatibility is guaranteed between minor releases starting + * with version 0.5, thanks to the Pimpl idiom. That is, the next binary + * incompatible version will be 1.x. + * + * \section test Testing + * + * To check if QuaZIP's basic features work OK on your platform, you may + * wish to compile the test suite provided in test directory: +\verbatim +$ cd /wherever/quazip/source/is/quazip-x.y.z/qztest +$ qmake +$ make +$ ./qztest +\endverbatim + * + * Note that the test suite looks for the quazip library in the "quazip" + * folder of the project ("../quazip"), but you may wish to use LIBS + * for some systems (Windows often puts the library in the separate + * "debug" or "release" directory). If you wish to use the quazip + * version that's already installed, provide the appropriate path. + * + * On some systems you may need to set PATH, LD_LIBRARY_PATH or + * SHLIB_PATH to get "qztest" to actually run. + * + * If everything went fine, the test suite should report a lot of PASS + * messages. If something goes wrong, it will provide details and a + * warning that some tests failed. + * + * \section using Using + * + * See \ref usage "usage page". + * + * \section contacts Authors and contacts + * + * This wrapper has been written by Sergey A. Tachenov, AKA Alqualos. + * This is my first open source project, so it may suck, but I did not + * find anything like that, so I just had no other choice but to write + * it. + * + * If you have anything to say to me about QuaZIP library, feel free to + * do so (read the \ref faq first, though). I can not promise, + * though, that I fix all the bugs you report in, add any features you + * want, or respond to your critics, or respond to your feedback at all. + * I may be busy, I may be tired of working on QuaZIP, I may be even + * dead already (you never know...). + * + * To report bugs or to post ideas about what should be done, use + * SourceForge.net's <a + * href="http://sourceforge.net/tracker/?group_id=142688">trackers</a>. + * If you want to send me a private message, use my e-mail address + * stachenov@gmail.com. + * + * Do not use e-mail to report bugs, please. Reporting bugs and problems + * with the SourceForge.net's bug report system has that advantage that + * it is visible to public, and I can always search for open tickets + * that were created long ago. It is highly unlikely that I will search + * my mail for that kind of stuff, so if a bug reported by mail isn't + * fixed immediately, it will likely be forgotten forever. + * + * Copyright (C) 2005-2014 Sergey A. Tachenov and contributors + **/ diff --git a/daemon/quazip/doc/usage.dox b/daemon/quazip/doc/usage.dox new file mode 100644 index 0000000..108f6cb --- /dev/null +++ b/daemon/quazip/doc/usage.dox @@ -0,0 +1,77 @@ +/** \page usage Usage + * + * This page provides general information on QuaZIP usage. See classes + * QuaZip and QuaZipFile 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. + * + * QuaZip is a class representing ZIP archive, QuaZipFile represents a + * file inside archive and subclasses QIODevice as well. One limitation + * is that there can be only one instance of QuaZipFile per QuaZip + * 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 Terminology + * + * "QuaZIP" means whole this library, while "QuaZip" (note the + * lower case) is just one class in it. + * + * "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 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. + * + * "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 QIODevice (say, QBuffer, but not + * QTcpSocket). + * + * "A file inside archive", "a file inside ZIP" or something like that + * means file either being read or written from/to some ZIP archive. + * + * \section error-handling 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 "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 (QuaZip) 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: + * + * - Both QuaZip and QuaZipFile 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 + * \c const and do not access ZIP archive in any way. Some, on the + * other hand, \em do access ZIP archive, but do not reset or set + * error code. For example, QuaZipFile::pos() function. Such functions + * are explicitly marked in the documentation. + * - Most functions have their own way to report errors, by returning a + * null string, negative value or \c false. 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. + * - If the function returns error-stating value (like \c 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. + * + * I know that this is somewhat messy, but I could not find a better way + * to do all the error handling. + **/ |