diff options
author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
commit | 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch) | |
tree | 0bba044c4ce775e45a88a51686b5d9f90697ea9d /include/linux/zlib.h |
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
Diffstat (limited to 'include/linux/zlib.h')
-rw-r--r-- | include/linux/zlib.h | 637 |
1 files changed, 637 insertions, 0 deletions
diff --git a/include/linux/zlib.h b/include/linux/zlib.h new file mode 100644 index 000000000000..850076ea14d3 --- /dev/null +++ b/include/linux/zlib.h | |||
@@ -0,0 +1,637 @@ | |||
1 | /* zlib.h -- interface of the 'zlib' general purpose compression library | ||
2 | version 1.1.3, July 9th, 1998 | ||
3 | |||
4 | Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler | ||
5 | |||
6 | This software is provided 'as-is', without any express or implied | ||
7 | warranty. In no event will the authors be held liable for any damages | ||
8 | arising from the use of this software. | ||
9 | |||
10 | Permission is granted to anyone to use this software for any purpose, | ||
11 | including commercial applications, and to alter it and redistribute it | ||
12 | freely, subject to the following restrictions: | ||
13 | |||
14 | 1. The origin of this software must not be misrepresented; you must not | ||
15 | claim that you wrote the original software. If you use this software | ||
16 | in a product, an acknowledgment in the product documentation would be | ||
17 | appreciated but is not required. | ||
18 | 2. Altered source versions must be plainly marked as such, and must not be | ||
19 | misrepresented as being the original software. | ||
20 | 3. This notice may not be removed or altered from any source distribution. | ||
21 | |||
22 | Jean-loup Gailly Mark Adler | ||
23 | jloup@gzip.org madler@alumni.caltech.edu | ||
24 | |||
25 | |||
26 | The data format used by the zlib library is described by RFCs (Request for | ||
27 | Comments) 1950 to 1952 in the files ftp://ds.internic.net/rfc/rfc1950.txt | ||
28 | (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). | ||
29 | */ | ||
30 | |||
31 | #ifndef _ZLIB_H | ||
32 | #define _ZLIB_H | ||
33 | |||
34 | #include <linux/zconf.h> | ||
35 | |||
36 | #define ZLIB_VERSION "1.1.3" | ||
37 | |||
38 | /* | ||
39 | The 'zlib' compression library provides in-memory compression and | ||
40 | decompression functions, including integrity checks of the uncompressed | ||
41 | data. This version of the library supports only one compression method | ||
42 | (deflation) but other algorithms will be added later and will have the same | ||
43 | stream interface. | ||
44 | |||
45 | Compression can be done in a single step if the buffers are large | ||
46 | enough (for example if an input file is mmap'ed), or can be done by | ||
47 | repeated calls of the compression function. In the latter case, the | ||
48 | application must provide more input and/or consume the output | ||
49 | (providing more output space) before each call. | ||
50 | |||
51 | The library also supports reading and writing files in gzip (.gz) format | ||
52 | with an interface similar to that of stdio. | ||
53 | |||
54 | The library does not install any signal handler. The decoder checks | ||
55 | the consistency of the compressed data, so the library should never | ||
56 | crash even in case of corrupted input. | ||
57 | */ | ||
58 | |||
59 | struct internal_state; | ||
60 | |||
61 | typedef struct z_stream_s { | ||
62 | Byte *next_in; /* next input byte */ | ||
63 | uInt avail_in; /* number of bytes available at next_in */ | ||
64 | uLong total_in; /* total nb of input bytes read so far */ | ||
65 | |||
66 | Byte *next_out; /* next output byte should be put there */ | ||
67 | uInt avail_out; /* remaining free space at next_out */ | ||
68 | uLong total_out; /* total nb of bytes output so far */ | ||
69 | |||
70 | char *msg; /* last error message, NULL if no error */ | ||
71 | struct internal_state *state; /* not visible by applications */ | ||
72 | |||
73 | void *workspace; /* memory allocated for this stream */ | ||
74 | |||
75 | int data_type; /* best guess about the data type: ascii or binary */ | ||
76 | uLong adler; /* adler32 value of the uncompressed data */ | ||
77 | uLong reserved; /* reserved for future use */ | ||
78 | } z_stream; | ||
79 | |||
80 | typedef z_stream *z_streamp; | ||
81 | |||
82 | /* | ||
83 | The application must update next_in and avail_in when avail_in has | ||
84 | dropped to zero. It must update next_out and avail_out when avail_out | ||
85 | has dropped to zero. The application must initialize zalloc, zfree and | ||
86 | opaque before calling the init function. All other fields are set by the | ||
87 | compression library and must not be updated by the application. | ||
88 | |||
89 | The opaque value provided by the application will be passed as the first | ||
90 | parameter for calls of zalloc and zfree. This can be useful for custom | ||
91 | memory management. The compression library attaches no meaning to the | ||
92 | opaque value. | ||
93 | |||
94 | zalloc must return NULL if there is not enough memory for the object. | ||
95 | If zlib is used in a multi-threaded application, zalloc and zfree must be | ||
96 | thread safe. | ||
97 | |||
98 | On 16-bit systems, the functions zalloc and zfree must be able to allocate | ||
99 | exactly 65536 bytes, but will not be required to allocate more than this | ||
100 | if the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS, | ||
101 | pointers returned by zalloc for objects of exactly 65536 bytes *must* | ||
102 | have their offset normalized to zero. The default allocation function | ||
103 | provided by this library ensures this (see zutil.c). To reduce memory | ||
104 | requirements and avoid any allocation of 64K objects, at the expense of | ||
105 | compression ratio, compile the library with -DMAX_WBITS=14 (see zconf.h). | ||
106 | |||
107 | The fields total_in and total_out can be used for statistics or | ||
108 | progress reports. After compression, total_in holds the total size of | ||
109 | the uncompressed data and may be saved for use in the decompressor | ||
110 | (particularly if the decompressor wants to decompress everything in | ||
111 | a single step). | ||
112 | */ | ||
113 | |||
114 | /* constants */ | ||
115 | |||
116 | #define Z_NO_FLUSH 0 | ||
117 | #define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ | ||
118 | #define Z_PACKET_FLUSH 2 | ||
119 | #define Z_SYNC_FLUSH 3 | ||
120 | #define Z_FULL_FLUSH 4 | ||
121 | #define Z_FINISH 5 | ||
122 | /* Allowed flush values; see deflate() below for details */ | ||
123 | |||
124 | #define Z_OK 0 | ||
125 | #define Z_STREAM_END 1 | ||
126 | #define Z_NEED_DICT 2 | ||
127 | #define Z_ERRNO (-1) | ||
128 | #define Z_STREAM_ERROR (-2) | ||
129 | #define Z_DATA_ERROR (-3) | ||
130 | #define Z_MEM_ERROR (-4) | ||
131 | #define Z_BUF_ERROR (-5) | ||
132 | #define Z_VERSION_ERROR (-6) | ||
133 | /* Return codes for the compression/decompression functions. Negative | ||
134 | * values are errors, positive values are used for special but normal events. | ||
135 | */ | ||
136 | |||
137 | #define Z_NO_COMPRESSION 0 | ||
138 | #define Z_BEST_SPEED 1 | ||
139 | #define Z_BEST_COMPRESSION 9 | ||
140 | #define Z_DEFAULT_COMPRESSION (-1) | ||
141 | /* compression levels */ | ||
142 | |||
143 | #define Z_FILTERED 1 | ||
144 | #define Z_HUFFMAN_ONLY 2 | ||
145 | #define Z_DEFAULT_STRATEGY 0 | ||
146 | /* compression strategy; see deflateInit2() below for details */ | ||
147 | |||
148 | #define Z_BINARY 0 | ||
149 | #define Z_ASCII 1 | ||
150 | #define Z_UNKNOWN 2 | ||
151 | /* Possible values of the data_type field */ | ||
152 | |||
153 | #define Z_DEFLATED 8 | ||
154 | /* The deflate compression method (the only one supported in this version) */ | ||
155 | |||
156 | /* basic functions */ | ||
157 | |||
158 | extern const char * zlib_zlibVersion (void); | ||
159 | /* The application can compare zlibVersion and ZLIB_VERSION for consistency. | ||
160 | If the first character differs, the library code actually used is | ||
161 | not compatible with the zlib.h header file used by the application. | ||
162 | This check is automatically made by deflateInit and inflateInit. | ||
163 | */ | ||
164 | |||
165 | extern int zlib_deflate_workspacesize (void); | ||
166 | /* | ||
167 | Returns the number of bytes that needs to be allocated for a per- | ||
168 | stream workspace. A pointer to this number of bytes should be | ||
169 | returned in stream->workspace before calling zlib_deflateInit(). | ||
170 | */ | ||
171 | |||
172 | /* | ||
173 | extern int deflateInit (z_streamp strm, int level); | ||
174 | |||
175 | Initializes the internal stream state for compression. The fields | ||
176 | zalloc, zfree and opaque must be initialized before by the caller. | ||
177 | If zalloc and zfree are set to NULL, deflateInit updates them to | ||
178 | use default allocation functions. | ||
179 | |||
180 | The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9: | ||
181 | 1 gives best speed, 9 gives best compression, 0 gives no compression at | ||
182 | all (the input data is simply copied a block at a time). | ||
183 | Z_DEFAULT_COMPRESSION requests a default compromise between speed and | ||
184 | compression (currently equivalent to level 6). | ||
185 | |||
186 | deflateInit returns Z_OK if success, Z_MEM_ERROR if there was not | ||
187 | enough memory, Z_STREAM_ERROR if level is not a valid compression level, | ||
188 | Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible | ||
189 | with the version assumed by the caller (ZLIB_VERSION). | ||
190 | msg is set to null if there is no error message. deflateInit does not | ||
191 | perform any compression: this will be done by deflate(). | ||
192 | */ | ||
193 | |||
194 | |||
195 | extern int zlib_deflate (z_streamp strm, int flush); | ||
196 | /* | ||
197 | deflate compresses as much data as possible, and stops when the input | ||
198 | buffer becomes empty or the output buffer becomes full. It may introduce some | ||
199 | output latency (reading input without producing any output) except when | ||
200 | forced to flush. | ||
201 | |||
202 | The detailed semantics are as follows. deflate performs one or both of the | ||
203 | following actions: | ||
204 | |||
205 | - Compress more input starting at next_in and update next_in and avail_in | ||
206 | accordingly. If not all input can be processed (because there is not | ||
207 | enough room in the output buffer), next_in and avail_in are updated and | ||
208 | processing will resume at this point for the next call of deflate(). | ||
209 | |||
210 | - Provide more output starting at next_out and update next_out and avail_out | ||
211 | accordingly. This action is forced if the parameter flush is non zero. | ||
212 | Forcing flush frequently degrades the compression ratio, so this parameter | ||
213 | should be set only when necessary (in interactive applications). | ||
214 | Some output may be provided even if flush is not set. | ||
215 | |||
216 | Before the call of deflate(), the application should ensure that at least | ||
217 | one of the actions is possible, by providing more input and/or consuming | ||
218 | more output, and updating avail_in or avail_out accordingly; avail_out | ||
219 | should never be zero before the call. The application can consume the | ||
220 | compressed output when it wants, for example when the output buffer is full | ||
221 | (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK | ||
222 | and with zero avail_out, it must be called again after making room in the | ||
223 | output buffer because there might be more output pending. | ||
224 | |||
225 | If the parameter flush is set to Z_SYNC_FLUSH, all pending output is | ||
226 | flushed to the output buffer and the output is aligned on a byte boundary, so | ||
227 | that the decompressor can get all input data available so far. (In particular | ||
228 | avail_in is zero after the call if enough output space has been provided | ||
229 | before the call.) Flushing may degrade compression for some compression | ||
230 | algorithms and so it should be used only when necessary. | ||
231 | |||
232 | If flush is set to Z_FULL_FLUSH, all output is flushed as with | ||
233 | Z_SYNC_FLUSH, and the compression state is reset so that decompression can | ||
234 | restart from this point if previous compressed data has been damaged or if | ||
235 | random access is desired. Using Z_FULL_FLUSH too often can seriously degrade | ||
236 | the compression. | ||
237 | |||
238 | If deflate returns with avail_out == 0, this function must be called again | ||
239 | with the same value of the flush parameter and more output space (updated | ||
240 | avail_out), until the flush is complete (deflate returns with non-zero | ||
241 | avail_out). | ||
242 | |||
243 | If the parameter flush is set to Z_FINISH, pending input is processed, | ||
244 | pending output is flushed and deflate returns with Z_STREAM_END if there | ||
245 | was enough output space; if deflate returns with Z_OK, this function must be | ||
246 | called again with Z_FINISH and more output space (updated avail_out) but no | ||
247 | more input data, until it returns with Z_STREAM_END or an error. After | ||
248 | deflate has returned Z_STREAM_END, the only possible operations on the | ||
249 | stream are deflateReset or deflateEnd. | ||
250 | |||
251 | Z_FINISH can be used immediately after deflateInit if all the compression | ||
252 | is to be done in a single step. In this case, avail_out must be at least | ||
253 | 0.1% larger than avail_in plus 12 bytes. If deflate does not return | ||
254 | Z_STREAM_END, then it must be called again as described above. | ||
255 | |||
256 | deflate() sets strm->adler to the adler32 checksum of all input read | ||
257 | so far (that is, total_in bytes). | ||
258 | |||
259 | deflate() may update data_type if it can make a good guess about | ||
260 | the input data type (Z_ASCII or Z_BINARY). In doubt, the data is considered | ||
261 | binary. This field is only for information purposes and does not affect | ||
262 | the compression algorithm in any manner. | ||
263 | |||
264 | deflate() returns Z_OK if some progress has been made (more input | ||
265 | processed or more output produced), Z_STREAM_END if all input has been | ||
266 | consumed and all output has been produced (only when flush is set to | ||
267 | Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example | ||
268 | if next_in or next_out was NULL), Z_BUF_ERROR if no progress is possible | ||
269 | (for example avail_in or avail_out was zero). | ||
270 | */ | ||
271 | |||
272 | |||
273 | extern int zlib_deflateEnd (z_streamp strm); | ||
274 | /* | ||
275 | All dynamically allocated data structures for this stream are freed. | ||
276 | This function discards any unprocessed input and does not flush any | ||
277 | pending output. | ||
278 | |||
279 | deflateEnd returns Z_OK if success, Z_STREAM_ERROR if the | ||
280 | stream state was inconsistent, Z_DATA_ERROR if the stream was freed | ||
281 | prematurely (some input or output was discarded). In the error case, | ||
282 | msg may be set but then points to a static string (which must not be | ||
283 | deallocated). | ||
284 | */ | ||
285 | |||
286 | |||
287 | extern int zlib_inflate_workspacesize (void); | ||
288 | /* | ||
289 | Returns the number of bytes that needs to be allocated for a per- | ||
290 | stream workspace. A pointer to this number of bytes should be | ||
291 | returned in stream->workspace before calling zlib_inflateInit(). | ||
292 | */ | ||
293 | |||
294 | /* | ||
295 | extern int zlib_inflateInit (z_streamp strm); | ||
296 | |||
297 | Initializes the internal stream state for decompression. The fields | ||
298 | next_in, avail_in, and workspace must be initialized before by | ||
299 | the caller. If next_in is not NULL and avail_in is large enough (the exact | ||
300 | value depends on the compression method), inflateInit determines the | ||
301 | compression method from the zlib header and allocates all data structures | ||
302 | accordingly; otherwise the allocation will be deferred to the first call of | ||
303 | inflate. If zalloc and zfree are set to NULL, inflateInit updates them to | ||
304 | use default allocation functions. | ||
305 | |||
306 | inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough | ||
307 | memory, Z_VERSION_ERROR if the zlib library version is incompatible with the | ||
308 | version assumed by the caller. msg is set to null if there is no error | ||
309 | message. inflateInit does not perform any decompression apart from reading | ||
310 | the zlib header if present: this will be done by inflate(). (So next_in and | ||
311 | avail_in may be modified, but next_out and avail_out are unchanged.) | ||
312 | */ | ||
313 | |||
314 | |||
315 | extern int zlib_inflate (z_streamp strm, int flush); | ||
316 | /* | ||
317 | inflate decompresses as much data as possible, and stops when the input | ||
318 | buffer becomes empty or the output buffer becomes full. It may some | ||
319 | introduce some output latency (reading input without producing any output) | ||
320 | except when forced to flush. | ||
321 | |||
322 | The detailed semantics are as follows. inflate performs one or both of the | ||
323 | following actions: | ||
324 | |||
325 | - Decompress more input starting at next_in and update next_in and avail_in | ||
326 | accordingly. If not all input can be processed (because there is not | ||
327 | enough room in the output buffer), next_in is updated and processing | ||
328 | will resume at this point for the next call of inflate(). | ||
329 | |||
330 | - Provide more output starting at next_out and update next_out and avail_out | ||
331 | accordingly. inflate() provides as much output as possible, until there | ||
332 | is no more input data or no more space in the output buffer (see below | ||
333 | about the flush parameter). | ||
334 | |||
335 | Before the call of inflate(), the application should ensure that at least | ||
336 | one of the actions is possible, by providing more input and/or consuming | ||
337 | more output, and updating the next_* and avail_* values accordingly. | ||
338 | The application can consume the uncompressed output when it wants, for | ||
339 | example when the output buffer is full (avail_out == 0), or after each | ||
340 | call of inflate(). If inflate returns Z_OK and with zero avail_out, it | ||
341 | must be called again after making room in the output buffer because there | ||
342 | might be more output pending. | ||
343 | |||
344 | If the parameter flush is set to Z_SYNC_FLUSH, inflate flushes as much | ||
345 | output as possible to the output buffer. The flushing behavior of inflate is | ||
346 | not specified for values of the flush parameter other than Z_SYNC_FLUSH | ||
347 | and Z_FINISH, but the current implementation actually flushes as much output | ||
348 | as possible anyway. | ||
349 | |||
350 | inflate() should normally be called until it returns Z_STREAM_END or an | ||
351 | error. However if all decompression is to be performed in a single step | ||
352 | (a single call of inflate), the parameter flush should be set to | ||
353 | Z_FINISH. In this case all pending input is processed and all pending | ||
354 | output is flushed; avail_out must be large enough to hold all the | ||
355 | uncompressed data. (The size of the uncompressed data may have been saved | ||
356 | by the compressor for this purpose.) The next operation on this stream must | ||
357 | be inflateEnd to deallocate the decompression state. The use of Z_FINISH | ||
358 | is never required, but can be used to inform inflate that a faster routine | ||
359 | may be used for the single inflate() call. | ||
360 | |||
361 | If a preset dictionary is needed at this point (see inflateSetDictionary | ||
362 | below), inflate sets strm-adler to the adler32 checksum of the | ||
363 | dictionary chosen by the compressor and returns Z_NEED_DICT; otherwise | ||
364 | it sets strm->adler to the adler32 checksum of all output produced | ||
365 | so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or | ||
366 | an error code as described below. At the end of the stream, inflate() | ||
367 | checks that its computed adler32 checksum is equal to that saved by the | ||
368 | compressor and returns Z_STREAM_END only if the checksum is correct. | ||
369 | |||
370 | inflate() returns Z_OK if some progress has been made (more input processed | ||
371 | or more output produced), Z_STREAM_END if the end of the compressed data has | ||
372 | been reached and all uncompressed output has been produced, Z_NEED_DICT if a | ||
373 | preset dictionary is needed at this point, Z_DATA_ERROR if the input data was | ||
374 | corrupted (input stream not conforming to the zlib format or incorrect | ||
375 | adler32 checksum), Z_STREAM_ERROR if the stream structure was inconsistent | ||
376 | (for example if next_in or next_out was NULL), Z_MEM_ERROR if there was not | ||
377 | enough memory, Z_BUF_ERROR if no progress is possible or if there was not | ||
378 | enough room in the output buffer when Z_FINISH is used. In the Z_DATA_ERROR | ||
379 | case, the application may then call inflateSync to look for a good | ||
380 | compression block. | ||
381 | */ | ||
382 | |||
383 | |||
384 | extern int zlib_inflateEnd (z_streamp strm); | ||
385 | /* | ||
386 | All dynamically allocated data structures for this stream are freed. | ||
387 | This function discards any unprocessed input and does not flush any | ||
388 | pending output. | ||
389 | |||
390 | inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state | ||
391 | was inconsistent. In the error case, msg may be set but then points to a | ||
392 | static string (which must not be deallocated). | ||
393 | */ | ||
394 | |||
395 | /* Advanced functions */ | ||
396 | |||
397 | /* | ||
398 | The following functions are needed only in some special applications. | ||
399 | */ | ||
400 | |||
401 | /* | ||
402 | extern int deflateInit2 (z_streamp strm, | ||
403 | int level, | ||
404 | int method, | ||
405 | int windowBits, | ||
406 | int memLevel, | ||
407 | int strategy); | ||
408 | |||
409 | This is another version of deflateInit with more compression options. The | ||
410 | fields next_in, zalloc, zfree and opaque must be initialized before by | ||
411 | the caller. | ||
412 | |||
413 | The method parameter is the compression method. It must be Z_DEFLATED in | ||
414 | this version of the library. | ||
415 | |||
416 | The windowBits parameter is the base two logarithm of the window size | ||
417 | (the size of the history buffer). It should be in the range 8..15 for this | ||
418 | version of the library. Larger values of this parameter result in better | ||
419 | compression at the expense of memory usage. The default value is 15 if | ||
420 | deflateInit is used instead. | ||
421 | |||
422 | The memLevel parameter specifies how much memory should be allocated | ||
423 | for the internal compression state. memLevel=1 uses minimum memory but | ||
424 | is slow and reduces compression ratio; memLevel=9 uses maximum memory | ||
425 | for optimal speed. The default value is 8. See zconf.h for total memory | ||
426 | usage as a function of windowBits and memLevel. | ||
427 | |||
428 | The strategy parameter is used to tune the compression algorithm. Use the | ||
429 | value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a | ||
430 | filter (or predictor), or Z_HUFFMAN_ONLY to force Huffman encoding only (no | ||
431 | string match). Filtered data consists mostly of small values with a | ||
432 | somewhat random distribution. In this case, the compression algorithm is | ||
433 | tuned to compress them better. The effect of Z_FILTERED is to force more | ||
434 | Huffman coding and less string matching; it is somewhat intermediate | ||
435 | between Z_DEFAULT and Z_HUFFMAN_ONLY. The strategy parameter only affects | ||
436 | the compression ratio but not the correctness of the compressed output even | ||
437 | if it is not set appropriately. | ||
438 | |||
439 | deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough | ||
440 | memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid | ||
441 | method). msg is set to null if there is no error message. deflateInit2 does | ||
442 | not perform any compression: this will be done by deflate(). | ||
443 | */ | ||
444 | |||
445 | extern int zlib_deflateSetDictionary (z_streamp strm, | ||
446 | const Byte *dictionary, | ||
447 | uInt dictLength); | ||
448 | /* | ||
449 | Initializes the compression dictionary from the given byte sequence | ||
450 | without producing any compressed output. This function must be called | ||
451 | immediately after deflateInit, deflateInit2 or deflateReset, before any | ||
452 | call of deflate. The compressor and decompressor must use exactly the same | ||
453 | dictionary (see inflateSetDictionary). | ||
454 | |||
455 | The dictionary should consist of strings (byte sequences) that are likely | ||
456 | to be encountered later in the data to be compressed, with the most commonly | ||
457 | used strings preferably put towards the end of the dictionary. Using a | ||
458 | dictionary is most useful when the data to be compressed is short and can be | ||
459 | predicted with good accuracy; the data can then be compressed better than | ||
460 | with the default empty dictionary. | ||
461 | |||
462 | Depending on the size of the compression data structures selected by | ||
463 | deflateInit or deflateInit2, a part of the dictionary may in effect be | ||
464 | discarded, for example if the dictionary is larger than the window size in | ||
465 | deflate or deflate2. Thus the strings most likely to be useful should be | ||
466 | put at the end of the dictionary, not at the front. | ||
467 | |||
468 | Upon return of this function, strm->adler is set to the Adler32 value | ||
469 | of the dictionary; the decompressor may later use this value to determine | ||
470 | which dictionary has been used by the compressor. (The Adler32 value | ||
471 | applies to the whole dictionary even if only a subset of the dictionary is | ||
472 | actually used by the compressor.) | ||
473 | |||
474 | deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a | ||
475 | parameter is invalid (such as NULL dictionary) or the stream state is | ||
476 | inconsistent (for example if deflate has already been called for this stream | ||
477 | or if the compression method is bsort). deflateSetDictionary does not | ||
478 | perform any compression: this will be done by deflate(). | ||
479 | */ | ||
480 | |||
481 | extern int zlib_deflateCopy (z_streamp dest, z_streamp source); | ||
482 | /* | ||
483 | Sets the destination stream as a complete copy of the source stream. | ||
484 | |||
485 | This function can be useful when several compression strategies will be | ||
486 | tried, for example when there are several ways of pre-processing the input | ||
487 | data with a filter. The streams that will be discarded should then be freed | ||
488 | by calling deflateEnd. Note that deflateCopy duplicates the internal | ||
489 | compression state which can be quite large, so this strategy is slow and | ||
490 | can consume lots of memory. | ||
491 | |||
492 | deflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not | ||
493 | enough memory, Z_STREAM_ERROR if the source stream state was inconsistent | ||
494 | (such as zalloc being NULL). msg is left unchanged in both source and | ||
495 | destination. | ||
496 | */ | ||
497 | |||
498 | extern int zlib_deflateReset (z_streamp strm); | ||
499 | /* | ||
500 | This function is equivalent to deflateEnd followed by deflateInit, | ||
501 | but does not free and reallocate all the internal compression state. | ||
502 | The stream will keep the same compression level and any other attributes | ||
503 | that may have been set by deflateInit2. | ||
504 | |||
505 | deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source | ||
506 | stream state was inconsistent (such as zalloc or state being NULL). | ||
507 | */ | ||
508 | |||
509 | extern int zlib_deflateParams (z_streamp strm, int level, int strategy); | ||
510 | /* | ||
511 | Dynamically update the compression level and compression strategy. The | ||
512 | interpretation of level and strategy is as in deflateInit2. This can be | ||
513 | used to switch between compression and straight copy of the input data, or | ||
514 | to switch to a different kind of input data requiring a different | ||
515 | strategy. If the compression level is changed, the input available so far | ||
516 | is compressed with the old level (and may be flushed); the new level will | ||
517 | take effect only at the next call of deflate(). | ||
518 | |||
519 | Before the call of deflateParams, the stream state must be set as for | ||
520 | a call of deflate(), since the currently available input may have to | ||
521 | be compressed and flushed. In particular, strm->avail_out must be non-zero. | ||
522 | |||
523 | deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source | ||
524 | stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR | ||
525 | if strm->avail_out was zero. | ||
526 | */ | ||
527 | |||
528 | /* | ||
529 | extern int inflateInit2 (z_streamp strm, int windowBits); | ||
530 | |||
531 | This is another version of inflateInit with an extra parameter. The | ||
532 | fields next_in, avail_in, zalloc, zfree and opaque must be initialized | ||
533 | before by the caller. | ||
534 | |||
535 | The windowBits parameter is the base two logarithm of the maximum window | ||
536 | size (the size of the history buffer). It should be in the range 8..15 for | ||
537 | this version of the library. The default value is 15 if inflateInit is used | ||
538 | instead. If a compressed stream with a larger window size is given as | ||
539 | input, inflate() will return with the error code Z_DATA_ERROR instead of | ||
540 | trying to allocate a larger window. | ||
541 | |||
542 | inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough | ||
543 | memory, Z_STREAM_ERROR if a parameter is invalid (such as a negative | ||
544 | memLevel). msg is set to null if there is no error message. inflateInit2 | ||
545 | does not perform any decompression apart from reading the zlib header if | ||
546 | present: this will be done by inflate(). (So next_in and avail_in may be | ||
547 | modified, but next_out and avail_out are unchanged.) | ||
548 | */ | ||
549 | |||
550 | extern int zlib_inflateSetDictionary (z_streamp strm, | ||
551 | const Byte *dictionary, | ||
552 | uInt dictLength); | ||
553 | /* | ||
554 | Initializes the decompression dictionary from the given uncompressed byte | ||
555 | sequence. This function must be called immediately after a call of inflate | ||
556 | if this call returned Z_NEED_DICT. The dictionary chosen by the compressor | ||
557 | can be determined from the Adler32 value returned by this call of | ||
558 | inflate. The compressor and decompressor must use exactly the same | ||
559 | dictionary (see deflateSetDictionary). | ||
560 | |||
561 | inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a | ||
562 | parameter is invalid (such as NULL dictionary) or the stream state is | ||
563 | inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the | ||
564 | expected one (incorrect Adler32 value). inflateSetDictionary does not | ||
565 | perform any decompression: this will be done by subsequent calls of | ||
566 | inflate(). | ||
567 | */ | ||
568 | |||
569 | extern int zlib_inflateSync (z_streamp strm); | ||
570 | /* | ||
571 | Skips invalid compressed data until a full flush point (see above the | ||
572 | description of deflate with Z_FULL_FLUSH) can be found, or until all | ||
573 | available input is skipped. No output is provided. | ||
574 | |||
575 | inflateSync returns Z_OK if a full flush point has been found, Z_BUF_ERROR | ||
576 | if no more input was provided, Z_DATA_ERROR if no flush point has been found, | ||
577 | or Z_STREAM_ERROR if the stream structure was inconsistent. In the success | ||
578 | case, the application may save the current current value of total_in which | ||
579 | indicates where valid compressed data was found. In the error case, the | ||
580 | application may repeatedly call inflateSync, providing more input each time, | ||
581 | until success or end of the input data. | ||
582 | */ | ||
583 | |||
584 | extern int zlib_inflateReset (z_streamp strm); | ||
585 | /* | ||
586 | This function is equivalent to inflateEnd followed by inflateInit, | ||
587 | but does not free and reallocate all the internal decompression state. | ||
588 | The stream will keep attributes that may have been set by inflateInit2. | ||
589 | |||
590 | inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source | ||
591 | stream state was inconsistent (such as zalloc or state being NULL). | ||
592 | */ | ||
593 | |||
594 | extern int zlib_inflateIncomp (z_stream *strm); | ||
595 | /* | ||
596 | This function adds the data at next_in (avail_in bytes) to the output | ||
597 | history without performing any output. There must be no pending output, | ||
598 | and the decompressor must be expecting to see the start of a block. | ||
599 | Calling this function is equivalent to decompressing a stored block | ||
600 | containing the data at next_in (except that the data is not output). | ||
601 | */ | ||
602 | |||
603 | /* various hacks, don't look :) */ | ||
604 | |||
605 | /* deflateInit and inflateInit are macros to allow checking the zlib version | ||
606 | * and the compiler's view of z_stream: | ||
607 | */ | ||
608 | extern int zlib_deflateInit_ (z_streamp strm, int level, | ||
609 | const char *version, int stream_size); | ||
610 | extern int zlib_inflateInit_ (z_streamp strm, | ||
611 | const char *version, int stream_size); | ||
612 | extern int zlib_deflateInit2_ (z_streamp strm, int level, int method, | ||
613 | int windowBits, int memLevel, | ||
614 | int strategy, const char *version, | ||
615 | int stream_size); | ||
616 | extern int zlib_inflateInit2_ (z_streamp strm, int windowBits, | ||
617 | const char *version, int stream_size); | ||
618 | #define zlib_deflateInit(strm, level) \ | ||
619 | zlib_deflateInit_((strm), (level), ZLIB_VERSION, sizeof(z_stream)) | ||
620 | #define zlib_inflateInit(strm) \ | ||
621 | zlib_inflateInit_((strm), ZLIB_VERSION, sizeof(z_stream)) | ||
622 | #define zlib_deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ | ||
623 | zlib_deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ | ||
624 | (strategy), ZLIB_VERSION, sizeof(z_stream)) | ||
625 | #define zlib_inflateInit2(strm, windowBits) \ | ||
626 | zlib_inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) | ||
627 | |||
628 | |||
629 | #if !defined(_Z_UTIL_H) && !defined(NO_DUMMY_DECL) | ||
630 | struct internal_state {int dummy;}; /* hack for buggy compilers */ | ||
631 | #endif | ||
632 | |||
633 | extern const char * zlib_zError (int err); | ||
634 | extern int zlib_inflateSyncPoint (z_streamp z); | ||
635 | extern const uLong * zlib_get_crc_table (void); | ||
636 | |||
637 | #endif /* _ZLIB_H */ | ||