diff options
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-0.13.59/docs/zzip-basics.htm')
-rw-r--r-- | Build/source/libs/zziplib/zziplib-0.13.59/docs/zzip-basics.htm | 163 |
1 files changed, 0 insertions, 163 deletions
diff --git a/Build/source/libs/zziplib/zziplib-0.13.59/docs/zzip-basics.htm b/Build/source/libs/zziplib/zziplib-0.13.59/docs/zzip-basics.htm deleted file mode 100644 index 0d0504710e7..00000000000 --- a/Build/source/libs/zziplib/zziplib-0.13.59/docs/zzip-basics.htm +++ /dev/null @@ -1,163 +0,0 @@ -<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> |