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

source code of boost/libs/beast/include/boost/beast/zlib/deflate_stream.hpp