summaryrefslogtreecommitdiff
path: root/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extras.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extras.htm')
-rw-r--r--Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extras.htm164
1 files changed, 164 insertions, 0 deletions
diff --git a/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extras.htm b/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extras.htm
new file mode 100644
index 00000000000..1d771160cb9
--- /dev/null
+++ b/Build/source/libs/zziplib/zziplib-0.13.62/docs/zzip-extras.htm
@@ -0,0 +1,164 @@
+<section><date> 20. July 2002 </date>
+<h2> ZZIP API extras </h2> The check/init API description.
+
+<!--border-->
+
+<section>
+<h3> Extras </h3>
+
+<P>
+ The next requests circulated around other file-extensions to
+ automagically look inside filetypes that have zip-format too but
+ carry other fileextensions - most famous might be the ".PK3"
+ files of ID's Quake game. There have been a number of these
+ requests and in a lot of cases it dawned to me that those guys
+ may have overlooked the zzip_dir_open functions to travel
+ through documents of zipformat under any name - that is that the
+ "magic" was not actually needed but they just wanted to read
+ files in zipformat with the zziplib.
+</P>
+
+<P>
+ Other requests circulated around encryption but I did reject
+ those bluntly, always. Instead there have been always examples
+ for doing some obfuscation around the zip-format so that the
+ stock zip/unzip tools do not recognize them but a game
+ software developer can pack/unpack his AI scripts and bitmaps
+ into such a zipformat-like file.
+</P>
+
+<P>
+ After some dead-end patches (being shipped along with the
+ zziplib as configure-time compile-options - greetings to
+ Lutz Sammer and Andreas Schiffler), the general approach
+ of _ext_io came up, and finally implemented (greetings go
+ to Mike Nordell). The _open()-calls do now each have a
+ cousin of _open_ext_io() with two/three additional arguments
+ being a set of extensions to loop through our magic testing,
+ a callback-handler plugin-table for obfuscation-means,
+ and (often) a bit-mask for extra-options - this bitmask even
+ has "PREFERZIP" and "ONLYZIP" options to skip the real-file
+ test magic in those <code>zzip_*open</code> functions.
+</P>
+
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_open(name,flags) </td>
+ <td width=50%> zzip_open_ext_io(name,flags,mode,ext,io) </td></tr>
+ <tr><td width=50%> zzip_opendir(name) </td>
+ <td width=50%> zzip_opendir_ext_io(name,mode,ext,io) </td></tr>
+ <tr><td width=50%> zzip_dir_open(name,errp) </td>
+ <td width=50%> zzip_dir_open_ext_io(name,errp,ext,io) </td></tr>
+ <tr><td width=50%> zzip_dir_fdopen(fd,errp) </td>
+ <td width=50%> zzip_dir_fdopen_ext_io(fd,errp,ext,io) </td></tr>
+ <tr><td width=50%> zzip_file_open(dir,name,mode) </td>
+ <td width=50%> zzip_file_open_ext_io(dir,name,mode,ext,io) </td></tr>
+</table></td></tr></table>
+
+<P>
+ Oh, and note that the mode,ext,io extras are memorized
+ in the respecitive ZZIP_DIR handle attached, so each
+ of the other calls like <code>zzip_file_open()</code>
+ and <code>zzip_read()</code> will be using them. There
+ are a few helper routines to help setup a new io-plugin
+ where the init_io will currently just memcopy the
+ default_io entries into the user-supplied plugin-struct.
+</P>
+
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_init_io </td>
+ <td width=50%> the recommended way to do things </td></tr>
+ <tr><td width=50%> zzip_get_default_io </td>
+ <td width=50%> used internally whenever you supply a null
+ for the io-argument of a _ext_io()-call </td></tr>
+ <tr><td width=50%> zzip_get_default_ext </td>
+ <td width=50%> used internally but not exported </td></tr>
+</table></td></tr></table>
+
+
+<P>
+ And last some stdio-like replacements were build but these
+ happen to be actually just small wrappers around the other
+ posix-like magic-calls. It just offers some convenience
+ since wrappers like "SDL_rwops" tend to use a stringised
+ open-mode - and I took the occasion to fold the zzip-bits
+ for the _ext_io-calls right in there recognized via
+ special extensions to the openmode-string of zzip_fopen().
+</P>
+
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_fopen </td>
+ <td width=50%> convert stringmode and call zzip_open_ext_io </td></tr>
+ <tr><td width=50%> zzip_fread </td>
+ <td width=50%> slower way to say zzip_read </td></tr>
+ <tr><td width=50%> zzip_fclose </td>
+ <td width=50%> a synonym of zzip_close </td></tr>
+</table></td></tr></table>
+
+<P>
+ For some reason, people did need the full set of function-calls()
+ to be working on zzip-wrappers too, so here they are - if the
+ ZZIP_FILE instance did wrap a real file, then the real posix-call
+ will be used, otherwise it is simulated on the compressed stream
+ with a zip-contained file - especially <code>seek()</code> can be
+ a slow operation:
+ if the new point is later then just read out more bytes till we
+ hit that position but if it is an earlier point then rewind to the
+ beginning of the compressed data and start reading/decompression
+ until the position is met.
+</P>
+
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_rewind </td>
+ <td width=50%> magic for rewind() </td></tr>
+ <tr><td width=50%> zzip_tell </td>
+ <td width=50%> magic for tell() </td></tr>
+ <tr><td width=50%> zzip_seek </td>
+ <td width=50%> magic for seek() </td></tr>
+</table></td></tr></table>
+
+<P>
+ And last not least, there are few informative functions to
+ use function-calls to read parts of the opaque structures
+ of zzip-objects and their zzip-factory.
+</P>
+
+<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
+ <tr><td width=50%> zzip_dir_stat </td>
+ <td width=50%> a stat()-like thing on a file within a ZZIP_DIR </td></tr>
+ <tr><td width=50%> zzip_dir_real </td>
+ <td width=50%> check if ZZIP_DIR wraps a stat'able posix-dirent</td></tr>
+ <tr><td width=50%> zzip_file_real </td>
+ <td width=50%> check if ZZIP_FILE wraps a stat'able posix-file </td></tr>
+ <tr><td width=50%> zzip_realdir </td>
+ <td width=50%> if zzip_dir_real then return the posix-dirent </td></tr>
+ <tr><td width=50%> zzip_realfd </td>
+ <td width=50%> if zzip_file_real then return the posix-file </td></tr>
+ <tr><td width=50%> zzip_dirhandle </td>
+ <td width=50%> the attached ZZIP_DIR of compressed ZZIP_FILE </td></tr>
+ <tr><td width=50%> zzip_dirfd </td>
+ <td width=50%> the attached posix-file of ZZIP_DIR zip-file </td></tr>
+ <tr><td width=50%> zzip_set_error </td>
+ <td width=50%> set the last ZZIP_DIR error-code </td></tr>
+ <tr><td width=50%> zzip_error </td>
+ <td width=50%> get the last ZZIP_DIR error-code </td></tr>
+ <tr><td width=50%> zzip_strerror </td>
+ <td width=50%> convert a zzip_error into a readable string </td></tr>
+ <tr><td width=50%> zzip_strerror_of </td>
+ <td width=50%> combine both above zzip_strerror of zzip_error </td></tr>
+ <tr><td width=50%> zzip_errno </td>
+ <td width=50%> helper to wrap a zzip-error to a posix-errno </td></tr>
+ <tr><td width=50%> zzip_compr_str </td>
+ <td width=50%> helper to wrap a compr-number to a readable string
+ </td></tr>
+ <tr><td width=50%> zzip_dir_free </td>
+ <td width=50%> internally called by zzip_dir_close if the ref-count
+ of the ZZIP_DIR has gone zero</td></tr>
+ <tr><td width=50%> zzip_freopen </td>
+ <td width=50%> to reuse the ZZIP_DIR from another ZZIP_FILE so it does
+ not need to be parsed again </td></tr>
+ <tr><td width=50%> zzip_open_shared_io </td>
+ <td width=50%> the ext/io cousin but it does not close the old ZZIP_FILE
+ and instead just shares the ZZIP_DIR if possible</td></tr>
+</table></td></tr></table>
+
+</section></section>