granicus.if.org Git - zziplib/blob - docs/zzip-basics.htm

   1 <section> <date> 20. July 2002 </date>
   2 <h2> ZZIP API Basics </h2>              The open/close API description.
   3
   4 <!--border-->
   5
   6 <section>
   7 <h3> Basics </h3>
   8
   9 <P>
  10   The naming schem of functions in this library follow a simple rule:
  11   if you see a function with a <code>zzip_</code> prefix followed by
  12   compact name representing otherwise a C library or posix function then
  13   it is a magic wrapper that can automagically handle both real
  14   files/directories or zip-contained files. This includes:
  15 </P>
  16 <table cellpadding=10 width=100%><tr><td><table width=100% border=1>
  17   <tr><td width=50%> zzip_opendir   </td><td width=50%> opendir </td></tr>
  18   <tr><td width=50%> zzip_readdir   </td><td width=50%> readdir </td></tr>
  19   <tr><td width=50%> zzip_closedir  </td><td width=50%> closedir </td></tr>
  20   <tr><td width=50%> zzip_rewinddir </td><td width=50%> rewinddir </td></tr>
  21   <tr><td width=50%> zzip_telldir   </td><td width=50%> telldir </td></tr>
  22   <tr><td width=50%> zzip_seekdir   </td><td width=50%> seekdir </td></tr>
  23 </table></td></tr></table>
  24 <P>
  25   The ZZIP_DIR handle can wrap both a real directory or a zip-file.
  26   Note that you can not open a virtual directory <em>within</em> a
  27   zip-file, the ZZIP_DIR is either a real DIR-handle of a real
  28   directory or the reference of ZIP-file but never a DIR-handle
  29   within a ZIP-file - there is no such schema of a SUB-DIR handle
  30   implemented in this library. A ZZIP_DIR does actually represent
  31   the central directory of a ZIP-file, so that each file entry in
  32   this ZZIP-DIR can possibly have a subpath prepended.
  33 </P>
  34
  35 <P>
  36   This form of magic has historic reasons as originally the
  37   magic wrappers of this library were not meant to wrap a complete
  38   subtree of a real file tree but only a single directory being
  39   wrapped with into a zip-file and placed instead. Later proposals
  40   and patches were coming in to support subtree wrapping by not
  41   only making a split between the dir-part and file-part but
  42   going recursivly up through all "/"-dirseparators of a filepath
  43   given to <code>zzip_open</code> and looking for zip-file there.
  44 </P>
  45
  46 <P>
  47   To open a zip-file unconditionally one should be using their
  48   respective methods that would return a ZZIP_DIR handle being
  49   the representant memory instance of a ZIP-DIR, the central
  50   directory of a zip-file. From that ZZIP-DIR one can open a
  51   compressed file entry which will be returned as a ZZIP_FILE
  52   pointer.
  53 </P>
  54 <table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
  55   <tr><td width=50%> zzip_dir_open  </td>
  56       <td width=50%> open a zip-file and parse the central directory
  57                                               to a memory shadow</td></tr>
  58   <tr><td width=50%> zzip_dir_close  </td>
  59       <td width=50%> close a zip-file and free the memory shadow</td></tr>
  60   <tr><td width=50%> zzip_dir_fdopen  </td>
  61       <td width=50%> aquire the given posix-file and try to parse it
  62                                                   as a zip-file.</td></tr>
  63   <tr><td width=50%> zzip_dir_read  </td>
  64       <td width=50%> return the next info entry of a zip-file's central
  65                  directory - this would include a possible subpath </td></tr>
  66 </table></td></tr></table>
  67
  68 <P>
  69   To unconditionally access a zipped-file (as the counter-part of a
  70   zip-file's directory) you should be using the functions having a
  71   <code>zzip_file_</code> prefix which are the methods working on
  72   ZZIP_FILE pointers directly and assuming those are references of
  73   a zipped file with a ZZIP_DIR.
  74 </P>
  75 <table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
  76   <tr><td width=50%> zzip_file_open  </td>
  77       <td width=50%> open a file within a zip and prepare a zlib
  78                      compressor for it - note the ZZIP_DIR argument,
  79                      multiple ZZIP_FILE's may share the same central
  80                      directory shadow.</td></tr>
  81   <tr><td width=50%> zzip_file_close  </td>
  82       <td width=50%> close the handle of zippedfile
  83                      and free zlib compressor of it</td></tr>
  84   <tr><td width=50%> zzip_file_read  </td>
  85       <td width=50%> decompress the next part of a compressed file
  86                      within a zip-file</td></tr>
  87 </table></td></tr></table>
  88 <P>
  89   From here it is only a short step to the magic wrappers for
  90   file-access - when being given a filepath to zzip_open then
  91   the filepath is checked first for being possibly a real file
  92   (we can often do that by a <code>stat</code> call) and if there is
  93   a real file under that name then the returned ZZIP_FILE is
  94   nothing more than a wrapper around a file-descriptor of the
  95   underlying operating system. Any other calls like zzip_read
  96   will see the realfd-flag in the ZZIP_FILE and forward the
  97   execution to the read() function of the underlying operating system.
  98 </P>
  99
 100 <P>
 101   However if that fails then the filepath is cut at last directory
 102   separator, i.e. a filepath of "this/test/README" is cut into the
 103   dir-part "this/test" and a file-part "README". Then the possible
 104   zip-extensions are attached (".zip" and ".ZIP") and we check if
 105   there is a real file under that name. If a file "this/test.zip"
 106   does exist then it is given to zzip_dir_open which will create
 107   a ZZIP_DIR instance of it, and when that was successul (so it
 108   was in zip-format) then we call zzip_file_open which will see
 109   two arguments - the just opened ZZIP_DIR and the file-part. The
 110   resulting ZZIP_FILE has its own copy of a ZZIP_DIR, so if you
 111   open multiple files from the same zip-file than you will also
 112   have multiple in-memory copies of the zip's central directory
 113   whereas otherwise multiple ZZIP_FILE's may share a common
 114   ZZIP_DIR when being opened with zzip_file_open directly - the
 115   zzip_file_open's first argument is the ZZIP_DIR and the second
 116   one the file-part to be looked up within that zip-directory.
 117 </P>
 118
 119 <table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
 120   <tr><td width=50%> zzip_open  </td>
 121       <td width=50%> try the file-path as a real-file, and if not
 122                      there, look for the existance of ZZIP_DIR by
 123                      applying extensions, and open the file
 124                      contained within that one.</td></tr>
 125   <tr><td width=50%> zzip_close  </td>
 126       <td width=50%> if the ZZIP_FILE wraps a real-file, then call
 127                      read(), otherwise call zzip_file_read() </td></tr>
 128   <tr><td width=50%> zzip_close  </td>
 129       <td width=50%> if the ZZIP_FILE wraps a real-file, then call
 130                      close(), otherwise call zzip_file_close() </td></tr>
 131 </table></td></tr></table>
 132
 133 <P>
 134   Up to here we have the original functionality of the zziplib
 135   when I (Guido Draheim) created the magic functions around the work from
 136   Tomi Ollila who wrote the routines to read and decompress files from
 137   a zip archive - unlike other libraries it was quite readable and
 138   intelligible source code (after many changes there is not much
 139   left of the original zip08x source code but that's another story).
 140   Later however some request and proposals and patches were coming in.
 141 </P>
 142
 143 <P>
 144   Among the first extensions was the recursive zzip_open magic. In
 145   the first instance, the library did just do as described above:
 146   a file-path of "this/test/README" might be a zip-file known as
 147   "this/test.zip" containing a compressed file "README". But if
 148   there is neither a real file "this/test/README" and no real
 149   zip-file "this/test.zip" then the call would have failed but
 150   know the zzip_open call will recursivly check the parent
 151   directories - so it can now find a zip-file "this.zip" which
 152   contains a file-part "test/README".
 153 </P>
 154
 155 <P>
 156   This dissolves the original meaning of a ZZIP_DIR and it has lead
 157   to some confusion later on - you can not create a DIRENT-like handle
 158   for "this/test/" being within a "test.zip" file. And actually, I did
 159   never see a reason to implement it so far (open "this.zip" and set
 160   an initial subpath of "test" and let zzip_readdir skip all entries
 161   that do not start with "test/"). This is left for excercie ;-)
 162 </P>
 163 </section></section>