00001 /* zlib.h -- interface of the 'zlib' general purpose compression library 00002 version 1.2.3, July 18th, 2005 00003 00004 Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler 00005 00006 This software is provided 'as-is', without any express or implied 00007 warranty. In no event will the authors be held liable for any damages 00008 arising from the use of this software. 00009 00010 Permission is granted to anyone to use this software for any purpose, 00011 including commercial applications, and to alter it and redistribute it 00012 freely, subject to the following restrictions: 00013 00014 1. The origin of this software must not be misrepresented; you must not 00015 claim that you wrote the original software. If you use this software 00016 in a product, an acknowledgment in the product documentation would be 00017 appreciated but is not required. 00018 2. Altered source versions must be plainly marked as such, and must not be 00019 misrepresented as being the original software. 00020 3. This notice may not be removed or altered from any source distribution. 00021 00022 Jean-loup Gailly Mark Adler 00023 jloup@gzip.org madler@alumni.caltech.edu 00024 00025 00026 The data format used by the zlib library is described by RFCs (Request for 00027 Comments) 1950 to 1952 in the files http://www.ietf.org/rfc/rfc1950.txt 00028 (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). 00029 */ 00030 00031 #ifndef ZLIB_H 00032 #define ZLIB_H 00033 00034 #include "zconf.h" 00035 00036 #ifdef __cplusplus 00037 extern "C" { 00038 #endif 00039 00040 #define ZLIB_VERSION "1.2.3" 00041 #define ZLIB_VERNUM 0x1230 00042 00043 /* 00044 The 'zlib' compression library provides in-memory compression and 00045 decompression functions, including integrity checks of the uncompressed 00046 data. This version of the library supports only one compression method 00047 (deflation) but other algorithms will be added later and will have the same 00048 stream interface. 00049 00050 Compression can be done in a single step if the buffers are large 00051 enough (for example if an input file is mmap'ed), or can be done by 00052 repeated calls of the compression function. In the latter case, the 00053 application must provide more input and/or consume the output 00054 (providing more output space) before each call. 00055 00056 The compressed data format used by default by the in-memory functions is 00057 the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped 00058 around a deflate stream, which is itself documented in RFC 1951. 00059 00060 The library also supports reading and writing files in gzip (.gz) format 00061 with an interface similar to that of stdio using the functions that start 00062 with "gz". The gzip format is different from the zlib format. gzip is a 00063 gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. 00064 00065 This library can optionally read and write gzip streams in memory as well. 00066 00067 The zlib format was designed to be compact and fast for use in memory 00068 and on communications channels. The gzip format was designed for single- 00069 file compression on file systems, has a larger header than zlib to maintain 00070 directory information, and uses a different, slower check method than zlib. 00071 00072 The library does not install any signal handler. The decoder checks 00073 the consistency of the compressed data, so the library should never 00074 crash even in case of corrupted input. 00075 */ 00076 00077 typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); 00078 typedef void (*free_func) OF((voidpf opaque, voidpf address)); 00079 00080 struct internal_state; 00081 00082 typedef struct z_stream_s { 00083 Bytef *next_in; /* next input byte */ 00084 uInt avail_in; /* number of bytes available at next_in */ 00085 uLong total_in; /* total nb of input bytes read so far */ 00086 00087 Bytef *next_out; /* next output byte should be put there */ 00088 uInt avail_out; /* remaining free space at next_out */ 00089 uLong total_out; /* total nb of bytes output so far */ 00090 00091 char *msg; /* last error message, NULL if no error */ 00092 struct internal_state FAR *state; /* not visible by applications */ 00093 00094 alloc_func zalloc; /* used to allocate the internal state */ 00095 free_func zfree; /* used to free the internal state */ 00096 voidpf opaque; /* private data object passed to zalloc and zfree */ 00097 00098 int data_type; /* best guess about the data type: binary or text */ 00099 uLong adler; /* adler32 value of the uncompressed data */ 00100 uLong reserved; /* reserved for future use */ 00101 } z_stream; 00102 00103 typedef z_stream FAR *z_streamp; 00104 00105 /* 00106 gzip header information passed to and from zlib routines. See RFC 1952 00107 for more details on the meanings of these fields. 00108 */ 00109 typedef struct gz_header_s { 00110 int text; /* true if compressed data believed to be text */ 00111 uLong time; /* modification time */ 00112 int xflags; /* extra flags (not used when writing a gzip file) */ 00113 int os; /* operating system */ 00114 Bytef *extra; /* pointer to extra field or Z_NULL if none */ 00115 uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ 00116 uInt extra_max; /* space at extra (only when reading header) */ 00117 Bytef *name; /* pointer to zero-terminated file name or Z_NULL */ 00118 uInt name_max; /* space at name (only when reading header) */ 00119 Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ 00120 uInt comm_max; /* space at comment (only when reading header) */ 00121 int hcrc; /* true if there was or will be a header crc */ 00122 int done; /* true when done reading gzip header (not used 00123 when writing a gzip file) */ 00124 } gz_header; 00125 00126 typedef gz_header FAR *gz_headerp; 00127 00128 /* 00129 The application must update next_in and avail_in when avail_in has 00130 dropped to zero. It must update next_out and avail_out when avail_out 00131 has dropped to zero. The application must initialize zalloc, zfree and 00132 opaque before calling the init function. All other fields are set by the 00133 compression library and must not be updated by the application. 00134 00135 The opaque value provided by the application will be passed as the first 00136 parameter for calls of zalloc and zfree. This can be useful for custom 00137 memory management. The compression library attaches no meaning to the 00138 opaque value. 00139 00140 zalloc must return Z_NULL if there is not enough memory for the object. 00141 If zlib is used in a multi-threaded application, zalloc and zfree must be 00142 thread safe. 00143 00144 On 16-bit systems, the functions zalloc and zfree must be able to allocate 00145 exactly 65536 bytes, but will not be required to allocate more than this 00146 if the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS, 00147 pointers returned by zalloc for objects of exactly 65536 bytes *must* 00148 have their offset normalized to zero. The default allocation function 00149 provided by this library ensures this (see zutil.c). To reduce memory 00150 requirements and avoid any allocation of 64K objects, at the expense of 00151 compression ratio, compile the library with -DMAX_WBITS=14 (see zconf.h). 00152 00153 The fields total_in and total_out can be used for statistics or 00154 progress reports. After compression, total_in holds the total size of 00155 the uncompressed data and may be saved for use in the decompressor 00156 (particularly if the decompressor wants to decompress everything in 00157 a single step). 00158 */ 00159 00160 /* constants */ 00161 00162 #define Z_NO_FLUSH 0 00163 #define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ 00164 #define Z_SYNC_FLUSH 2 00165 #define Z_FULL_FLUSH 3 00166 #define Z_FINISH 4 00167 #define Z_BLOCK 5 00168 /* Allowed flush values; see deflate() and inflate() below for details */ 00169 00170 #define Z_OK 0 00171 #define Z_STREAM_END 1 00172 #define Z_NEED_DICT 2 00173 #define Z_ERRNO (-1) 00174 #define Z_STREAM_ERROR (-2) 00175 #define Z_DATA_ERROR (-3) 00176 #define Z_MEM_ERROR (-4) 00177 #define Z_BUF_ERROR (-5) 00178 #define Z_VERSION_ERROR (-6) 00179 /* Return codes for the compression/decompression functions. Negative 00180 * values are errors, positive values are used for special but normal events. 00181 */ 00182 00183 #define Z_NO_COMPRESSION 0 00184 #define Z_BEST_SPEED 1 00185 #define Z_BEST_COMPRESSION 9 00186 #define Z_DEFAULT_COMPRESSION (-1) 00187 /* compression levels */ 00188 00189 #define Z_FILTERED 1 00190 #define Z_HUFFMAN_ONLY 2 00191 #define Z_RLE 3 00192 #define Z_FIXED 4 00193 #define Z_DEFAULT_STRATEGY 0 00194 /* compression strategy; see deflateInit2() below for details */ 00195 00196 #define Z_BINARY 0 00197 #define Z_TEXT 1 00198 #define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ 00199 #define Z_UNKNOWN 2 00200 /* Possible values of the data_type field (though see inflate()) */ 00201 00202 #define Z_DEFLATED 8 00203 /* The deflate compression method (the only one supported in this version) */ 00204 00205 #define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ 00206 00207 #define zlib_version zlibVersion() 00208 /* for compatibility with versions < 1.0.2 */ 00209 00210 /* basic functions */ 00211 00212 ZEXTERN const char * ZEXPORT zlibVersion OF((void)); 00213 /* The application can compare zlibVersion and ZLIB_VERSION for consistency. 00214 If the first character differs, the library code actually used is 00215 not compatible with the zlib.h header file used by the application. 00216 This check is automatically made by deflateInit and inflateInit. 00217 */ 00218 00219 /* 00220 ZEXTERN int ZEXPORT deflateInit OF((z_streamp strm, int level)); 00221 00222 Initializes the internal stream state for compression. The fields 00223 zalloc, zfree and opaque must be initialized before by the caller. 00224 If zalloc and zfree are set to Z_NULL, deflateInit updates them to 00225 use default allocation functions. 00226 00227 The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9: 00228 1 gives best speed, 9 gives best compression, 0 gives no compression at 00229 all (the input data is simply copied a block at a time). 00230 Z_DEFAULT_COMPRESSION requests a default compromise between speed and 00231 compression (currently equivalent to level 6). 00232 00233 deflateInit returns Z_OK if success, Z_MEM_ERROR if there was not 00234 enough memory, Z_STREAM_ERROR if level is not a valid compression level, 00235 Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible 00236 with the version assumed by the caller (ZLIB_VERSION). 00237 msg is set to null if there is no error message. deflateInit does not 00238 perform any compression: this will be done by deflate(). 00239 */ 00240 00241 00242 ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); 00243 /* 00244 deflate compresses as much data as possible, and stops when the input 00245 buffer becomes empty or the output buffer becomes full. It may introduce some 00246 output latency (reading input without producing any output) except when 00247 forced to flush. 00248 00249 The detailed semantics are as follows. deflate performs one or both of the 00250 following actions: 00251 00252 - Compress more input starting at next_in and update next_in and avail_in 00253 accordingly. If not all input can be processed (because there is not 00254 enough room in the output buffer), next_in and avail_in are updated and 00255 processing will resume at this point for the next call of deflate(). 00256 00257 - Provide more output starting at next_out and update next_out and avail_out 00258 accordingly. This action is forced if the parameter flush is non zero. 00259 Forcing flush frequently degrades the compression ratio, so this parameter 00260 should be set only when necessary (in interactive applications). 00261 Some output may be provided even if flush is not set. 00262 00263 Before the call of deflate(), the application should ensure that at least 00264 one of the actions is possible, by providing more input and/or consuming 00265 more output, and updating avail_in or avail_out accordingly; avail_out 00266 should never be zero before the call. The application can consume the 00267 compressed output when it wants, for example when the output buffer is full 00268 (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK 00269 and with zero avail_out, it must be called again after making room in the 00270 output buffer because there might be more output pending. 00271 00272 Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to 00273 decide how much data to accumualte before producing output, in order to 00274 maximize compression. 00275 00276 If the parameter flush is set to Z_SYNC_FLUSH, all pending output is 00277 flushed to the output buffer and the output is aligned on a byte boundary, so 00278 that the decompressor can get all input data available so far. (In particular 00279 avail_in is zero after the call if enough output space has been provided 00280 before the call.) Flushing may degrade compression for some compression 00281 algorithms and so it should be used only when necessary. 00282 00283 If flush is set to Z_FULL_FLUSH, all output is flushed as with 00284 Z_SYNC_FLUSH, and the compression state is reset so that decompression can 00285 restart from this point if previous compressed data has been damaged or if 00286 random access is desired. Using Z_FULL_FLUSH too often can seriously degrade 00287 compression. 00288 00289 If deflate returns with avail_out == 0, this function must be called again 00290 with the same value of the flush parameter and more output space (updated 00291 avail_out), until the flush is complete (deflate returns with non-zero 00292 avail_out). In the case of a Z_FULL_FLUSH or Z_SYNC_FLUSH, make sure that 00293 avail_out is greater than six to avoid repeated flush markers due to 00294 avail_out == 0 on return. 00295 00296 If the parameter flush is set to Z_FINISH, pending input is processed, 00297 pending output is flushed and deflate returns with Z_STREAM_END if there 00298 was enough output space; if deflate returns with Z_OK, this function must be 00299 called again with Z_FINISH and more output space (updated avail_out) but no 00300 more input data, until it returns with Z_STREAM_END or an error. After 00301 deflate has returned Z_STREAM_END, the only possible operations on the 00302 stream are deflateReset or deflateEnd. 00303 00304 Z_FINISH can be used immediately after deflateInit if all the compression 00305 is to be done in a single step. In this case, avail_out must be at least 00306 the value returned by deflateBound (see below). If deflate does not return 00307 Z_STREAM_END, then it must be called again as described above. 00308 00309 deflate() sets strm->adler to the adler32 checksum of all input read 00310 so far (that is, total_in bytes). 00311 00312 deflate() may update strm->data_type if it can make a good guess about 00313 the input data type (Z_BINARY or Z_TEXT). In doubt, the data is considered 00314 binary. This field is only for information purposes and does not affect 00315 the compression algorithm in any manner. 00316 00317 deflate() returns Z_OK if some progress has been made (more input 00318 processed or more output produced), Z_STREAM_END if all input has been 00319 consumed and all output has been produced (only when flush is set to 00320 Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example 00321 if next_in or next_out was NULL), Z_BUF_ERROR if no progress is possible 00322 (for example avail_in or avail_out was zero). Note that Z_BUF_ERROR is not 00323 fatal, and deflate() can be called again with more input and more output 00324 space to continue compressing. 00325 */ 00326 00327 00328 ZEXTERN int ZEXPORT deflateEnd OF((z_streamp strm)); 00329 /* 00330 All dynamically allocated data structures for this stream are freed. 00331 This function discards any unprocessed input and does not flush any 00332 pending output. 00333 00334 deflateEnd returns Z_OK if success, Z_STREAM_ERROR if the 00335 stream state was inconsistent, Z_DATA_ERROR if the stream was freed 00336 prematurely (some input or output was discarded). In the error case, 00337 msg may be set but then points to a static string (which must not be 00338 deallocated). 00339 */ 00340 00341 00342 /* 00343 ZEXTERN int ZEXPORT inflateInit OF((z_streamp strm)); 00344 00345 Initializes the internal stream state for decompression. The fields 00346 next_in, avail_in, zalloc, zfree and opaque must be initialized before by 00347 the caller. If next_in is not Z_NULL and avail_in is large enough (the exact 00348 value depends on the compression method), inflateInit determines the 00349 compression method from the zlib header and allocates all data structures 00350 accordingly; otherwise the allocation will be deferred to the first call of 00351 inflate. If zalloc and zfree are set to Z_NULL, inflateInit updates them to 00352 use default allocation functions. 00353 00354 inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough 00355 memory, Z_VERSION_ERROR if the zlib library version is incompatible with the 00356 version assumed by the caller. msg is set to null if there is no error 00357 message. inflateInit does not perform any decompression apart from reading 00358 the zlib header if present: this will be done by inflate(). (So next_in and 00359 avail_in may be modified, but next_out and avail_out are unchanged.) 00360 */ 00361 00362 00363 ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); 00364 /* 00365 inflate decompresses as much data as possible, and stops when the input 00366 buffer becomes empty or the output buffer becomes full. It may introduce 00367 some output latency (reading input without producing any output) except when 00368 forced to flush. 00369 00370 The detailed semantics are as follows. inflate performs one or both of the 00371 following actions: 00372 00373 - Decompress more input starting at next_in and update next_in and avail_in 00374 accordingly. If not all input can be processed (because there is not 00375 enough room in the output buffer), next_in is updated and processing 00376 will resume at this point for the next call of inflate(). 00377 00378 - Provide more output starting at next_out and update next_out and avail_out 00379 accordingly. inflate() provides as much output as possible, until there 00380 is no more input data or no more space in the output buffer (see below 00381 about the flush parameter). 00382 00383 Before the call of inflate(), the application should ensure that at least 00384 one of the actions is possible, by providing more input and/or consuming 00385 more output, and updating the next_* and avail_* values accordingly. 00386 The application can consume the uncompressed output when it wants, for 00387 example when the output buffer is full (avail_out == 0), or after each 00388 call of inflate(). If inflate returns Z_OK and with zero avail_out, it 00389 must be called again after making room in the output buffer because there 00390 might be more output pending. 00391 00392 The flush parameter of inflate() can be Z_NO_FLUSH, Z_SYNC_FLUSH, 00393 Z_FINISH, or Z_BLOCK. Z_SYNC_FLUSH requests that inflate() flush as much 00394 output as possible to the output buffer. Z_BLOCK requests that inflate() stop 00395 if and when it gets to the next deflate block boundary. When decoding the 00396 zlib or gzip format, this will cause inflate() to return immediately after 00397 the header and before the first block. When doing a raw inflate, inflate() 00398 will go ahead and process the first block, and will return when it gets to 00399 the end of that block, or when it runs out of data. 00400 00401 The Z_BLOCK option assists in appending to or combining deflate streams. 00402 Also to assist in this, on return inflate() will set strm->data_type to the 00403 number of unused bits in the last byte taken from strm->next_in, plus 64 00404 if inflate() is currently decoding the last block in the deflate stream, 00405 plus 128 if inflate() returned immediately after decoding an end-of-block 00406 code or decoding the complete header up to just before the first byte of the 00407 deflate stream. The end-of-block will not be indicated until all of the 00408 uncompressed data from that block has been written to strm->next_out. The 00409 number of unused bits may in general be greater than seven, except when 00410 bit 7 of data_type is set, in which case the number of unused bits will be 00411 less than eight. 00412 00413 inflate() should normally be called until it returns Z_STREAM_END or an 00414 error. However if all decompression is to be performed in a single step 00415 (a single call of inflate), the parameter flush should be set to 00416 Z_FINISH. In this case all pending input is processed and all pending 00417 output is flushed; avail_out must be large enough to hold all the 00418 uncompressed data. (The size of the uncompressed data may have been saved 00419 by the compressor for this purpose.) The next operation on this stream must 00420 be inflateEnd to deallocate the decompression state. The use of Z_FINISH 00421 is never required, but can be used to inform inflate that a faster approach 00422 may be used for the single inflate() call. 00423 00424 In this implementation, inflate() always flushes as much output as 00425 possible to the output buffer, and always uses the faster approach on the 00426 first call. So the only effect of the flush parameter in this implementation 00427 is on the return value of inflate(), as noted below, or when it returns early 00428 because Z_BLOCK is used. 00429 00430 If a preset dictionary is needed after this call (see inflateSetDictionary 00431 below), inflate sets strm->adler to the adler32 checksum of the dictionary 00432 chosen by the compressor and returns Z_NEED_DICT; otherwise it sets 00433 strm->adler to the adler32 checksum of all output produced so far (that is, 00434 total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described 00435 below. At the end of the stream, inflate() checks that its computed adler32 00436 checksum is equal to that saved by the compressor and returns Z_STREAM_END 00437 only if the checksum is correct. 00438 00439 inflate() will decompress and check either zlib-wrapped or gzip-wrapped 00440 deflate data. The header type is detected automatically. Any information 00441 contained in the gzip header is not retained, so applications that need that 00442 information should instead use raw inflate, see inflateInit2() below, or 00443 inflateBack() and perform their own processing of the gzip header and 00444 trailer. 00445 00446 inflate() returns Z_OK if some progress has been made (more input processed 00447 or more output produced), Z_STREAM_END if the end of the compressed data has 00448 been reached and all uncompressed output has been produced, Z_NEED_DICT if a 00449 preset dictionary is needed at this point, Z_DATA_ERROR if the input data was 00450 corrupted (input stream not conforming to the zlib format or incorrect check 00451 value), Z_STREAM_ERROR if the stream structure was inconsistent (for example 00452 if next_in or next_out was NULL), Z_MEM_ERROR if there was not enough memory, 00453 Z_BUF_ERROR if no progress is possible or if there was not enough room in the 00454 output buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and 00455 inflate() can be called again with more input and more output space to 00456 continue decompressing. If Z_DATA_ERROR is returned, the application may then 00457 call inflateSync() to look for a good compression block if a partial recovery 00458 of the data is desired. 00459 */ 00460 00461 00462 ZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm)); 00463 /* 00464 All dynamically allocated data structures for this stream are freed. 00465 This function discards any unprocessed input and does not flush any 00466 pending output. 00467 00468 inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state 00469 was inconsistent. In the error case, msg may be set but then points to a 00470 static string (which must not be deallocated). 00471 */ 00472 00473 /* Advanced functions */ 00474 00475 /* 00476 The following functions are needed only in some special applications. 00477 */ 00478 00479 /* 00480 ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, 00481 int level, 00482 int method, 00483 int windowBits, 00484 int memLevel, 00485 int strategy)); 00486 00487 This is another version of deflateInit with more compression options. The 00488 fields next_in, zalloc, zfree and opaque must be initialized before by 00489 the caller. 00490 00491 The method parameter is the compression method. It must be Z_DEFLATED in 00492 this version of the library. 00493 00494 The windowBits parameter is the base two logarithm of the window size 00495 (the size of the history buffer). It should be in the range 8..15 for this 00496 version of the library. Larger values of this parameter result in better 00497 compression at the expense of memory usage. The default value is 15 if 00498 deflateInit is used instead. 00499 00500 windowBits can also be -8..-15 for raw deflate. In this case, -windowBits 00501 determines the window size. deflate() will then generate raw deflate data 00502 with no zlib header or trailer, and will not compute an adler32 check value. 00503 00504 windowBits can also be greater than 15 for optional gzip encoding. Add 00505 16 to windowBits to write a simple gzip header and trailer around the 00506 compressed data instead of a zlib wrapper. The gzip header will have no 00507 file name, no extra data, no comment, no modification time (set to zero), 00508 no header crc, and the operating system will be set to 255 (unknown). If a 00509 gzip stream is being written, strm->adler is a crc32 instead of an adler32. 00510 00511 The memLevel parameter specifies how much memory should be allocated 00512 for the internal compression state. memLevel=1 uses minimum memory but 00513 is slow and reduces compression ratio; memLevel=9 uses maximum memory 00514 for optimal speed. The default value is 8. See zconf.h for total memory 00515 usage as a function of windowBits and memLevel. 00516 00517 The strategy parameter is used to tune the compression algorithm. Use the 00518 value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a 00519 filter (or predictor), Z_HUFFMAN_ONLY to force Huffman encoding only (no 00520 string match), or Z_RLE to limit match distances to one (run-length 00521 encoding). Filtered data consists mostly of small values with a somewhat 00522 random distribution. In this case, the compression algorithm is tuned to 00523 compress them better. The effect of Z_FILTERED is to force more Huffman 00524 coding and less string matching; it is somewhat intermediate between 00525 Z_DEFAULT and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as fast as 00526 Z_HUFFMAN_ONLY, but give better compression for PNG image data. The strategy 00527 parameter only affects the compression ratio but not the correctness of the 00528 compressed output even if it is not set appropriately. Z_FIXED prevents the 00529 use of dynamic Huffman codes, allowing for a simpler decoder for special 00530 applications. 00531 00532 deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 00533 memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid 00534 method). msg is set to null if there is no error message. deflateInit2 does 00535 not perform any compression: this will be done by deflate(). 00536 */ 00537 00538 ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, 00539 const Bytef *dictionary, 00540 uInt dictLength)); 00541 /* 00542 Initializes the compression dictionary from the given byte sequence 00543 without producing any compressed output. This function must be called 00544 immediately after deflateInit, deflateInit2 or deflateReset, before any 00545 call of deflate. The compressor and decompressor must use exactly the same 00546 dictionary (see inflateSetDictionary). 00547 00548 The dictionary should consist of strings (byte sequences) that are likely 00549 to be encountered later in the data to be compressed, with the most commonly 00550 used strings preferably put towards the end of the dictionary. Using a 00551 dictionary is most useful when the data to be compressed is short and can be 00552 predicted with good accuracy; the data can then be compressed better than 00553 with the default empty dictionary. 00554 00555 Depending on the size of the compression data structures selected by 00556 deflateInit or deflateInit2, a part of the dictionary may in effect be 00557 discarded, for example if the dictionary is larger than the window size in 00558 deflate or deflate2. Thus the strings most likely to be useful should be 00559 put at the end of the dictionary, not at the front. In addition, the 00560 current implementation of deflate will use at most the window size minus 00561 262 bytes of the provided dictionary. 00562 00563 Upon return of this function, strm->adler is set to the adler32 value 00564 of the dictionary; the decompressor may later use this value to determine 00565 which dictionary has been used by the compressor. (The adler32 value 00566 applies to the whole dictionary even if only a subset of the dictionary is 00567 actually used by the compressor.) If a raw deflate was requested, then the 00568 adler32 value is not computed and strm->adler is not set. 00569 00570 deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a 00571 parameter is invalid (such as NULL dictionary) or the stream state is 00572 inconsistent (for example if deflate has already been called for this stream 00573 or if the compression method is bsort). deflateSetDictionary does not 00574 perform any compression: this will be done by deflate(). 00575 */ 00576 00577 ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, 00578 z_streamp source)); 00579 /* 00580 Sets the destination stream as a complete copy of the source stream. 00581 00582 This function can be useful when several compression strategies will be 00583 tried, for example when there are several ways of pre-processing the input 00584 data with a filter. The streams that will be discarded should then be freed 00585 by calling deflateEnd. Note that deflateCopy duplicates the internal 00586 compression state which can be quite large, so this strategy is slow and 00587 can consume lots of memory. 00588 00589 deflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not 00590 enough memory, Z_STREAM_ERROR if the source stream state was inconsistent 00591 (such as zalloc being NULL). msg is left unchanged in both source and 00592 destination. 00593 */ 00594 00595 ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm)); 00596 /* 00597 This function is equivalent to deflateEnd followed by deflateInit, 00598 but does not free and reallocate all the internal compression state. 00599 The stream will keep the same compression level and any other attributes 00600 that may have been set by deflateInit2. 00601 00602 deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source 00603 stream state was inconsistent (such as zalloc or state being NULL). 00604 */ 00605 00606 ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, 00607 int level, 00608 int strategy)); 00609 /* 00610 Dynamically update the compression level and compression strategy. The 00611 interpretation of level and strategy is as in deflateInit2. This can be 00612 used to switch between compression and straight copy of the input data, or 00613 to switch to a different kind of input data requiring a different 00614 strategy. If the compression level is changed, the input available so far 00615 is compressed with the old level (and may be flushed); the new level will 00616 take effect only at the next call of deflate(). 00617 00618 Before the call of deflateParams, the stream state must be set as for 00619 a call of deflate(), since the currently available input may have to 00620 be compressed and flushed. In particular, strm->avail_out must be non-zero. 00621 00622 deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source 00623 stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR 00624 if strm->avail_out was zero. 00625 */ 00626 00627 ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, 00628 int good_length, 00629 int max_lazy, 00630 int nice_length, 00631 int max_chain)); 00632 /* 00633 Fine tune deflate's internal compression parameters. This should only be 00634 used by someone who understands the algorithm used by zlib's deflate for 00635 searching for the best matching string, and even then only by the most 00636 fanatic optimizer trying to squeeze out the last compressed bit for their 00637 specific input data. Read the deflate.c source code for the meaning of the 00638 max_lazy, good_length, nice_length, and max_chain parameters. 00639 00640 deflateTune() can be called after deflateInit() or deflateInit2(), and 00641 returns Z_OK on success, or Z_STREAM_ERROR for an invalid deflate stream. 00642 */ 00643 00644 ZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm, 00645 uLong sourceLen)); 00646 /* 00647 deflateBound() returns an upper bound on the compressed size after 00648 deflation of sourceLen bytes. It must be called after deflateInit() 00649 or deflateInit2(). This would be used to allocate an output buffer 00650 for deflation in a single pass, and so would be called before deflate(). 00651 */ 00652 00653 ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm, 00654 int bits, 00655 int value)); 00656 /* 00657 deflatePrime() inserts bits in the deflate output stream. The intent 00658 is that this function is used to start off the deflate output with the 00659 bits leftover from a previous deflate stream when appending to it. As such, 00660 this function can only be used for raw deflate, and must be used before the 00661 first deflate() call after a deflateInit2() or deflateReset(). bits must be 00662 less than or equal to 16, and that many of the least significant bits of 00663 value will be inserted in the output. 00664 00665 deflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source 00666 stream state was inconsistent. 00667 */ 00668 00669 ZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm, 00670 gz_headerp head)); 00671 /* 00672 deflateSetHeader() provides gzip header information for when a gzip 00673 stream is requested by deflateInit2(). deflateSetHeader() may be called 00674 after deflateInit2() or deflateReset() and before the first call of 00675 deflate(). The text, time, os, extra field, name, and comment information 00676 in the provided gz_header structure are written to the gzip header (xflag is 00677 ignored -- the extra flags are set according to the compression level). The 00678 caller must assure that, if not Z_NULL, name and comment are terminated with 00679 a zero byte, and that if extra is not Z_NULL, that extra_len bytes are 00680 available there. If hcrc is true, a gzip header crc is included. Note that 00681 the current versions of the command-line version of gzip (up through version 00682 1.3.x) do not support header crc's, and will report that it is a "multi-part 00683 gzip file" and give up. 00684 00685 If deflateSetHeader is not used, the default gzip header has text false, 00686 the time set to zero, and os set to 255, with no extra, name, or comment 00687 fields. The gzip header is returned to the default state by deflateReset(). 00688 00689 deflateSetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source 00690 stream state was inconsistent. 00691 */ 00692 00693 /* 00694 ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, 00695 int windowBits)); 00696 00697 This is another version of inflateInit with an extra parameter. The 00698 fields next_in, avail_in, zalloc, zfree and opaque must be initialized 00699 before by the caller. 00700 00701 The windowBits parameter is the base two logarithm of the maximum window 00702 size (the size of the history buffer). It should be in the range 8..15 for 00703 this version of the library. The default value is 15 if inflateInit is used 00704 instead. windowBits must be greater than or equal to the windowBits value 00705 provided to deflateInit2() while compressing, or it must be equal to 15 if 00706 deflateInit2() was not used. If a compressed stream with a larger window 00707 size is given as input, inflate() will return with the error code 00708 Z_DATA_ERROR instead of trying to allocate a larger window. 00709 00710 windowBits can also be -8..-15 for raw inflate. In this case, -windowBits 00711 determines the window size. inflate() will then process raw deflate data, 00712 not looking for a zlib or gzip header, not generating a check value, and not 00713 looking for any check values for comparison at the end of the stream. This 00714 is for use with other formats that use the deflate compressed data format 00715 such as zip. Those formats provide their own check values. If a custom 00716 format is developed using the raw deflate format for compressed data, it is 00717 recommended that a check value such as an adler32 or a crc32 be applied to 00718 the uncompressed data as is done in the zlib, gzip, and zip formats. For 00719 most applications, the zlib format should be used as is. Note that comments 00720 above on the use in deflateInit2() applies to the magnitude of windowBits. 00721 00722 windowBits can also be greater than 15 for optional gzip decoding. Add 00723 32 to windowBits to enable zlib and gzip decoding with automatic header 00724 detection, or add 16 to decode only the gzip format (the zlib format will 00725 return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is 00726 a crc32 instead of an adler32. 00727 00728 inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 00729 memory, Z_STREAM_ERROR if a parameter is invalid (such as a null strm). msg 00730 is set to null if there is no error message. inflateInit2 does not perform 00731 any decompression apart from reading the zlib header if present: this will 00732 be done by inflate(). (So next_in and avail_in may be modified, but next_out 00733 and avail_out are unchanged.) 00734 */ 00735 00736 ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, 00737 const Bytef *dictionary, 00738 uInt dictLength)); 00739 /* 00740 Initializes the decompression dictionary from the given uncompressed byte 00741 sequence. This function must be called immediately after a call of inflate, 00742 if that call returned Z_NEED_DICT. The dictionary chosen by the compressor 00743 can be determined from the adler32 value returned by that call of inflate. 00744 The compressor and decompressor must use exactly the same dictionary (see 00745 deflateSetDictionary). For raw inflate, this function can be called 00746 immediately after inflateInit2() or inflateReset() and before any call of 00747 inflate() to set the dictionary. The application must insure that the 00748 dictionary that was used for compression is provided. 00749 00750 inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a 00751 parameter is invalid (such as NULL dictionary) or the stream state is 00752 inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the 00753 expected one (incorrect adler32 value). inflateSetDictionary does not 00754 perform any decompression: this will be done by subsequent calls of 00755 inflate(). 00756 */ 00757 00758 ZEXTERN int ZEXPORT inflateSync OF((z_streamp strm)); 00759 /* 00760 Skips invalid compressed data until a full flush point (see above the 00761 description of deflate with Z_FULL_FLUSH) can be found, or until all 00762 available input is skipped. No output is provided. 00763 00764 inflateSync returns Z_OK if a full flush point has been found, Z_BUF_ERROR 00765 if no more input was provided, Z_DATA_ERROR if no flush point has been found, 00766 or Z_STREAM_ERROR if the stream structure was inconsistent. In the success 00767 case, the application may save the current current value of total_in which 00768 indicates where valid compressed data was found. In the error case, the 00769 application may repeatedly call inflateSync, providing more input each time, 00770 until success or end of the input data. 00771 */ 00772 00773 ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, 00774 z_streamp source)); 00775 /* 00776 Sets the destination stream as a complete copy of the source stream. 00777 00778 This function can be useful when randomly accessing a large stream. The 00779 first pass through the stream can periodically record the inflate state, 00780 allowing restarting inflate at those points when randomly accessing the 00781 stream. 00782 00783 inflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not 00784 enough memory, Z_STREAM_ERROR if the source stream state was inconsistent 00785 (such as zalloc being NULL). msg is left unchanged in both source and 00786 destination. 00787 */ 00788 00789 ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm)); 00790 /* 00791 This function is equivalent to inflateEnd followed by inflateInit, 00792 but does not free and reallocate all the internal decompression state. 00793 The stream will keep attributes that may have been set by inflateInit2. 00794 00795 inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source 00796 stream state was inconsistent (such as zalloc or state being NULL). 00797 */ 00798 00799 ZEXTERN int ZEXPORT inflatePrime OF((z_streamp strm, 00800 int bits, 00801 int value)); 00802 /* 00803 This function inserts bits in the inflate input stream. The intent is 00804 that this function is used to start inflating at a bit position in the 00805 middle of a byte. The provided bits will be used before any bytes are used 00806 from next_in. This function should only be used with raw inflate, and 00807 should be used before the first inflate() call after inflateInit2() or 00808 inflateReset(). bits must be less than or equal to 16, and that many of the 00809 least significant bits of value will be inserted in the input. 00810 00811 inflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source 00812 stream state was inconsistent. 00813 */ 00814 00815 ZEXTERN int ZEXPORT inflateGetHeader OF((z_streamp strm, 00816 gz_headerp head)); 00817 /* 00818 inflateGetHeader() requests that gzip header information be stored in the 00819 provided gz_header structure. inflateGetHeader() may be called after 00820 inflateInit2() or inflateReset(), and before the first call of inflate(). 00821 As inflate() processes the gzip stream, head->done is zero until the header 00822 is completed, at which time head->done is set to one. If a zlib stream is 00823 being decoded, then head->done is set to -1 to indicate that there will be 00824 no gzip header information forthcoming. Note that Z_BLOCK can be used to 00825 force inflate() to return immediately after header processing is complete 00826 and before any actual data is decompressed. 00827 00828 The text, time, xflags, and os fields are filled in with the gzip header 00829 contents. hcrc is set to true if there is a header CRC. (The header CRC 00830 was valid if done is set to one.) If extra is not Z_NULL, then extra_max 00831 contains the maximum number of bytes to write to extra. Once done is true, 00832 extra_len contains the actual extra field length, and extra contains the 00833 extra field, or that field truncated if extra_max is less than extra_len. 00834 If name is not Z_NULL, then up to name_max characters are written there, 00835 terminated with a zero unless the length is greater than name_max. If 00836 comment is not Z_NULL, then up to comm_max characters are written there, 00837 terminated with a zero unless the length is greater than comm_max. When 00838 any of extra, name, or comment are not Z_NULL and the respective field is 00839 not present in the header, then that field is set to Z_NULL to signal its 00840 absence. This allows the use of deflateSetHeader() with the returned 00841 structure to duplicate the header. However if those fields are set to 00842 allocated memory, then the application will need to save those pointers 00843 elsewhere so that they can be eventually freed. 00844 00845 If inflateGetHeader is not used, then the header information is simply 00846 discarded. The header is always checked for validity, including the header 00847 CRC if present. inflateReset() will reset the process to discard the header 00848 information. The application would need to call inflateGetHeader() again to 00849 retrieve the header from the next gzip stream. 00850 00851 inflateGetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source 00852 stream state was inconsistent. 00853 */ 00854 00855 /* 00856 ZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits, 00857 unsigned char FAR *window)); 00858 00859 Initialize the internal stream state for decompression using inflateBack() 00860 calls. The fields zalloc, zfree and opaque in strm must be initialized 00861 before the call. If zalloc and zfree are Z_NULL, then the default library- 00862 derived memory allocation routines are used. windowBits is the base two 00863 logarithm of the window size, in the range 8..15. window is a caller 00864 supplied buffer of that size. Except for special applications where it is 00865 assured that deflate was used with small window sizes, windowBits must be 15 00866 and a 32K byte window must be supplied to be able to decompress general 00867 deflate streams. 00868 00869 See inflateBack() for the usage of these routines. 00870 00871 inflateBackInit will return Z_OK on success, Z_STREAM_ERROR if any of 00872 the paramaters are invalid, Z_MEM_ERROR if the internal state could not 00873 be allocated, or Z_VERSION_ERROR if the version of the library does not 00874 match the version of the header file. 00875 */ 00876 00877 typedef unsigned (*in_func) OF((void FAR *, unsigned char FAR * FAR *)); 00878 typedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned)); 00879 00880 ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, 00881 in_func in, void FAR *in_desc, 00882 out_func out, void FAR *out_desc)); 00883 /* 00884 inflateBack() does a raw inflate with a single call using a call-back 00885 interface for input and output. This is more efficient than inflate() for 00886 file i/o applications in that it avoids copying between the output and the 00887 sliding window by simply making the window itself the output buffer. This 00888 function trusts the application to not change the output buffer passed by 00889 the output function, at least until inflateBack() returns. 00890 00891 inflateBackInit() must be called first to allocate the internal state 00892 and to initialize the state with the user-provided window buffer. 00893 inflateBack() may then be used multiple times to inflate a complete, raw 00894 deflate stream with each call. inflateBackEnd() is then called to free 00895 the allocated state. 00896 00897 A raw deflate stream is one with no zlib or gzip header or trailer. 00898 This routine would normally be used in a utility that reads zip or gzip 00899 files and writes out uncompressed files. The utility would decode the 00900 header and process the trailer on its own, hence this routine expects 00901 only the raw deflate stream to decompress. This is different from the 00902 normal behavior of inflate(), which expects either a zlib or gzip header and 00903 trailer around the deflate stream. 00904 00905 inflateBack() uses two subroutines supplied by the caller that are then 00906 called by inflateBack() for input and output. inflateBack() calls those 00907 routines until it reads a complete deflate stream and writes out all of the 00908 uncompressed data, or until it encounters an error. The function's 00909 parameters and return types are defined above in the in_func and out_func 00910 typedefs. inflateBack() will call in(in_desc, &buf) which should return the 00911 number of bytes of provided input, and a pointer to that input in buf. If 00912 there is no input available, in() must return zero--buf is ignored in that 00913 case--and inflateBack() will return a buffer error. inflateBack() will call 00914 out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out() 00915 should return zero on success, or non-zero on failure. If out() returns 00916 non-zero, inflateBack() will return with an error. Neither in() nor out() 00917 are permitted to change the contents of the window provided to 00918 inflateBackInit(), which is also the buffer that out() uses to write from. 00919 The length written by out() will be at most the window size. Any non-zero 00920 amount of input may be provided by in(). 00921 00922 For convenience, inflateBack() can be provided input on the first call by 00923 setting strm->next_in and strm->avail_in. If that input is exhausted, then 00924 in() will be called. Therefore strm->next_in must be initialized before 00925 calling inflateBack(). If strm->next_in is Z_NULL, then in() will be called 00926 immediately for input. If strm->next_in is not Z_NULL, then strm->avail_in 00927 must also be initialized, and then if strm->avail_in is not zero, input will 00928 initially be taken from strm->next_in[0 .. strm->avail_in - 1]. 00929 00930 The in_desc and out_desc parameters of inflateBack() is passed as the 00931 first parameter of in() and out() respectively when they are called. These 00932 descriptors can be optionally used to pass any information that the caller- 00933 supplied in() and out() functions need to do their job. 00934 00935 On return, inflateBack() will set strm->next_in and strm->avail_in to 00936 pass back any unused input that was provided by the last in() call. The 00937 return values of inflateBack() can be Z_STREAM_END on success, Z_BUF_ERROR 00938 if in() or out() returned an error, Z_DATA_ERROR if there was a format 00939 error in the deflate stream (in which case strm->msg is set to indicate the 00940 nature of the error), or Z_STREAM_ERROR if the stream was not properly 00941 initialized. In the case of Z_BUF_ERROR, an input or output error can be 00942 distinguished using strm->next_in which will be Z_NULL only if in() returned 00943 an error. If strm->next is not Z_NULL, then the Z_BUF_ERROR was due to 00944 out() returning non-zero. (in() will always be called before out(), so 00945 strm->next_in is assured to be defined if out() returns non-zero.) Note 00946 that inflateBack() cannot return Z_OK. 00947 */ 00948 00949 ZEXTERN int ZEXPORT inflateBackEnd OF((z_streamp strm)); 00950 /* 00951 All memory allocated by inflateBackInit() is freed. 00952 00953 inflateBackEnd() returns Z_OK on success, or Z_STREAM_ERROR if the stream 00954 state was inconsistent. 00955 */ 00956 00957 ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); 00958 /* Return flags indicating compile-time options. 00959 00960 Type sizes, two bits each, 00 = 16 bits, 01 = 32, 10 = 64, 11 = other: 00961 1.0: size of uInt 00962 3.2: size of uLong 00963 5.4: size of voidpf (pointer) 00964 7.6: size of z_off_t 00965 00966 Compiler, assembler, and debug options: 00967 8: DEBUG 00968 9: ASMV or ASMINF -- use ASM code 00969 10: ZLIB_WINAPI -- exported functions use the WINAPI calling convention 00970 11: 0 (reserved) 00971 00972 One-time table building (smaller code, but not thread-safe if true): 00973 12: BUILDFIXED -- build static block decoding tables when needed 00974 13: DYNAMIC_CRC_TABLE -- build CRC calculation tables when needed 00975 14,15: 0 (reserved) 00976 00977 Library content (indicates missing functionality): 00978 16: NO_GZCOMPRESS -- gz* functions cannot compress (to avoid linking 00979 deflate code when not needed) 00980 17: NO_GZIP -- deflate can't write gzip streams, and inflate can't detect 00981 and decode gzip streams (to avoid linking crc code) 00982 18-19: 0 (reserved) 00983 00984 Operation variations (changes in library functionality): 00985 20: PKZIP_BUG_WORKAROUND -- slightly more permissive inflate 00986 21: FASTEST -- deflate algorithm with only one, lowest compression level 00987 22,23: 0 (reserved) 00988 00989 The sprintf variant used by gzprintf (zero is best): 00990 24: 0 = vs*, 1 = s* -- 1 means limited to 20 arguments after the format 00991 25: 0 = *nprintf, 1 = *printf -- 1 means gzprintf() not secure! 00992 26: 0 = returns value, 1 = void -- 1 means inferred string length returned 00993 00994 Remainder: 00995 27-31: 0 (reserved) 00996 */ 00997 00998 00999 /* utility functions */ 01000 01001 /* 01002 The following utility functions are implemented on top of the 01003 basic stream-oriented functions. To simplify the interface, some 01004 default options are assumed (compression level and memory usage, 01005 standard memory allocation functions). The source code of these 01006 utility functions can easily be modified if you need special options. 01007 */ 01008 01009 ZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen, 01010 const Bytef *source, uLong sourceLen)); 01011 /* 01012 Compresses the source buffer into the destination buffer. sourceLen is 01013 the byte length of the source buffer. Upon entry, destLen is the total 01014 size of the destination buffer, which must be at least the value returned 01015 by compressBound(sourceLen). Upon exit, destLen is the actual size of the 01016 compressed buffer. 01017 This function can be used to compress a whole file at once if the 01018 input file is mmap'ed. 01019 compress returns Z_OK if success, Z_MEM_ERROR if there was not 01020 enough memory, Z_BUF_ERROR if there was not enough room in the output 01021 buffer. 01022 */ 01023 01024 ZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen, 01025 const Bytef *source, uLong sourceLen, 01026 int level)); 01027 /* 01028 Compresses the source buffer into the destination buffer. The level 01029 parameter has the same meaning as in deflateInit. sourceLen is the byte 01030 length of the source buffer. Upon entry, destLen is the total size of the 01031 destination buffer, which must be at least the value returned by 01032 compressBound(sourceLen). Upon exit, destLen is the actual size of the 01033 compressed buffer. 01034 01035 compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 01036 memory, Z_BUF_ERROR if there was not enough room in the output buffer, 01037 Z_STREAM_ERROR if the level parameter is invalid. 01038 */ 01039 01040 ZEXTERN uLong ZEXPORT compressBound OF((uLong sourceLen)); 01041 /* 01042 compressBound() returns an upper bound on the compressed size after 01043 compress() or compress2() on sourceLen bytes. It would be used before 01044 a compress() or compress2() call to allocate the destination buffer. 01045 */ 01046 01047 ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, 01048 const Bytef *source, uLong sourceLen)); 01049 /* 01050 Decompresses the source buffer into the destination buffer. sourceLen is 01051 the byte length of the source buffer. Upon entry, destLen is the total 01052 size of the destination buffer, which must be large enough to hold the 01053 entire uncompressed data. (The size of the uncompressed data must have 01054 been saved previously by the compressor and transmitted to the decompressor 01055 by some mechanism outside the scope of this compression library.) 01056 Upon exit, destLen is the actual size of the compressed buffer. 01057 This function can be used to decompress a whole file at once if the 01058 input file is mmap'ed. 01059 01060 uncompress returns Z_OK if success, Z_MEM_ERROR if there was not 01061 enough memory, Z_BUF_ERROR if there was not enough room in the output 01062 buffer, or Z_DATA_ERROR if the input data was corrupted or incomplete. 01063 */ 01064 01065 01066 typedef voidp gzFile; 01067 01068 ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); 01069 /* 01070 Opens a gzip (.gz) file for reading or writing. The mode parameter 01071 is as in fopen ("rb" or "wb") but can also include a compression level 01072 ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for 01073 Huffman only compression as in "wb1h", or 'R' for run-length encoding 01074 as in "wb1R". (See the description of deflateInit2 for more information 01075 about the strategy parameter.) 01076 01077 gzopen can be used to read a file which is not in gzip format; in this 01078 case gzread will directly read from the file without decompression. 01079 01080 gzopen returns NULL if the file could not be opened or if there was 01081 insufficient memory to allocate the (de)compression state; errno 01082 can be checked to distinguish the two cases (if errno is zero, the 01083 zlib error is Z_MEM_ERROR). */ 01084 01085 ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); 01086 /* 01087 gzdopen() associates a gzFile with the file descriptor fd. File 01088 descriptors are obtained from calls like open, dup, creat, pipe or 01089 fileno (in the file has been previously opened with fopen). 01090 The mode parameter is as in gzopen. 01091 The next call of gzclose on the returned gzFile will also close the 01092 file descriptor fd, just like fclose(fdopen(fd), mode) closes the file 01093 descriptor fd. If you want to keep fd open, use gzdopen(dup(fd), mode). 01094 gzdopen returns NULL if there was insufficient memory to allocate 01095 the (de)compression state. 01096 */ 01097 01098 ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); 01099 /* 01100 Dynamically update the compression level or strategy. See the description 01101 of deflateInit2 for the meaning of these parameters. 01102 gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not 01103 opened for writing. 01104 */ 01105 01106 ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); 01107 /* 01108 Reads the given number of uncompressed bytes from the compressed file. 01109 If the input file was not in gzip format, gzread copies the given number 01110 of bytes into the buffer. 01111 gzread returns the number of uncompressed bytes actually read (0 for 01112 end of file, -1 for error). */ 01113 01114 ZEXTERN int ZEXPORT gzwrite OF((gzFile file, 01115 voidpc buf, unsigned len)); 01116 /* 01117 Writes the given number of uncompressed bytes into the compressed file. 01118 gzwrite returns the number of uncompressed bytes actually written 01119 (0 in case of error). 01120 */ 01121 01122 ZEXTERN int ZEXPORTVA gzprintf OF((gzFile file, const char *format, ...)); 01123 /* 01124 Converts, formats, and writes the args to the compressed file under 01125 control of the format string, as in fprintf. gzprintf returns the number of 01126 uncompressed bytes actually written (0 in case of error). The number of 01127 uncompressed bytes written is limited to 4095. The caller should assure that 01128 this limit is not exceeded. If it is exceeded, then gzprintf() will return 01129 return an error (0) with nothing written. In this case, there may also be a 01130 buffer overflow with unpredictable consequences, which is possible only if 01131 zlib was compiled with the insecure functions sprintf() or vsprintf() 01132 because the secure snprintf() or vsnprintf() functions were not available. 01133 */ 01134 01135 ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); 01136 /* 01137 Writes the given null-terminated string to the compressed file, excluding 01138 the terminating null character. 01139 gzputs returns the number of characters written, or -1 in case of error. 01140 */ 01141 01142 ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); 01143 /* 01144 Reads bytes from the compressed file until len-1 characters are read, or 01145 a newline character is read and transferred to buf, or an end-of-file 01146 condition is encountered. The string is then terminated with a null 01147 character. 01148 gzgets returns buf, or Z_NULL in case of error. 01149 */ 01150 01151 ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c)); 01152 /* 01153 Writes c, converted to an unsigned char, into the compressed file. 01154 gzputc returns the value that was written, or -1 in case of error. 01155 */ 01156 01157 ZEXTERN int ZEXPORT gzgetc OF((gzFile file)); 01158 /* 01159 Reads one byte from the compressed file. gzgetc returns this byte 01160 or -1 in case of end of file or error. 01161 */ 01162 01163 ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); 01164 /* 01165 Push one character back onto the stream to be read again later. 01166 Only one character of push-back is allowed. gzungetc() returns the 01167 character pushed, or -1 on failure. gzungetc() will fail if a 01168 character has been pushed but not read yet, or if c is -1. The pushed 01169 character will be discarded if the stream is repositioned with gzseek() 01170 or gzrewind(). 01171 */ 01172 01173 ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); 01174 /* 01175 Flushes all pending output into the compressed file. The parameter 01176 flush is as in the deflate() function. The return value is the zlib 01177 error number (see function gzerror below). gzflush returns Z_OK if 01178 the flush parameter is Z_FINISH and all output could be flushed. 01179 gzflush should be called only when strictly necessary because it can 01180 degrade compression. 01181 */ 01182 01183 ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, 01184 z_off_t offset, int whence)); 01185 /* 01186 Sets the starting position for the next gzread or gzwrite on the 01187 given compressed file. The offset represents a number of bytes in the 01188 uncompressed data stream. The whence parameter is defined as in lseek(2); 01189 the value SEEK_END is not supported. 01190 If the file is opened for reading, this function is emulated but can be 01191 extremely slow. If the file is opened for writing, only forward seeks are 01192 supported; gzseek then compresses a sequence of zeroes up to the new 01193 starting position. 01194 01195 gzseek returns the resulting offset location as measured in bytes from 01196 the beginning of the uncompressed stream, or -1 in case of error, in 01197 particular if the file is opened for writing and the new starting position 01198 would be before the current position. 01199 */ 01200 01201 ZEXTERN int ZEXPORT gzrewind OF((gzFile file)); 01202 /* 01203 Rewinds the given file. This function is supported only for reading. 01204 01205 gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) 01206 */ 01207 01208 ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); 01209 /* 01210 Returns the starting position for the next gzread or gzwrite on the 01211 given compressed file. This position represents a number of bytes in the 01212 uncompressed data stream. 01213 01214 gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) 01215 */ 01216 01217 ZEXTERN int ZEXPORT gzeof OF((gzFile file)); 01218 /* 01219 Returns 1 when EOF has previously been detected reading the given 01220 input stream, otherwise zero. 01221 */ 01222 01223 ZEXTERN int ZEXPORT gzdirect OF((gzFile file)); 01224 /* 01225 Returns 1 if file is being read directly without decompression, otherwise 01226 zero. 01227 */ 01228 01229 ZEXTERN int ZEXPORT gzclose OF((gzFile file)); 01230 /* 01231 Flushes all pending output if necessary, closes the compressed file 01232 and deallocates all the (de)compression state. The return value is the zlib 01233 error number (see function gzerror below). 01234 */ 01235 01236 ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); 01237 /* 01238 Returns the error message for the last error which occurred on the 01239 given compressed file. errnum is set to zlib error number. If an 01240 error occurred in the file system and not in the compression library, 01241 errnum is set to Z_ERRNO and the application may consult errno 01242 to get the exact error code. 01243 */ 01244 01245 ZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); 01246 /* 01247 Clears the error and end-of-file flags for file. This is analogous to the 01248 clearerr() function in stdio. This is useful for continuing to read a gzip 01249 file that is being written concurrently. 01250 */ 01251 01252 /* checksum functions */ 01253 01254 /* 01255 These functions are not related to compression but are exported 01256 anyway because they might be useful in applications using the 01257 compression library. 01258 */ 01259 01260 ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); 01261 /* 01262 Update a running Adler-32 checksum with the bytes buf[0..len-1] and 01263 return the updated checksum. If buf is NULL, this function returns 01264 the required initial value for the checksum. 01265 An Adler-32 checksum is almost as reliable as a CRC32 but can be computed 01266 much faster. Usage example: 01267 01268 uLong adler = adler32(0L, Z_NULL, 0); 01269 01270 while (read_buffer(buffer, length) != EOF) { 01271 adler = adler32(adler, buffer, length); 01272 } 01273 if (adler != original_adler) error(); 01274 */ 01275 01276 ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, 01277 z_off_t len2)); 01278 /* 01279 Combine two Adler-32 checksums into one. For two sequences of bytes, seq1 01280 and seq2 with lengths len1 and len2, Adler-32 checksums were calculated for 01281 each, adler1 and adler2. adler32_combine() returns the Adler-32 checksum of 01282 seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. 01283 */ 01284 01285 ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); 01286 /* 01287 Update a running CRC-32 with the bytes buf[0..len-1] and return the 01288 updated CRC-32. If buf is NULL, this function returns the required initial 01289 value for the for the crc. Pre- and post-conditioning (one's complement) is 01290 performed within this function so it shouldn't be done by the application. 01291 Usage example: 01292 01293 uLong crc = crc32(0L, Z_NULL, 0); 01294 01295 while (read_buffer(buffer, length) != EOF) { 01296 crc = crc32(crc, buffer, length); 01297 } 01298 if (crc != original_crc) error(); 01299 */ 01300 01301 ZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); 01302 01303 /* 01304 Combine two CRC-32 check values into one. For two sequences of bytes, 01305 seq1 and seq2 with lengths len1 and len2, CRC-32 check values were 01306 calculated for each, crc1 and crc2. crc32_combine() returns the CRC-32 01307 check value of seq1 and seq2 concatenated, requiring only crc1, crc2, and 01308 len2. 01309 */ 01310 01311 01312 /* various hacks, don't look :) */ 01313 01314 /* deflateInit and inflateInit are macros to allow checking the zlib version 01315 * and the compiler's view of z_stream: 01316 */ 01317 ZEXTERN int ZEXPORT deflateInit_ OF((z_streamp strm, int level, 01318 const char *version, int stream_size)); 01319 ZEXTERN int ZEXPORT inflateInit_ OF((z_streamp strm, 01320 const char *version, int stream_size)); 01321 ZEXTERN int ZEXPORT deflateInit2_ OF((z_streamp strm, int level, int method, 01322 int windowBits, int memLevel, 01323 int strategy, const char *version, 01324 int stream_size)); 01325 ZEXTERN int ZEXPORT inflateInit2_ OF((z_streamp strm, int windowBits, 01326 const char *version, int stream_size)); 01327 ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, 01328 unsigned char FAR *window, 01329 const char *version, 01330 int stream_size)); 01331 #define deflateInit(strm, level) \ 01332 deflateInit_((strm), (level), ZLIB_VERSION, sizeof(z_stream)) 01333 #define inflateInit(strm) \ 01334 inflateInit_((strm), ZLIB_VERSION, sizeof(z_stream)) 01335 #define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ 01336 deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ 01337 (strategy), ZLIB_VERSION, sizeof(z_stream)) 01338 #define inflateInit2(strm, windowBits) \ 01339 inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) 01340 #define inflateBackInit(strm, windowBits, window) \ 01341 inflateBackInit_((strm), (windowBits), (window), \ 01342 ZLIB_VERSION, sizeof(z_stream)) 01343 01344 01345 #if !defined(ZUTIL_H) && !defined(NO_DUMMY_DECL) 01346 struct internal_state {int dummy;}; /* hack for buggy compilers */ 01347 #endif 01348 01349 ZEXTERN const char * ZEXPORT zError OF((int)); 01350 ZEXTERN int ZEXPORT inflateSyncPoint OF((z_streamp z)); 01351 ZEXTERN const uLongf * ZEXPORT get_crc_table OF((void)); 01352 01353 #ifdef __cplusplus 01354 } 01355 #endif 01356 01357 #endif /* ZLIB_H */