diff options
Diffstat (limited to 'Build/source/texk/web2c/luatexdir/zziplib/docs/zzip-extio.htm')
-rw-r--r-- | Build/source/texk/web2c/luatexdir/zziplib/docs/zzip-extio.htm | 188 |
1 files changed, 0 insertions, 188 deletions
diff --git a/Build/source/texk/web2c/luatexdir/zziplib/docs/zzip-extio.htm b/Build/source/texk/web2c/luatexdir/zziplib/docs/zzip-extio.htm deleted file mode 100644 index c7c47f1a37d..00000000000 --- a/Build/source/texk/web2c/luatexdir/zziplib/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 < 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> |