20. July 2002
ZZIP API extras
The check/init API description.
Extras
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.
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.
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 zzip_*open functions.
| zzip_open(name,flags) |
zzip_open_ext_io(name,flags,mode,ext,io) |
| zzip_opendir(name) |
zzip_opendir_ext_io(name,mode,ext,io) |
| zzip_dir_open(name,errp) |
zzip_dir_open_ext_io(name,errp,ext,io) |
| zzip_dir_fdopen(fd,errp) |
zzip_dir_fdopen_ext_io(fd,errp,ext,io) |
| zzip_file_open(dir,name,mode) |
zzip_file_open_ext_io(dir,name,mode,ext,io) |
|
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 zzip_file_open()
and zzip_read() 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.
| zzip_init_io |
the recommended way to do things |
| zzip_get_default_io |
used internally whenever you supply a null
for the io-argument of a _ext_io()-call |
| zzip_get_default_ext |
used internally but not exported |
|
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().
| zzip_fopen |
convert stringmode and call zzip_open_ext_io |
| zzip_fread |
slower way to say zzip_read |
| zzip_fclose |
a synonym of zzip_close |
|
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 seek() 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.
| zzip_rewind |
magic for rewind() |
| zzip_tell |
magic for tell() |
| zzip_seek |
magic for seek() |
|
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.
| zzip_dir_stat |
a stat()-like thing on a file within a ZZIP_DIR |
| zzip_dir_real |
check if ZZIP_DIR wraps a stat'able posix-dirent |
| zzip_file_real |
check if ZZIP_FILE wraps a stat'able posix-file |
| zzip_realdir |
if zzip_dir_real then return the posix-dirent |
| zzip_realfd |
if zzip_file_real then return the posix-file |
| zzip_dirhandle |
the attached ZZIP_DIR of compressed ZZIP_FILE |
| zzip_dirfd |
the attached posix-file of ZZIP_DIR zip-file |
| zzip_set_error |
set the last ZZIP_DIR error-code |
| zzip_error |
get the last ZZIP_DIR error-code |
| zzip_strerror |
convert a zzip_error into a readable string |
| zzip_strerror_of |
combine both above zzip_strerror of zzip_error |
| zzip_errno |
helper to wrap a zzip-error to a posix-errno |
| zzip_compr_str |
helper to wrap a compr-number to a readable string
|
| zzip_dir_free |
internally called by zzip_dir_close if the ref-count
of the ZZIP_DIR has gone zero |
| zzip_freopen |
to reuse the ZZIP_DIR from another ZZIP_FILE so it does
not need to be parsed again |
| zzip_open_shared_io |
the ext/io cousin but it does not close the old ZZIP_FILE
and instead just shares the ZZIP_DIR if possible |
|