summaryrefslogtreecommitdiff
path: root/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-basics.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-basics.htm')
-rw-r--r--Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-basics.htm163
1 files changed, 163 insertions, 0 deletions
diff --git a/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-basics.htm b/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-basics.htm
new file mode 100644
index 00000000000..0d0504710e7
--- /dev/null
+++ b/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-basics.htm
@@ -0,0 +1,163 @@
+<section> <date> 20. July 2002 </date>
+<h2> ZZIP API Basics </h2> The open/close API description.
+
+<!--border-->
+
+<section>
+<h3> Basics </h3>
+
+<P>
+ The naming schem of functions in this library follow a simple rule:
+ if you see a function with a <code>zzip_</code> prefix followed by
+ compact name representing otherwise a C library or posix function then
+ it is a magic wrapper that can automagically handle both real
+ files/directories or zip-contained files. This includes:
+</P>
+<table cellpadding=10 width=100%><tr><td><table width=100% border=1>
+ <tr><td width=50%> zzip_opendir </td><td width=50%> opendir </td></tr>
+ <tr><td width=50%> zzip_readdir </td><td width=50%> readdir </td></tr>
+ <tr><td width=50%> zzip_closedir </td><td width=50%> closedir </td></tr>
+ <tr><td width=50%> zzip_rewinddir </td><td width=50%> rewinddir </td></tr>
+ <tr><td width=50%> zzip_telldir </td><td width=50%> telldir </td></tr>
+ <tr><td width=50%> zzip_seekdir </td><td width=50%> seekdir </td></tr>
+</table></td></tr></table>
+<P>
+ The ZZIP_DIR handle can wrap both a real directory or a zip-file.
+ Note that you can not open a virtual directory <em>within</em> a
+ zip-file, the ZZIP_DIR is either a real DIR-handle of a real
+ directory or the reference of ZIP-file but never a DIR-handle
+ within a ZIP-file - there is no such schema of a SUB-DIR handle
+ implemented in this library. A ZZIP_DIR does actually represent
+ the central directory of a ZIP-file, so that each file entry in
+ this ZZIP-DIR can possibly have a subpath prepended.
+</P>
+
+<P>
+ This form of magic has historic reasons as originally the
+ magic wrappers of this library were not meant to wrap a complete
+ subtree of a real file tree but only a single directory being
+ wrapped with into a zip-file and placed instead. Later proposals
+ and patches were coming in to support subtree wrapping by not
+ only making a split between the dir-part and file-part but
+ going recursivly up through all "/"-dirseparators of a filepath
+ given to <code>zzip_open</code> and looking for zip-file there.
+</P>
+
+<P>
+ To open a zip-file unconditionally one should be using their
+ respective methods that would return a ZZIP_DIR handle being
+ the representant memory instance of a ZIP-DIR, the central
+ directory of a zip-file. From that ZZIP-DIR one can open a
+ compressed file entry which will be returned as a ZZIP_FILE
+ pointer.
+</P>
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_dir_open </td>
+ <td width=50%> open a zip-file and parse the central directory
+ to a memory shadow</td></tr>
+ <tr><td width=50%> zzip_dir_close </td>
+ <td width=50%> close a zip-file and free the memory shadow</td></tr>
+ <tr><td width=50%> zzip_dir_fdopen </td>
+ <td width=50%> aquire the given posix-file and try to parse it
+ as a zip-file.</td></tr>
+ <tr><td width=50%> zzip_dir_read </td>
+ <td width=50%> return the next info entry of a zip-file's central
+ directory - this would include a possible subpath </td></tr>
+</table></td></tr></table>
+
+<P>
+ To unconditionally access a zipped-file (as the counter-part of a
+ zip-file's directory) you should be using the functions having a
+ <code>zzip_file_</code> prefix which are the methods working on
+ ZZIP_FILE pointers directly and assuming those are references of
+ a zipped file with a ZZIP_DIR.
+</P>
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_file_open </td>
+ <td width=50%> open a file within a zip and prepare a zlib
+ compressor for it - note the ZZIP_DIR argument,
+ multiple ZZIP_FILE's may share the same central
+ directory shadow.</td></tr>
+ <tr><td width=50%> zzip_file_close </td>
+ <td width=50%> close the handle of zippedfile
+ and free zlib compressor of it</td></tr>
+ <tr><td width=50%> zzip_file_read </td>
+ <td width=50%> decompress the next part of a compressed file
+ within a zip-file</td></tr>
+</table></td></tr></table>
+<P>
+ From here it is only a short step to the magic wrappers for
+ file-access - when being given a filepath to zzip_open then
+ the filepath is checked first for being possibly a real file
+ (we can often do that by a <code>stat</code> call) and if there is
+ a real file under that name then the returned ZZIP_FILE is
+ nothing more than a wrapper around a file-descriptor of the
+ underlying operating system. Any other calls like zzip_read
+ will see the realfd-flag in the ZZIP_FILE and forward the
+ execution to the read() function of the underlying operating system.
+</P>
+
+<P>
+ However if that fails then the filepath is cut at last directory
+ separator, i.e. a filepath of "this/test/README" is cut into the
+ dir-part "this/test" and a file-part "README". Then the possible
+ zip-extensions are attached (".zip" and ".ZIP") and we check if
+ there is a real file under that name. If a file "this/test.zip"
+ does exist then it is given to zzip_dir_open which will create
+ a ZZIP_DIR instance of it, and when that was successul (so it
+ was in zip-format) then we call zzip_file_open which will see
+ two arguments - the just opened ZZIP_DIR and the file-part. The
+ resulting ZZIP_FILE has its own copy of a ZZIP_DIR, so if you
+ open multiple files from the same zip-file than you will also
+ have multiple in-memory copies of the zip's central directory
+ whereas otherwise multiple ZZIP_FILE's may share a common
+ ZZIP_DIR when being opened with zzip_file_open directly - the
+ zzip_file_open's first argument is the ZZIP_DIR and the second
+ one the file-part to be looked up within that zip-directory.
+</P>
+
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_open </td>
+ <td width=50%> try the file-path as a real-file, and if not
+ there, look for the existance of ZZIP_DIR by
+ applying extensions, and open the file
+ contained within that one.</td></tr>
+ <tr><td width=50%> zzip_close </td>
+ <td width=50%> if the ZZIP_FILE wraps a real-file, then call
+ read(), otherwise call zzip_file_read() </td></tr>
+ <tr><td width=50%> zzip_close </td>
+ <td width=50%> if the ZZIP_FILE wraps a real-file, then call
+ close(), otherwise call zzip_file_close() </td></tr>
+</table></td></tr></table>
+
+<P>
+ Up to here we have the original functionality of the zziplib
+ when I (Guido Draheim) created the magic functions around the work from
+ Tomi Ollila who wrote the routines to read and decompress files from
+ a zip archive - unlike other libraries it was quite readable and
+ intelligible source code (after many changes there is not much
+ left of the original zip08x source code but that's another story).
+ Later however some request and proposals and patches were coming in.
+</P>
+
+<P>
+ Among the first extensions was the recursive zzip_open magic. In
+ the first instance, the library did just do as described above:
+ a file-path of "this/test/README" might be a zip-file known as
+ "this/test.zip" containing a compressed file "README". But if
+ there is neither a real file "this/test/README" and no real
+ zip-file "this/test.zip" then the call would have failed but
+ know the zzip_open call will recursivly check the parent
+ directories - so it can now find a zip-file "this.zip" which
+ contains a file-part "test/README".
+</P>
+
+<P>
+ This dissolves the original meaning of a ZZIP_DIR and it has lead
+ to some confusion later on - you can not create a DIRENT-like handle
+ for "this/test/" being within a "test.zip" file. And actually, I did
+ never see a reason to implement it so far (open "this.zip" and set
+ an initial subpath of "test" and let zzip_readdir skip all entries
+ that do not start with "test/"). This is left for excercie ;-)
+</P>
+</section></section>