cannam@128: /* blast.h -- interface for blast.c
cannam@128:   Copyright (C) 2003, 2012 Mark Adler
cannam@128:   version 1.2, 24 Oct 2012
cannam@128: 
cannam@128:   This software is provided 'as-is', without any express or implied
cannam@128:   warranty.  In no event will the author be held liable for any damages
cannam@128:   arising from the use of this software.
cannam@128: 
cannam@128:   Permission is granted to anyone to use this software for any purpose,
cannam@128:   including commercial applications, and to alter it and redistribute it
cannam@128:   freely, subject to the following restrictions:
cannam@128: 
cannam@128:   1. The origin of this software must not be misrepresented; you must not
cannam@128:      claim that you wrote the original software. If you use this software
cannam@128:      in a product, an acknowledgment in the product documentation would be
cannam@128:      appreciated but is not required.
cannam@128:   2. Altered source versions must be plainly marked as such, and must not be
cannam@128:      misrepresented as being the original software.
cannam@128:   3. This notice may not be removed or altered from any source distribution.
cannam@128: 
cannam@128:   Mark Adler    madler@alumni.caltech.edu
cannam@128:  */
cannam@128: 
cannam@128: 
cannam@128: /*
cannam@128:  * blast() decompresses the PKWare Data Compression Library (DCL) compressed
cannam@128:  * format.  It provides the same functionality as the explode() function in
cannam@128:  * that library.  (Note: PKWare overused the "implode" verb, and the format
cannam@128:  * used by their library implode() function is completely different and
cannam@128:  * incompatible with the implode compression method supported by PKZIP.)
cannam@128:  *
cannam@128:  * The binary mode for stdio functions should be used to assure that the
cannam@128:  * compressed data is not corrupted when read or written.  For example:
cannam@128:  * fopen(..., "rb") and fopen(..., "wb").
cannam@128:  */
cannam@128: 
cannam@128: 
cannam@128: typedef unsigned (*blast_in)(void *how, unsigned char **buf);
cannam@128: typedef int (*blast_out)(void *how, unsigned char *buf, unsigned len);
cannam@128: /* Definitions for input/output functions passed to blast().  See below for
cannam@128:  * what the provided functions need to do.
cannam@128:  */
cannam@128: 
cannam@128: 
cannam@128: int blast(blast_in infun, void *inhow, blast_out outfun, void *outhow);
cannam@128: /* Decompress input to output using the provided infun() and outfun() calls.
cannam@128:  * On success, the return value of blast() is zero.  If there is an error in
cannam@128:  * the source data, i.e. it is not in the proper format, then a negative value
cannam@128:  * is returned.  If there is not enough input available or there is not enough
cannam@128:  * output space, then a positive error is returned.
cannam@128:  *
cannam@128:  * The input function is invoked: len = infun(how, &buf), where buf is set by
cannam@128:  * infun() to point to the input buffer, and infun() returns the number of
cannam@128:  * available bytes there.  If infun() returns zero, then blast() returns with
cannam@128:  * an input error.  (blast() only asks for input if it needs it.)  inhow is for
cannam@128:  * use by the application to pass an input descriptor to infun(), if desired.
cannam@128:  *
cannam@128:  * The output function is invoked: err = outfun(how, buf, len), where the bytes
cannam@128:  * to be written are buf[0..len-1].  If err is not zero, then blast() returns
cannam@128:  * with an output error.  outfun() is always called with len <= 4096.  outhow
cannam@128:  * is for use by the application to pass an output descriptor to outfun(), if
cannam@128:  * desired.
cannam@128:  *
cannam@128:  * The return codes are:
cannam@128:  *
cannam@128:  *   2:  ran out of input before completing decompression
cannam@128:  *   1:  output error before completing decompression
cannam@128:  *   0:  successful decompression
cannam@128:  *  -1:  literal flag not zero or one
cannam@128:  *  -2:  dictionary size not in 4..6
cannam@128:  *  -3:  distance is too far back
cannam@128:  *
cannam@128:  * At the bottom of blast.c is an example program that uses blast() that can be
cannam@128:  * compiled to produce a command-line decompression filter by defining TEST.
cannam@128:  */