diff options
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-src/docs/zzip-extio.htm')
| -rw-r--r-- | Build/source/libs/zziplib/zziplib-src/docs/zzip-extio.htm | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/Build/source/libs/zziplib/zziplib-src/docs/zzip-extio.htm b/Build/source/libs/zziplib/zziplib-src/docs/zzip-extio.htm new file mode 100644 index 00000000000..c7c47f1a37d --- /dev/null +++ b/Build/source/libs/zziplib/zziplib-src/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 < fread (buffer, 1, buflen, file))) + while (0 < 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 (& 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 < 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->io->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> |