]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com) | |
3 | // | |
4 | // Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | // | |
7 | // This is a derivative work based on Zlib, copyright below: | |
8 | /* | |
9 | Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler | |
10 | ||
11 | This software is provided 'as-is', without any express or implied | |
12 | warranty. In no event will the authors be held liable for any damages | |
13 | arising from the use of this software. | |
14 | ||
15 | Permission is granted to anyone to use this software for any purpose, | |
16 | including commercial applications, and to alter it and redistribute it | |
17 | freely, subject to the following restrictions: | |
18 | ||
19 | 1. The origin of this software must not be misrepresented; you must not | |
20 | claim that you wrote the original software. If you use this software | |
21 | in a product, an acknowledgment in the product documentation would be | |
22 | appreciated but is not required. | |
23 | 2. Altered source versions must be plainly marked as such, and must not be | |
24 | misrepresented as being the original software. | |
25 | 3. This notice may not be removed or altered from any source distribution. | |
26 | ||
27 | Jean-loup Gailly Mark Adler | |
28 | jloup@gzip.org madler@alumni.caltech.edu | |
29 | ||
30 | The data format used by the zlib library is described by RFCs (Request for | |
31 | Comments) 1950 to 1952 in the files http://tools.ietf.org/html/rfc1950 | |
32 | (zlib format), rfc1951 (deflate format) and rfc1952 (gzip format). | |
33 | */ | |
34 | ||
35 | #ifndef BEAST_ZLIB_DEFLATE_STREAM_HPP | |
36 | #define BEAST_ZLIB_DEFLATE_STREAM_HPP | |
37 | ||
38 | #include <beast/config.hpp> | |
39 | #include <beast/zlib/error.hpp> | |
40 | #include <beast/zlib/zlib.hpp> | |
41 | #include <beast/zlib/detail/deflate_stream.hpp> | |
42 | #include <algorithm> | |
43 | #include <cstdlib> | |
44 | #include <cstdint> | |
45 | #include <cstring> | |
46 | #include <memory> | |
47 | ||
48 | namespace beast { | |
49 | namespace zlib { | |
50 | ||
51 | /** Raw deflate compressor. | |
52 | ||
53 | This is a port of zlib's "deflate" functionality to C++. | |
54 | */ | |
55 | class deflate_stream | |
56 | : private detail::deflate_stream | |
57 | { | |
58 | public: | |
59 | /** Construct a default deflate stream. | |
60 | ||
61 | Upon construction, the stream settings will be set | |
62 | to these default values: | |
63 | ||
64 | @li `level = 6` | |
65 | ||
66 | @li `windowBits = 15` | |
67 | ||
68 | @li `memLevel = 8` | |
69 | ||
70 | @li `strategy = Strategy::normal` | |
71 | ||
72 | Although the stream is ready to be used immediately | |
73 | after construction, any required internal buffers are | |
74 | not dynamically allocated until needed. | |
75 | */ | |
76 | deflate_stream() | |
77 | { | |
78 | reset(6, 15, DEF_MEM_LEVEL, Strategy::normal); | |
79 | } | |
80 | ||
81 | /** Reset the stream and compression settings. | |
82 | ||
83 | This function initializes the stream to the specified | |
84 | compression settings. | |
85 | ||
86 | Although the stream is ready to be used immediately | |
87 | after a reset, any required internal buffers are not | |
88 | dynamically allocated until needed. | |
89 | ||
90 | @note Any unprocessed input or pending output from | |
91 | previous calls are discarded. | |
92 | */ | |
93 | void | |
94 | reset( | |
95 | int level, | |
96 | int windowBits, | |
97 | int memLevel, | |
98 | Strategy strategy) | |
99 | { | |
100 | doReset(level, windowBits, memLevel, strategy); | |
101 | } | |
102 | ||
103 | /** Reset the stream without deallocating memory. | |
104 | ||
105 | This function performs the equivalent of calling `clear` | |
106 | followed by `reset` with the same compression settings, | |
107 | without deallocating the internal buffers. | |
108 | ||
109 | @note Any unprocessed input or pending output from | |
110 | previous calls are discarded. | |
111 | */ | |
112 | void | |
113 | reset() | |
114 | { | |
115 | doReset(); | |
116 | } | |
117 | ||
118 | /** Clear the stream. | |
119 | ||
120 | This function resets the stream and frees all dynamically | |
121 | allocated internal buffers. The compression settings are | |
122 | left unchanged. | |
123 | ||
124 | @note Any unprocessed input or pending output from | |
125 | previous calls are discarded. | |
126 | */ | |
127 | void | |
128 | clear() | |
129 | { | |
130 | doClear(); | |
131 | } | |
132 | ||
133 | /** Returns the upper limit on the size of a compressed block. | |
134 | ||
135 | This function makes a conservative estimate of the maximum number | |
136 | of bytes needed to store the result of compressing a block of | |
137 | data based on the current compression level and strategy. | |
138 | ||
139 | @param sourceLen The size of the uncompressed data. | |
140 | ||
141 | @return The maximum number of resulting compressed bytes. | |
142 | */ | |
143 | std::size_t | |
144 | upper_bound(std::size_t sourceLen) const | |
145 | { | |
146 | return doUpperBound(sourceLen); | |
147 | } | |
148 | ||
149 | /** Fine tune internal compression parameters. | |
150 | ||
151 | Compression parameters should only be tuned by someone who | |
152 | understands the algorithm used by zlib's deflate for searching | |
153 | for the best matching string, and even then only by the most | |
154 | fanatic optimizer trying to squeeze out the last compressed bit | |
155 | for their specific input data. Read the deflate.c source code | |
156 | (ZLib) for the meaning of the max_lazy, good_length, nice_length, | |
157 | and max_chain parameters. | |
158 | */ | |
159 | void | |
160 | tune( | |
161 | int good_length, | |
162 | int max_lazy, | |
163 | int nice_length, | |
164 | int max_chain) | |
165 | { | |
166 | doTune(good_length, max_lazy, nice_length, max_chain); | |
167 | } | |
168 | ||
169 | /** Compress input and write output. | |
170 | ||
171 | This function compresses as much data as possible, and stops when | |
172 | the input buffer becomes empty or the output buffer becomes full. | |
173 | It may introduce some output latency (reading input without | |
174 | producing any output) except when forced to flush. | |
175 | ||
176 | In each call, one or both of these actions are performed: | |
177 | ||
178 | @li Compress more input starting at `zs.next_in` and update | |
179 | `zs.next_in` and `zs.avail_in` accordingly. If not all | |
180 | input can be processed (because there is not enough room in | |
181 | the output buffer), `zs.next_in` and `zs.avail_in` are updated | |
182 | and processing will resume at this point for the next call. | |
183 | ||
184 | @li Provide more output starting at `zs.next_out` and update | |
185 | `zs.next_out` and `zs.avail_out` accordingly. This action is | |
186 | forced if the parameter flush is not `Flush::none`. Forcing | |
187 | flush frequently degrades the compression ratio, so this parameter | |
188 | should be set only when necessary (in interactive applications). | |
189 | Some output may be provided even if flush is not set. | |
190 | ||
191 | Before the call, the application must ensure that at least one | |
192 | of the actions is possible, by providing more input and/or | |
193 | consuming more output, and updating `zs.avail_in` or `zs.avail_out` | |
194 | accordingly; `zs.avail_out` should never be zero before the call. | |
195 | The application can consume the compressed output when it wants, | |
196 | for example when the output buffer is full (`zs.avail_out == 0`), | |
197 | or after each call of `write`. If `write` returns no error | |
198 | with zero `zs.avail_out`, it must be called again after making | |
199 | room in the output buffer because there might be more output | |
200 | pending. | |
201 | ||
202 | Normally the parameter flush is set to `Flush::none`, which allows | |
203 | deflate to decide how much data to accumulate before producing | |
204 | output, in order to maximize compression. | |
205 | ||
206 | If the parameter flush is set to `Flush::sync`, all pending output | |
207 | is flushed to the output buffer and the output is aligned on a | |
208 | byte boundary, so that the decompressor can get all input data | |
209 | available so far. In particular `zs.avail_in` is zero after the | |
210 | call if enough output space has been provided before the call. | |
211 | Flushing may degrade compression for some compression algorithms | |
212 | and so it should be used only when necessary. This completes the | |
213 | current deflate block and follows it with an empty stored block | |
214 | that is three bits plus filler bits to the next byte, followed | |
215 | by the four bytes `{ 0x00, 0x00 0xff 0xff }`. | |
216 | ||
217 | If flush is set to `Flush::partial`, all pending output is flushed | |
218 | to the output buffer, but the output is not aligned to a byte | |
219 | boundary. All of the input data so far will be available to the | |
220 | decompressor, as for Z_SYNC_FLUSH. This completes the current | |
221 | deflate block and follows it with an empty fixed codes block that | |
222 | is 10 bits long. This assures that enough bytes are output in order | |
223 | for the decompressor to finish the block before the empty fixed | |
224 | code block. | |
225 | ||
226 | If flush is set to `Flush::block`, a deflate block is completed | |
227 | and emitted, as for `Flush::sync`, but the output is not aligned | |
228 | on a byte boundary, and up to seven bits of the current block are | |
229 | held to be written as the next byte after the next deflate block | |
230 | is completed. In this case, the decompressor may not be provided | |
231 | enough bits at this point in order to complete decompression of | |
232 | the data provided so far to the compressor. It may need to wait | |
233 | for the next block to be emitted. This is for advanced applications | |
234 | that need to control the emission of deflate blocks. | |
235 | ||
236 | If flush is set to `Flush::full`, all output is flushed as with | |
237 | `Flush::sync`, and the compression state is reset so that | |
238 | decompression can restart from this point if previous compressed | |
239 | data has been damaged or if random access is desired. Using | |
240 | `Flush::full` too often can seriously degrade compression. | |
241 | ||
242 | If `write` returns with `zs.avail_out == 0`, this function must | |
243 | be called again with the same value of the flush parameter and | |
244 | more output space (updated `zs.avail_out`), until the flush is | |
245 | complete (`write` returns with non-zero `zs.avail_out`). In the | |
246 | case of a `Flush::full`or `Flush::sync`, make sure that | |
247 | `zs.avail_out` is greater than six to avoid repeated flush markers | |
248 | due to `zs.avail_out == 0` on return. | |
249 | ||
250 | If the parameter flush is set to `Flush::finish`, pending input | |
251 | is processed, pending output is flushed and deflate returns the | |
252 | error `error::end_of_stream` if there was enough output space; | |
253 | if deflate returns with no error, this function must be called | |
254 | again with `Flush::finish` and more output space (updated | |
255 | `zs.avail_out`) but no more input data, until it returns the | |
256 | error `error::end_of_stream` or another error. After `write` has | |
257 | returned the `error::end_of_stream` error, the only possible | |
258 | operations on the stream are to reset or destroy. | |
259 | ||
260 | `Flush::finish` can be used immediately after initialization | |
261 | if all the compression is to be done in a single step. In this | |
262 | case, `zs.avail_out` must be at least value returned by | |
263 | `upper_bound` (see below). Then `write` is guaranteed to return | |
264 | the `error::end_of_stream` error. If not enough output space | |
265 | is provided, deflate will not return `error::end_of_stream`, | |
266 | and it must be called again as described above. | |
267 | ||
268 | `write` returns no error if some progress has been made (more | |
269 | input processed or more output produced), `error::end_of_stream` | |
270 | if all input has been consumed and all output has been produced | |
271 | (only when flush is set to `Flush::finish`), `error::stream_error` | |
272 | if the stream state was inconsistent (for example if `zs.next_in` | |
273 | or `zs.next_out` was `nullptr`), `error::need_buffers` if no | |
274 | progress is possible (for example `zs.avail_in` or `zs.avail_out` | |
275 | was zero). Note that `error::need_buffers` is not fatal, and | |
276 | `write` can be called again with more input and more output space | |
277 | to continue compressing. | |
278 | */ | |
279 | void | |
280 | write( | |
281 | z_params& zs, | |
282 | Flush flush, | |
283 | error_code& ec) | |
284 | { | |
285 | doWrite(zs, flush, ec); | |
286 | } | |
287 | ||
288 | /** Update the compression level and strategy. | |
289 | ||
290 | This function dynamically updates the compression level and | |
291 | compression strategy. The interpretation of level and strategy | |
292 | is as in @ref reset. This can be used to switch between compression | |
293 | and straight copy of the input data, or to switch to a different kind | |
294 | of input data requiring a different strategy. If the compression level | |
295 | is changed, the input available so far is compressed with the old level | |
296 | (and may be flushed); the new level will take effect only at the next | |
297 | call of @ref write. | |
298 | ||
299 | Before the call of `params`, the stream state must be set as for a | |
300 | call of @ref write, since the currently available input may have to be | |
301 | compressed and flushed. In particular, `zs.avail_out` must be non-zero. | |
302 | ||
303 | @return `Z_OK` if success, `Z_STREAM_ERROR` if the source stream state | |
304 | was inconsistent or if a parameter was invalid, `error::need_buffers` | |
305 | if `zs.avail_out` was zero. | |
306 | */ | |
307 | void | |
308 | params( | |
309 | z_params& zs, | |
310 | int level, | |
311 | Strategy strategy, | |
312 | error_code& ec) | |
313 | { | |
314 | doParams(zs, level, strategy, ec); | |
315 | } | |
316 | ||
317 | /** Return bits pending in the output. | |
318 | ||
319 | This function returns the number of bytes and bits of output | |
320 | that have been generated, but not yet provided in the available | |
321 | output. The bytes not provided would be due to the available | |
322 | output space having being consumed. The number of bits of output | |
323 | not provided are between 0 and 7, where they await more bits to | |
324 | join them in order to fill out a full byte. If pending or bits | |
325 | are `nullptr`, then those values are not set. | |
326 | ||
327 | @return `Z_OK` if success, or `Z_STREAM_ERROR` if the source | |
328 | stream state was inconsistent. | |
329 | */ | |
330 | void | |
331 | pending(unsigned *value, int *bits) | |
332 | { | |
333 | doPending(value, bits); | |
334 | } | |
335 | ||
336 | /** Insert bits into the compressed output stream. | |
337 | ||
338 | This function inserts bits in the deflate output stream. The | |
339 | intent is that this function is used to start off the deflate | |
340 | output with the bits leftover from a previous deflate stream when | |
341 | appending to it. As such, this function can only be used for raw | |
342 | deflate, and must be used before the first `write` call after an | |
343 | initialization. `bits` must be less than or equal to 16, and that | |
344 | many of the least significant bits of `value` will be inserted in | |
345 | the output. | |
346 | ||
347 | @return `error::need_buffers` if there was not enough room in | |
348 | the internal buffer to insert the bits. | |
349 | */ | |
350 | void | |
351 | prime(int bits, int value, error_code& ec) | |
352 | { | |
353 | return doPrime(bits, value, ec); | |
354 | } | |
355 | }; | |
356 | ||
357 | /** Returns the upper limit on the size of a compressed block. | |
358 | ||
359 | This function makes a conservative estimate of the maximum number | |
360 | of bytes needed to store the result of compressing a block of | |
361 | data. | |
362 | ||
363 | @param bytes The size of the uncompressed data. | |
364 | ||
365 | @return The maximum number of resulting compressed bytes. | |
366 | */ | |
367 | std::size_t | |
368 | deflate_upper_bound(std::size_t bytes); | |
369 | ||
370 | /* For the default windowBits of 15 and memLevel of 8, this function returns | |
371 | a close to exact, as well as small, upper bound on the compressed size. | |
372 | They are coded as constants here for a reason--if the #define's are | |
373 | changed, then this function needs to be changed as well. The return | |
374 | value for 15 and 8 only works for those exact settings. | |
375 | ||
376 | For any setting other than those defaults for windowBits and memLevel, | |
377 | the value returned is a conservative worst case for the maximum expansion | |
378 | resulting from using fixed blocks instead of stored blocks, which deflate | |
379 | can emit on compressed data for some combinations of the parameters. | |
380 | ||
381 | This function could be more sophisticated to provide closer upper bounds for | |
382 | every combination of windowBits and memLevel. But even the conservative | |
383 | upper bound of about 14% expansion does not seem onerous for output buffer | |
384 | allocation. | |
385 | */ | |
386 | inline | |
387 | std::size_t | |
388 | deflate_upper_bound(std::size_t bytes) | |
389 | { | |
390 | return bytes + | |
391 | ((bytes + 7) >> 3) + | |
392 | ((bytes + 63) >> 6) + 5 + | |
393 | 6; | |
394 | } | |
395 | ||
396 | } // zlib | |
397 | } // beast | |
398 | ||
399 | #endif |