misc/quazip/doc/usage.dox
changeset 5752 ea95ee97c805
equal deleted inserted replaced
5750:6bbf7aee2cdf 5752:ea95ee97c805
       
     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  **/