2019-08-27 18:26:00 -07:00
|
|
|
|
/** \page usage Usage
|
|
|
|
|
|
2021-01-23 16:26:28 -08:00
|
|
|
|
This page provides general information on %QuaZip usage. See classes
|
2019-08-27 18:26:00 -07:00
|
|
|
|
QuaZip and QuaZipFile for the detailed documentation on what can
|
2021-01-23 16:26:28 -08:00
|
|
|
|
%QuaZip do and what it can't do. Also, reading comments in the zip.h and
|
2019-08-27 18:26:00 -07:00
|
|
|
|
unzip.h files (taken from the original ZIP/UNZIP package) is always a
|
2021-01-23 16:26:28 -08:00
|
|
|
|
good idea too. After all, %QuaZip is just a wrapper with a few
|
2019-08-27 18:26:00 -07:00
|
|
|
|
convenience extensions and reimplementations.
|
|
|
|
|
|
2021-01-23 16:26:28 -08:00
|
|
|
|
\section CMake
|
|
|
|
|
|
|
|
|
|
To get started, as it is usual with modern CMake, you just need
|
|
|
|
|
something like this in your CMakeLists.txt:
|
|
|
|
|
|
|
|
|
|
\verbatim
|
|
|
|
|
find_package(QuaZip-Qt5)
|
|
|
|
|
target_link_libraries(whatever-your-target-is QuaZip::QuaZip)
|
|
|
|
|
\endverbatim
|
|
|
|
|
|
|
|
|
|
Or, if you prefer to add %QuaZip sources directly to your project
|
|
|
|
|
(e. g. as a Git submodule):
|
|
|
|
|
\verbatim
|
|
|
|
|
add_subdirectory(quazip)
|
|
|
|
|
target_link_libraries(whatever-your-target-is QuaZip::QuaZip)
|
|
|
|
|
\endverbatim
|
|
|
|
|
|
|
|
|
|
In the latter case, you may want to set BUILD_SHARED_LIBS to NO
|
|
|
|
|
to link statically.
|
|
|
|
|
|
|
|
|
|
In all cases, if %QuaZip is linked statically, it automatically
|
|
|
|
|
defines QUAZIP_STATIC whenever your link to it, which disables
|
|
|
|
|
dllimports that would lead to confusing errors (at least on Windows)
|
|
|
|
|
otherwise.
|
|
|
|
|
|
|
|
|
|
If, for some weird reason, you decide to add %QuaZip sources to your
|
|
|
|
|
project directly (skipping CMake), or link it statically and then
|
|
|
|
|
link it to your project without CMake, you may need to define
|
|
|
|
|
QUAZIP_STATIC manually to avoid problems with dllimports.
|
|
|
|
|
|
|
|
|
|
%QuaZip uses SameMajorVersion compatibility mode, so you can have,
|
|
|
|
|
say, %QuaZip 1.x and %QuaZip 2.x (in some future, when there is such a thing)
|
|
|
|
|
installed in parallel, and then pass the required version to
|
|
|
|
|
\c find_package. As long as the major version matches, it will be found.
|
|
|
|
|
|
|
|
|
|
\section Flatpak
|
|
|
|
|
|
|
|
|
|
%Quazip can be used in Flatpak YAML manifests as such:
|
|
|
|
|
|
|
|
|
|
\verbatim
|
|
|
|
|
modules:
|
|
|
|
|
- name: quazip
|
|
|
|
|
buildsystem: cmake-ninja
|
|
|
|
|
builddir: true
|
|
|
|
|
config-opts:
|
|
|
|
|
- -DCMAKE_BUILD_TYPE=MinSizeRel
|
|
|
|
|
sources:
|
|
|
|
|
- type: archive
|
|
|
|
|
url: https://github.com/stachenov/quazip/archive/v1.1.tar.gz
|
|
|
|
|
sha256: 54edce9c11371762bd4f0003c2937b5d8806a2752dd9c0fd9085e90792612ad0
|
|
|
|
|
- type: shell
|
|
|
|
|
commands:
|
|
|
|
|
- sed -i 's|${CMAKE_ROOT}/Modules|share/cmake|' CMakeLists.txt
|
|
|
|
|
\endverbatim
|
|
|
|
|
|
|
|
|
|
or on older JSON manifests:
|
|
|
|
|
\verbatim
|
|
|
|
|
"modules": [
|
|
|
|
|
{
|
|
|
|
|
"name": "quazip",
|
|
|
|
|
"buildsystem": "cmake-ninja",
|
|
|
|
|
"builddir": true,
|
|
|
|
|
"config-opts": [
|
|
|
|
|
"-DCMAKE_BUILD_TYPE=MinSizeRel"
|
|
|
|
|
],
|
|
|
|
|
"sources": [
|
|
|
|
|
{
|
|
|
|
|
"type": "archive",
|
|
|
|
|
"url": "https://github.com/stachenov/quazip/archive/v1.1.tar.gz",
|
|
|
|
|
"sha256": "54edce9c11371762bd4f0003c2937b5d8806a2752dd9c0fd9085e90792612ad0"
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"type": "shell",
|
|
|
|
|
"commands": [
|
|
|
|
|
"sed -i 's|${CMAKE_ROOT}/Modules|share/cmake|' CMakeLists.txt"
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
]
|
|
|
|
|
\endverbatim
|
2019-08-27 18:26:00 -07:00
|
|
|
|
|
|
|
|
|
\section terminology Terminology
|
|
|
|
|
|
2021-01-23 16:26:28 -08:00
|
|
|
|
“%QuaZip” means the whole library or the \c QuaZip class, depending
|
|
|
|
|
on the context.
|
2019-08-27 18:26:00 -07:00
|
|
|
|
|
|
|
|
|
“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
|
2021-01-23 16:26:28 -08:00
|
|
|
|
just drop the newer Minizip version into %QuaZip sources and make it
|
2019-08-27 18:26:00 -07:00
|
|
|
|
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.
|
|
|
|
|
|
2021-01-23 16:26:28 -08:00
|
|
|
|
\section API
|
|
|
|
|
|
|
|
|
|
The main classes are QuaZip and QuaZipFile, and there's JlCompress
|
|
|
|
|
that contains a lot of high-level utility methods (think of it
|
|
|
|
|
as the Facade Pattern for the most common uses).
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
kept for backwards compatibility.
|
|
|
|
|
|
2019-08-27 18:26:00 -07:00
|
|
|
|
\section general-usage General usage
|
|
|
|
|
|
|
|
|
|
In general, the process looks like this:
|
|
|
|
|
|
|
|
|
|
-# Open or create an archive with a QuaZip instance.
|
|
|
|
|
-# Open or create a file in the archive with a QuaZipFile instance.
|
|
|
|
|
-# Perform reading or writing.
|
|
|
|
|
-# Close the QuaZipFile instance.
|
|
|
|
|
-# Repeat steps 2–4 for other files if needed.
|
2021-01-23 16:26:28 -08:00
|
|
|
|
-# Close the QuaZip instance.
|
2019-08-27 18:26:00 -07:00
|
|
|
|
|
|
|
|
|
See the “qztest” subdirectory for examples. TestQuaZipFile::zipUnzip()
|
|
|
|
|
is a good place to start.
|
|
|
|
|
|
|
|
|
|
\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,
|
2021-01-23 16:26:28 -08:00
|
|
|
|
%QuaZip only checks for situations that ZIP/UNZIP API can not check
|
2019-08-27 18:26:00 -07:00
|
|
|
|
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”
|
2021-01-23 16:26:28 -08:00
|
|
|
|
or something like that, %QuaZip introduces “ZIP open mode” concept
|
2019-08-27 18:26:00 -07:00
|
|
|
|
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.
|
|
|
|
|
|
2021-01-23 16:26:28 -08:00
|
|
|
|
Therefore, error checking is two-level (%QuaZip's level and ZIP/UNZIP
|
2019-08-27 18:26:00 -07:00
|
|
|
|
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
|
2021-01-23 16:26:28 -08:00
|
|
|
|
to do all the error handling back in 2005, and it's too late to change
|
|
|
|
|
anything now. A major API redesign is needed, but not planned in any
|
|
|
|
|
foreseeable future yet.
|
2019-08-27 18:26:00 -07:00
|
|
|
|
*/
|