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