misc/quazip/doc/usage.dox
author nemo
Mon, 04 Jun 2012 19:36:55 -0400
changeset 7181 0791c1f2734c
parent 5752 ea95ee97c805
permissions -rw-r--r--
Welp. We have a bit of a problem here. Reverting the move of nextturn. But this causes a desync in scripting unless we can find a better fix.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5752
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     1
/** \page usage Usage
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     2
 * 
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     3
 * This page provides general information on QuaZIP usage. See classes
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     4
 * QuaZip and QuaZipFile for the detailed documentation on what can
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     5
 * QuaZIP do and what can not. Also, reading comments in the zip.h and
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     6
 * unzip.h files (taken from the original ZIP/UNZIP package) is always a
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     7
 * good idea too. After all, QuaZIP is just a wrapper with a few
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     8
 * convenience extensions and reimplementations.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
     9
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    10
 * QuaZip is a class representing ZIP archive, QuaZipFile represents a
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    11
 * file inside archive and subclasses QIODevice as well.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    12
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    13
 * \section terminology Terminology
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    14
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    15
 * "QuaZIP" means whole this library, while "QuaZip" (not case
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    16
 * difference) is just one class in it.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    17
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    18
 * "ZIP/UNZIP API" means the original API of the Gilles Vollant's
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    19
 * ZIP/UNZIP package. I did not alter it in any way to make it easier to
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    20
 * port to the future ZIP/UNZIP versions.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    21
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    22
 * "ZIP", "ZIP archive" or "ZIP file" means any ZIP archive. Typically
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    23
 * this is a plain file with ".zip" (or ".ZIP") file name suffix.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    24
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    25
 * "A file inside archive", "a file inside ZIP" or something like that
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    26
 * means file either being read or written from/to some ZIP archive.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    27
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    28
 * \section error-handling Error handling
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    29
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    30
 * Almost any call to ZIP/UNZIP API return some error code. Most of the
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    31
 * original API's error checking could be done in this wrapper as well,
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    32
 * but it would cause unnecessary code bloating without any benefit. So,
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    33
 * QuaZIP only checks for situations that ZIP/UNZIP API can not check
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    34
 * for. For example, ZIP/UNZIP API has no "ZIP open mode" concept
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    35
 * because read and write modes are completely separated. On the other
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    36
 * hand, to avoid creating classes like "QuaZipReader", "QuaZipWriter"
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    37
 * or something like that, QuaZIP introduces "ZIP open mode" concept
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    38
 * instead, thus making it possible to use one class (QuaZip) for both
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    39
 * reading and writing. But this leads to additional open mode checks
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    40
 * which are not done in ZIP/UNZIP package.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    41
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    42
 * Therefore, error checking is two-level (QuaZIP's level and ZIP/UNZIP
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    43
 * API level), which sometimes can be confusing, so here are some
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    44
 * advices on how the error checking should be properly done:
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    45
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    46
 * - Both QuaZip and QuaZipFile have getZipError() function, which return
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    47
 *   error code of the last ZIP/UNZIP API call. Most function calls
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    48
 *   reset error code to UNZ_OK on success and set error code on
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    49
 *   failure. Some functions do not reset error code. Most of them are
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    50
 *   \c const and do not access ZIP archive in any way. Some, on the
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    51
 *   other hand, \em do access ZIP archive, but do not reset or set
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    52
 *   error code. For example, QuaZipFile::pos() function. Such functions
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    53
 *   are explicitly marked in the documentation.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    54
 * - Most functions have its own way to report errors, by returning a
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    55
 *   null string, negative value or \c false. If such a function returns
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    56
 *   error value, call getZipError() to get more information about
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    57
 *   error. See "zip.h" and "unzip.h" of the ZIP/UNZIP package for error
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    58
 *   codes.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    59
 * - If the function returns error-stating value (like \c false), but
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    60
 *   getZipError() returns UNZ_OK, it means that you did something
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    61
 *   obviously wrong. For example, tried to write in the archive open
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    62
 *   for reading or not open at all. You better just do not do that!
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    63
 *   Most functions also issue a warning using qWarning() function in
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    64
 *   such cases. See documentation for a specific function for details
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    65
 *   on when it should not be called.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    66
 *
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    67
 * I know that this is somewhat messy, but I could not find a better way
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    68
 * to do all the error handling.
ea95ee97c805 Add QuaZIP library to build system
unc0rr
parents:
diff changeset
    69
 **/