source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm

   1 <section> <date>15. July 2002 </date>
   2 <h2> ZZIP-EXT/IO </h2>  Customizing the file access
   3
   4 <!--border-->
   5
   6 <section>
   7 <h3> The EXT/IO calls </h3>
   8
   9 <P>
  10   There were quite some requests from game developers and graphics-apps
  11   developers who wanted various extensions to be included into the
  12   <a href="zziplib.html">zziplib library</a>, but most of them were
  13   only of specific usage. After some discussions we came up with a
  14   model to customize the <a href="zziplib.html">zziplib library</a>
  15   calls in a number of ways - and adding two or three arguments to
  16   the zzip_* calls. The standard <a href="zziplib.html">zziplib library</a>
  17   will actually call these *_ext_io functions with these extra arguments
  18   to be set to zero.
  19 </P><P>
  20   The EXT feature describes a way to customize the extensions used in
  21   the magic wrapper to find a .ZIP file. It turned out that there are
  22   quite a number of applications that did chose the zip file format as
  23   their native document format and where just the file extension had
  24   been changed. This includes file types like Quake3 ".PK3" files from
  25   ID Software, the Java library files called ".JAR", and lately the
  26   OpenOffice-6 (resp. StarOffice-6) documents which carry xml-files along.
  27   Just build a zero-termined string-list of file-extensions and submit it
  28   to the _ext_io calls to let the <a href="zziplib.html">zziplib</a> find
  29   parts of those zip-documents automagically.
  30 </P><P>
  31   In quite some of these cases, it is very benefical to make use of the
  32   o_modes functionality that allows to submit extra bit-options into
  33   the <a href="zziplib.html">zziplib</a> - this includes options like
  34   <code>ZZIP_PREFERZIP</code> or even <code>ZZIP_ONLYZIP</code> which
  35   modifies the default behaviour of looking for real files first instead
  36   of some within a zipped directory tree. Other bit-options include
  37   <code>ZZIP_CASELESS</code> to imitate win32-like filematching for a
  38   zipped filetree.
  39 </P><P>
  40   Other wishes on <a href="zziplib.html">zziplib</a> circulated around
  41   <a href="zzip-xor.html">obfuscation</a> or access to zip-files wrapped
  42   in other data areas including encrpyted resources from other applications.
  43   This has been adressed with the IO-handlers that you can explicitly
  44   submit to the *_ext_io functions - the default will be posix-IO
  45   open/read/write and seek/tell. An application using
  46   <a href="zziplib.html">zziplib</a> can divert these to its own set of
  47   these calls - and it only needs to declare them on opening a zipped file.
  48 </P>
  49
  50 </section><section>
  51 <h3> The EXT stringlist </h3>
  52
  53 <P>
  54   Declaring an EXT stringlist is very simple as it is simply a
  55   list of strings, the <a href="zziplib.html">zziplib</a> provides
  56   you with a double-const <code>zzip_strings_t</code> type to help
  57   you move a global declaration into the writeonly segment of your
  58   app - it turned out that about all developers wanted just some
  59   extensions on the default and they were fine with having them
  60   global-const for their application, nothing like dynamically
  61   modifying them. Well, you are still allowed to make it fully
  62   dynamic... if you find a use case for that.
  63 </P><P>
  64   Extending the magic zip-extensions is just done by adding the
  65   additional extensions to be recognized - just remember to add
  66   the uppercased variants too since those will be needed on
  67   (unx-like) filesystems that are case-sensitive. In the internet
  68   age, quite some downloaded will appear in uppercased format since
  69   the other side declared it as that and that other end was happy
  70   with it as being a (w32-like) case-insensitive server. Therefore,
  71   it should look like <pre>
  72      static zzip_strings_t my_ext[] = { ".zip", ".ZIP", ".jar", ".JAR", 0 };
  73   </pre>
  74 </P><P>
  75   There is one frequently asked question in this area - how to open
  76   a zipped file as "test.zip/README" instead of "test/README". Other
  77   than some people might expect, the library will not find it - if
  78   you want to have that one needs a fileext list that contains the
  79   empty string - not the zero string, an empty string that is. It
  80   looks like <pre>
  81      static zzip_strings_t my_ext[] = { ".zip", ".ZIP", "", 0 };
  82   </pre>
  83 </P><P>
  84   And last not least, people want to tell the libary to not try to
  85   open a real file that lives side by side with the same path as the
  86   file path that can be matched by the zziplib. Actually, the magic
  87   wrappers were never meant to be used like - the developer should
  88   have used zzip_dir_* functions to open a zip-file and the
  89   zzip_file_* functions to read entries from that zip-file. However,
  90   the magic-wrappers look rather more familiar, and so you will find
  91   now a bit-option ZZIP_ONLYZIP that can be passed down to the _ext_io
  92   variants of the magic-wrapper calls, and a real-file will never get
  93   tested for existance. Actually, I would rather recommend that for
  94   application data the option ZZIP_PREFERZIP, so that one can enter
  95   debugging mode by unpacking the zip-file as a real directory tree
  96   in the place of the original zip.
  97 </P>
  98
  99 </section><section>
 100 <h3> The IO handlers </h3>
 101
 102 <P>
 103   While you will find the zzip_plugin_io_t declared in the zziplib
 104   headers, you are not advised to make much assumptions about their
 105   structure. Still we gone the path of simplicity, so you can use
 106   a global static for this struct too just like one can do for the
 107   EXT-list. This again mimics the internals of zziplib. There is
 108   even a helper function zzip_init_io that will copy the zziplib
 109   internal handlers to your own handlers-set. Actually, this is
 110   barely needed since the zziplib library will not check for nulls
 111   in the plugin_io structure, all handlers must be filled, and the
 112   zziplib routines call them unconditionally - that's simply
 113   because a conditional-call will be ten times slower than an
 114   unconditional call which adds mostly just one or two cpu cycles
 115   in the place so you won't ever notice zziplib to be anywhat
 116   slower than before adding IO-handlers.
 117 </P><P>
 118   However, you better instantiate your handlers in your application
 119   and call that zzip_init_io on that instance to have everything
 120   filled, only then modify the entry you actually wish to have
 121   modified. For <a href="zzip-xor.html">obfuscation</a> this
 122   will mostly be just the <code>read()</code> routine. But one can
 123   also use IO-handlers to wrap zip-files into another data part
 124   for which one (also) wants to modify the open/close routines
 125   as well.
 126 </P><P>
 127   Therefore, you can modify your normal stdio code to start using
 128   zipped files by exchaning the fopen/fread/fclose calls by their
 129   magic counterparts, i.e. <pre>
 130     // FILE* file = fopen ("test/README", "rb");
 131     ZZIP_FILE* file = zzip_fopen ("test/README", "rb");
 132     // while (0 &lt; fread (buffer, 1, buflen, file)))
 133     while (0 &lt; zzip_fread (buffer, 1, buflen, file)))
 134        { do something }
 135     // fclose (file);
 136     zzip_fclose (file);
 137   </pre>
 138 </P><P>
 139    and you then need to prefix this code with some additional
 140    code to support your own EXT/IO set, so the code will finally
 141    look like <pre>
 142     /* use .DAT extension to find some files */
 143     static zzip_strings_t ext[] = { ".dat", ".DAT", "", 0 };
 144     /* add obfuscation routine - see zzxorcat.c examples */
 145     static zzip_plugin_io_t io;
 146     zzip_init_io (&amp; io, 0);
 147     io.read = xor_read;
 148     /* and the rest of the code, just as above, but with ext/io */
 149     ZZIP_FILE* file = zzip_open_ext_io ("test/README", O_RDONLY|O_BINARY,
 150                                         ZZIP_ONLYZIP|ZZIP_CASELESS, ext, io);
 151     while (0 &lt; zzip_fread (buffer, 1, buflen, file)))
 152         { do something }
 153     zzip_fclose (file);
 154   </pre>
 155 </P>
 156
 157 </section><section>
 158 <h3> Finally </h3>
 159
 160 <P>
 161    What's more to it? Well, if you have some ideas then please mail me
 162    about it - don't worry, I'll probably reject it to be part of the
 163    standard zziplib dll, but perhaps it is worth to be added as a
 164    configure option and can help others later, and even more perhaps
 165    it can be somehow generalized just as the ext/io features have been
 166    generalized now. In most respects, this ext/io did not add much
 167    code to the <a href="zziplib.html">zziplib</a> - the posix-calls
 168    in the implemenation, like <code>"read(file)"</code> were simply
 169    exchanged with <code>"zip-&gt;io-&gt;read(file)"</code>, and the
 170    old <code>"zzip_open(name,mode)"</code> call is split up - the old
 171    entry still persists but directly calls
 172    <code>"zzip_open_ext_io(name,mode,0,0,0)"</code> which has the
 173    old implementation code with just one addition: when the ZIP_FILE
 174    handle is created, it uses the transferred io-handlers (or the
 175    default ones if io==0), and initialized the io-member of that
 176    structure for usage within the <code>zzip_read</code> calls.
 177 </P><P>
 178    This adds just a few bytes to the libs and just consumes additional
 179    cpu cycles that can be rightfully called to be negligable (unlike
 180    most commerical vendors will tell you when they indeed want to
 181    tell you that for soooo many new features you have to pay a price).
 182    It makes for greater variability without adding fatness to the
 183    core in the default case, this is truly efficient I'd say. Well,
 184    call this a German desease :-)=) ... and again, if you have another
 185    idea, write today... or next week.
 186 </P>
 187
 188 </section></section>