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, 0 insertions, 188 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
deleted file mode 100644
index c7c47f1a37d..00000000000
--- a/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extio.htm
+++ /dev/null
@@ -1,188 +0,0 @@
-<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>