summaryrefslogtreecommitdiff
path: root/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm')
-rw-r--r--Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm188
1 files changed, 188 insertions, 0 deletions
diff --git a/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm b/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm
new file mode 100644
index 00000000000..c7c47f1a37d
--- /dev/null
+++ b/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm
@@ -0,0 +1,188 @@
+<section> <date>15. July 2002 </date>
+<h2> ZZIP-EXT/IO </h2> Customizing the file access
+
+<!--border-->
+
+<section>
+<h3> The EXT/IO calls </h3>
+
+<P>
+ There were quite some requests from game developers and graphics-apps
+ developers who wanted various extensions to be included into the
+ <a href="zziplib.html">zziplib library</a>, but most of them were
+ only of specific usage. After some discussions we came up with a
+ model to customize the <a href="zziplib.html">zziplib library</a>
+ calls in a number of ways - and adding two or three arguments to
+ the zzip_* calls. The standard <a href="zziplib.html">zziplib library</a>
+ will actually call these *_ext_io functions with these extra arguments
+ to be set to zero.
+</P><P>
+ The EXT feature describes a way to customize the extensions used in
+ the magic wrapper to find a .ZIP file. It turned out that there are
+ quite a number of applications that did chose the zip file format as
+ their native document format and where just the file extension had
+ been changed. This includes file types like Quake3 ".PK3" files from
+ ID Software, the Java library files called ".JAR", and lately the
+ OpenOffice-6 (resp. StarOffice-6) documents which carry xml-files along.
+ Just build a zero-termined string-list of file-extensions and submit it
+ to the _ext_io calls to let the <a href="zziplib.html">zziplib</a> find
+ parts of those zip-documents automagically.
+</P><P>
+ In quite some of these cases, it is very benefical to make use of the
+ o_modes functionality that allows to submit extra bit-options into
+ the <a href="zziplib.html">zziplib</a> - this includes options like
+ <code>ZZIP_PREFERZIP</code> or even <code>ZZIP_ONLYZIP</code> which
+ modifies the default behaviour of looking for real files first instead
+ of some within a zipped directory tree. Other bit-options include
+ <code>ZZIP_CASELESS</code> to imitate win32-like filematching for a
+ zipped filetree.
+</P><P>
+ Other wishes on <a href="zziplib.html">zziplib</a> circulated around
+ <a href="zzip-xor.html">obfuscation</a> or access to zip-files wrapped
+ in other data areas including encrpyted resources from other applications.
+ This has been adressed with the IO-handlers that you can explicitly
+ submit to the *_ext_io functions - the default will be posix-IO
+ open/read/write and seek/tell. An application using
+ <a href="zziplib.html">zziplib</a> can divert these to its own set of
+ these calls - and it only needs to declare them on opening a zipped file.
+</P>
+
+</section><section>
+<h3> The EXT stringlist </h3>
+
+<P>
+ Declaring an EXT stringlist is very simple as it is simply a
+ list of strings, the <a href="zziplib.html">zziplib</a> provides
+ you with a double-const <code>zzip_strings_t</code> type to help
+ you move a global declaration into the writeonly segment of your
+ app - it turned out that about all developers wanted just some
+ extensions on the default and they were fine with having them
+ global-const for their application, nothing like dynamically
+ modifying them. Well, you are still allowed to make it fully
+ dynamic... if you find a use case for that.
+</P><P>
+ Extending the magic zip-extensions is just done by adding the
+ additional extensions to be recognized - just remember to add
+ the uppercased variants too since those will be needed on
+ (unx-like) filesystems that are case-sensitive. In the internet
+ age, quite some downloaded will appear in uppercased format since
+ the other side declared it as that and that other end was happy
+ with it as being a (w32-like) case-insensitive server. Therefore,
+ it should look like <pre>
+ static zzip_strings_t my_ext[] = { ".zip", ".ZIP", ".jar", ".JAR", 0 };
+ </pre>
+</P><P>
+ There is one frequently asked question in this area - how to open
+ a zipped file as "test.zip/README" instead of "test/README". Other
+ than some people might expect, the library will not find it - if
+ you want to have that one needs a fileext list that contains the
+ empty string - not the zero string, an empty string that is. It
+ looks like <pre>
+ static zzip_strings_t my_ext[] = { ".zip", ".ZIP", "", 0 };
+ </pre>
+</P><P>
+ And last not least, people want to tell the libary to not try to
+ open a real file that lives side by side with the same path as the
+ file path that can be matched by the zziplib. Actually, the magic
+ wrappers were never meant to be used like - the developer should
+ have used zzip_dir_* functions to open a zip-file and the
+ zzip_file_* functions to read entries from that zip-file. However,
+ the magic-wrappers look rather more familiar, and so you will find
+ now a bit-option ZZIP_ONLYZIP that can be passed down to the _ext_io
+ variants of the magic-wrapper calls, and a real-file will never get
+ tested for existance. Actually, I would rather recommend that for
+ application data the option ZZIP_PREFERZIP, so that one can enter
+ debugging mode by unpacking the zip-file as a real directory tree
+ in the place of the original zip.
+</P>
+
+</section><section>
+<h3> The IO handlers </h3>
+
+<P>
+ While you will find the zzip_plugin_io_t declared in the zziplib
+ headers, you are not advised to make much assumptions about their
+ structure. Still we gone the path of simplicity, so you can use
+ a global static for this struct too just like one can do for the
+ EXT-list. This again mimics the internals of zziplib. There is
+ even a helper function zzip_init_io that will copy the zziplib
+ internal handlers to your own handlers-set. Actually, this is
+ barely needed since the zziplib library will not check for nulls
+ in the plugin_io structure, all handlers must be filled, and the
+ zziplib routines call them unconditionally - that's simply
+ because a conditional-call will be ten times slower than an
+ unconditional call which adds mostly just one or two cpu cycles
+ in the place so you won't ever notice zziplib to be anywhat
+ slower than before adding IO-handlers.
+</P><P>
+ However, you better instantiate your handlers in your application
+ and call that zzip_init_io on that instance to have everything
+ filled, only then modify the entry you actually wish to have
+ modified. For <a href="zzip-xor.html">obfuscation</a> this
+ will mostly be just the <code>read()</code> routine. But one can
+ also use IO-handlers to wrap zip-files into another data part
+ for which one (also) wants to modify the open/close routines
+ as well.
+</P><P>
+ Therefore, you can modify your normal stdio code to start using
+ zipped files by exchaning the fopen/fread/fclose calls by their
+ magic counterparts, i.e. <pre>
+ // FILE* file = fopen ("test/README", "rb");
+ ZZIP_FILE* file = zzip_fopen ("test/README", "rb");
+ // while (0 &lt; fread (buffer, 1, buflen, file)))
+ while (0 &lt; zzip_fread (buffer, 1, buflen, file)))
+ { do something }
+ // fclose (file);
+ zzip_fclose (file);
+ </pre>
+</P><P>
+ and you then need to prefix this code with some additional
+ code to support your own EXT/IO set, so the code will finally
+ look like <pre>
+ /* use .DAT extension to find some files */
+ static zzip_strings_t ext[] = { ".dat", ".DAT", "", 0 };
+ /* add obfuscation routine - see zzxorcat.c examples */
+ static zzip_plugin_io_t io;
+ zzip_init_io (&amp; io, 0);
+ io.read = xor_read;
+ /* and the rest of the code, just as above, but with ext/io */
+ ZZIP_FILE* file = zzip_open_ext_io ("test/README", O_RDONLY|O_BINARY,
+ ZZIP_ONLYZIP|ZZIP_CASELESS, ext, io);
+ while (0 &lt; zzip_fread (buffer, 1, buflen, file)))
+ { do something }
+ zzip_fclose (file);
+ </pre>
+</P>
+
+</section><section>
+<h3> Finally </h3>
+
+<P>
+ What's more to it? Well, if you have some ideas then please mail me
+ about it - don't worry, I'll probably reject it to be part of the
+ standard zziplib dll, but perhaps it is worth to be added as a
+ configure option and can help others later, and even more perhaps
+ it can be somehow generalized just as the ext/io features have been
+ generalized now. In most respects, this ext/io did not add much
+ code to the <a href="zziplib.html">zziplib</a> - the posix-calls
+ in the implemenation, like <code>"read(file)"</code> were simply
+ exchanged with <code>"zip-&gt;io-&gt;read(file)"</code>, and the
+ old <code>"zzip_open(name,mode)"</code> call is split up - the old
+ entry still persists but directly calls
+ <code>"zzip_open_ext_io(name,mode,0,0,0)"</code> which has the
+ old implementation code with just one addition: when the ZIP_FILE
+ handle is created, it uses the transferred io-handlers (or the
+ default ones if io==0), and initialized the io-member of that
+ structure for usage within the <code>zzip_read</code> calls.
+</P><P>
+ This adds just a few bytes to the libs and just consumes additional
+ cpu cycles that can be rightfully called to be negligable (unlike
+ most commerical vendors will tell you when they indeed want to
+ tell you that for soooo many new features you have to pay a price).
+ It makes for greater variability without adding fatness to the
+ core in the default case, this is truly efficient I'd say. Well,
+ call this a German desease :-)=) ... and again, if you have another
+ idea, write today... or next week.
+</P>
+
+</section></section>