xref: /netbsd-src/common/dist/zlib/contrib/blast/blast.h (revision ec47cc4ba82fddf470a849188f4f11d4978b571d)
1aaf4ece6Schristos /* blast.h -- interface for blast.c
2c3423655Schristos   Copyright (C) 2003, 2012, 2013 Mark Adler
3c3423655Schristos   version 1.3, 24 Aug 2013
4aaf4ece6Schristos 
5aaf4ece6Schristos   This software is provided 'as-is', without any express or implied
6aaf4ece6Schristos   warranty.  In no event will the author be held liable for any damages
7aaf4ece6Schristos   arising from the use of this software.
8aaf4ece6Schristos 
9aaf4ece6Schristos   Permission is granted to anyone to use this software for any purpose,
10aaf4ece6Schristos   including commercial applications, and to alter it and redistribute it
11aaf4ece6Schristos   freely, subject to the following restrictions:
12aaf4ece6Schristos 
13aaf4ece6Schristos   1. The origin of this software must not be misrepresented; you must not
14aaf4ece6Schristos      claim that you wrote the original software. If you use this software
15aaf4ece6Schristos      in a product, an acknowledgment in the product documentation would be
16aaf4ece6Schristos      appreciated but is not required.
17aaf4ece6Schristos   2. Altered source versions must be plainly marked as such, and must not be
18aaf4ece6Schristos      misrepresented as being the original software.
19aaf4ece6Schristos   3. This notice may not be removed or altered from any source distribution.
20aaf4ece6Schristos 
21aaf4ece6Schristos   Mark Adler    madler@alumni.caltech.edu
22aaf4ece6Schristos  */
23aaf4ece6Schristos 
24aaf4ece6Schristos 
25aaf4ece6Schristos /*
26aaf4ece6Schristos  * blast() decompresses the PKWare Data Compression Library (DCL) compressed
27aaf4ece6Schristos  * format.  It provides the same functionality as the explode() function in
28aaf4ece6Schristos  * that library.  (Note: PKWare overused the "implode" verb, and the format
29aaf4ece6Schristos  * used by their library implode() function is completely different and
30aaf4ece6Schristos  * incompatible with the implode compression method supported by PKZIP.)
31c3423655Schristos  *
32c3423655Schristos  * The binary mode for stdio functions should be used to assure that the
33c3423655Schristos  * compressed data is not corrupted when read or written.  For example:
34c3423655Schristos  * fopen(..., "rb") and fopen(..., "wb").
35aaf4ece6Schristos  */
36aaf4ece6Schristos 
37aaf4ece6Schristos 
38aaf4ece6Schristos typedef unsigned (*blast_in)(void *how, unsigned char **buf);
39aaf4ece6Schristos typedef int (*blast_out)(void *how, unsigned char *buf, unsigned len);
40aaf4ece6Schristos /* Definitions for input/output functions passed to blast().  See below for
41aaf4ece6Schristos  * what the provided functions need to do.
42aaf4ece6Schristos  */
43aaf4ece6Schristos 
44aaf4ece6Schristos 
45c3423655Schristos int blast(blast_in infun, void *inhow, blast_out outfun, void *outhow,
46c3423655Schristos           unsigned *left, unsigned char **in);
47aaf4ece6Schristos /* Decompress input to output using the provided infun() and outfun() calls.
48aaf4ece6Schristos  * On success, the return value of blast() is zero.  If there is an error in
49aaf4ece6Schristos  * the source data, i.e. it is not in the proper format, then a negative value
50aaf4ece6Schristos  * is returned.  If there is not enough input available or there is not enough
51aaf4ece6Schristos  * output space, then a positive error is returned.
52aaf4ece6Schristos  *
53aaf4ece6Schristos  * The input function is invoked: len = infun(how, &buf), where buf is set by
54aaf4ece6Schristos  * infun() to point to the input buffer, and infun() returns the number of
55aaf4ece6Schristos  * available bytes there.  If infun() returns zero, then blast() returns with
56aaf4ece6Schristos  * an input error.  (blast() only asks for input if it needs it.)  inhow is for
57aaf4ece6Schristos  * use by the application to pass an input descriptor to infun(), if desired.
58aaf4ece6Schristos  *
59c3423655Schristos  * If left and in are not NULL and *left is not zero when blast() is called,
60*ec47cc4bSchristos  * then the *left bytes at *in are consumed for input before infun() is used.
61c3423655Schristos  *
62aaf4ece6Schristos  * The output function is invoked: err = outfun(how, buf, len), where the bytes
63aaf4ece6Schristos  * to be written are buf[0..len-1].  If err is not zero, then blast() returns
64aaf4ece6Schristos  * with an output error.  outfun() is always called with len <= 4096.  outhow
65aaf4ece6Schristos  * is for use by the application to pass an output descriptor to outfun(), if
66aaf4ece6Schristos  * desired.
67aaf4ece6Schristos  *
68c3423655Schristos  * If there is any unused input, *left is set to the number of bytes that were
69c3423655Schristos  * read and *in points to them.  Otherwise *left is set to zero and *in is set
70c3423655Schristos  * to NULL.  If left or in are NULL, then they are not set.
71c3423655Schristos  *
72aaf4ece6Schristos  * The return codes are:
73aaf4ece6Schristos  *
74aaf4ece6Schristos  *   2:  ran out of input before completing decompression
75aaf4ece6Schristos  *   1:  output error before completing decompression
76aaf4ece6Schristos  *   0:  successful decompression
77aaf4ece6Schristos  *  -1:  literal flag not zero or one
78aaf4ece6Schristos  *  -2:  dictionary size not in 4..6
79aaf4ece6Schristos  *  -3:  distance is too far back
80aaf4ece6Schristos  *
81aaf4ece6Schristos  * At the bottom of blast.c is an example program that uses blast() that can be
82aaf4ece6Schristos  * compiled to produce a command-line decompression filter by defining TEST.
83aaf4ece6Schristos  */
84