ceph/src/boost/boost/beast/zlib/inflate_stream.hpp

   1 //
   2 // Copyright (c) 2016-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 // Official repository: https://github.com/boostorg/beast
   8 //
   9
  10 #ifndef BOOST_BEAST_ZLIB_INFLATE_STREAM_HPP
  11 #define BOOST_BEAST_ZLIB_INFLATE_STREAM_HPP
  12
  13 #include <boost/beast/core/detail/config.hpp>
  14 #include <boost/beast/zlib/detail/inflate_stream.hpp>
  15
  16 // This is a derivative work based on Zlib, copyright below:
  17 /*
  18     Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler
  19
  20     This software is provided 'as-is', without any express or implied
  21     warranty.  In no event will the authors be held liable for any damages
  22     arising from the use of this software.
  23
  24     Permission is granted to anyone to use this software for any purpose,
  25     including commercial applications, and to alter it and redistribute it
  26     freely, subject to the following restrictions:
  27
  28     1. The origin of this software must not be misrepresented; you must not
  29        claim that you wrote the original software. If you use this software
  30        in a product, an acknowledgment in the product documentation would be
  31        appreciated but is not required.
  32     2. Altered source versions must be plainly marked as such, and must not be
  33        misrepresented as being the original software.
  34     3. This notice may not be removed or altered from any source distribution.
  35
  36     Jean-loup Gailly        Mark Adler
  37     jloup@gzip.org          madler@alumni.caltech.edu
  38
  39     The data format used by the zlib library is described by RFCs (Request for
  40     Comments) 1950 to 1952 in the files http://tools.ietf.org/html/rfc1950
  41     (zlib format), rfc1951 (deflate format) and rfc1952 (gzip format).
  42 */
  43
  44 namespace boost {
  45 namespace beast {
  46 namespace zlib {
  47
  48 /** Raw deflate stream decompressor.
  49
  50     This implements a raw deflate stream decompressor. The deflate
  51     protocol is a compression protocol described in
  52     "DEFLATE Compressed Data Format Specification version 1.3"
  53     located here: https://tools.ietf.org/html/rfc1951
  54
  55     The implementation is a refactored port to C++ of ZLib's "inflate".
  56     A more detailed description of ZLib is at http://zlib.net/.
  57
  58     Compression can be done in a single step if the buffers are large
  59     enough (for example if an input file is memory mapped), or can be done
  60     by repeated calls of the compression function. In the latter case, the
  61     application must provide more input and/or consume the output (providing
  62     more output space) before each call.
  63 */
  64 class inflate_stream
  65     : private detail::inflate_stream
  66 {
  67 public:
  68     /** Construct a raw deflate decompression stream.
  69
  70         The window size is set to the default of 15 bits.
  71     */
  72     inflate_stream() = default;
  73
  74     /** Reset the stream.
  75
  76         This puts the stream in a newly constructed state with
  77         the previously specified window size, but without de-allocating
  78         any dynamically created structures.
  79     */
  80     void
  81     reset()
  82     {
  83         doReset();
  84     }
  85
  86     /** Reset the stream.
  87
  88         This puts the stream in a newly constructed state with the
  89         specified window size, but without de-allocating any dynamically
  90         created structures.
  91     */
  92     void
  93     reset(int windowBits)
  94     {
  95         doReset(windowBits);
  96     }
  97
  98     /** Put the stream in a newly constructed state.
  99
 100         All dynamically allocated memory is de-allocated.
 101     */
 102     void
 103     clear()
 104     {
 105         doClear();
 106     }
 107
 108     /** Decompress input and produce output.
 109
 110         This function decompresses as much data as possible, and stops when
 111         the input buffer becomes empty or the output buffer becomes full. It
 112         may introduce some output latency (reading input without producing any
 113         output) except when forced to flush.
 114
 115         One or both of the following actions are performed:
 116
 117         @li Decompress more input starting at `zs.next_in` and update `zs.next_in`
 118         and `zs.avail_in` accordingly. If not all input can be processed (because
 119         there is not enough room in the output buffer), `zs.next_in` is updated
 120         and processing will resume at this point for the next call.
 121
 122         @li Provide more output starting at `zs.next_out` and update `zs.next_out`
 123         and `zs.avail_out` accordingly. `write` provides as much output as
 124         possible, until there is no more input data or no more space in the output
 125         buffer (see below about the flush parameter).
 126
 127         Before the call, the application should ensure that at least one of the
 128         actions is possible, by providing more input and/or consuming more output,
 129         and updating the values in `zs` accordingly. The application can consume
 130         the uncompressed output when it wants, for example when the output buffer
 131         is full (`zs.avail_out == 0`), or after each call. If `write` returns no
 132         error and with zero `zs.avail_out`, it must be called again after making
 133         room in the output buffer because there might be more output pending.
 134
 135         The flush parameter may be `Flush::none`, `Flush::sync`, `Flush::finish`,
 136         `Flush::block`, or `Flush::trees`. `Flush::sync` requests to flush as much
 137         output as possible to the output buffer. `Flush::block` requests to stop if
 138         and when it gets to the next deflate block boundary. When decoding the
 139         zlib or gzip format, this will cause `write` to return immediately after
 140         the header and before the first block. When doing a raw inflate, `write` will
 141         go ahead and process the first block, and will return when it gets to the
 142         end of that block, or when it runs out of data.
 143
 144         The `Flush::block` option assists in appending to or combining deflate
 145         streams. Also to assist in this, on return `write` will set `zs.data_type`
 146         to the number of unused bits in the last byte taken from `zs.next_in`, plus
 147         64 if `write` is currently decoding the last block in the deflate stream,
 148         plus 128 if `write` returned immediately after decoding an end-of-block code
 149         or decoding the complete header up to just before the first byte of the
 150         deflate stream. The end-of-block will not be indicated until all of the
 151         uncompressed data from that block has been written to `zs.next_out`. The
 152         number of unused bits may in general be greater than seven, except when
 153         bit 7 of `zs.data_type` is set, in which case the number of unused bits
 154         will be less than eight. `zs.data_type` is set as noted here every time
 155         `write` returns for all flush options, and so can be used to determine the
 156         amount of currently consumed input in bits.
 157
 158         The `Flush::trees` option behaves as `Flush::block` does, but it also returns
 159         when the end of each deflate block header is reached, before any actual data
 160         in that block is decoded. This allows the caller to determine the length of
 161         the deflate block header for later use in random access within a deflate block.
 162         256 is added to the value of `zs.data_type` when `write` returns immediately
 163         after reaching the end of the deflate block header.
 164
 165         `write` should normally be called until it returns `error::end_of_stream` or
 166         another error. However if all decompression is to be performed in a single
 167         step (a single call of `write`), the parameter flush should be set to
 168         `Flush::finish`. In this case all pending input is processed and all pending
 169         output is flushed; `zs.avail_out` must be large enough to hold all of the
 170         uncompressed data for the operation to complete. (The size of the uncompressed
 171         data may have been saved by the compressor for this purpose.) The use of
 172         `Flush::finish` is not required to perform an inflation in one step. However
 173         it may be used to inform inflate that a faster approach can be used for the
 174         single call. `Flush::finish` also informs inflate to not maintain a sliding
 175         window if the stream completes, which reduces inflate's memory footprint.
 176         If the stream does not complete, either because not all of the stream is
 177         provided or not enough output space is provided, then a sliding window will be
 178         allocated and `write` can be called again to continue the operation as if
 179         `Flush::none` had been used.
 180
 181         In this implementation, `write` always flushes as much output as possible to
 182         the output buffer, and always uses the faster approach on the first call. So
 183         the effects of the flush parameter in this implementation are on the return value
 184         of `write` as noted below, when `write` returns early when `Flush::block` or
 185         `Flush::trees` is used, and when `write` avoids the allocation of memory for a
 186         sliding window when `Flush::finsih` is used.
 187
 188         If a preset dictionary is needed after this call,
 189         `write` sets `zs.adler` to the Adler-32 checksum of the dictionary chosen by
 190         the compressor and returns `error::need_dictionary`; otherwise it sets
 191         `zs.adler` to the Adler-32 checksum of all output produced so far (that is,
 192         `zs.total_out bytes`) and returns no error, `error::end_of_stream`, or an
 193         error code as described below. At the end of the stream, `write` checks that
 194         its computed adler32 checksum is equal to that saved by the compressor and
 195         returns `error::end_of_stream` only if the checksum is correct.
 196
 197         This function returns no error if some progress has been made (more input
 198         processed or more output produced), `error::end_of_stream` if the end of the
 199         compressed data has been reached and all uncompressed output has been produced,
 200         `error::need_dictionary` if a preset dictionary is needed at this point,
 201         `error::invalid_data` if the input data was corrupted (input stream not
 202         conforming to the zlib format or incorrect check value), `error::stream_error`
 203         if the stream structure was inconsistent (for example if `zs.next_in` or
 204         `zs.next_out` was null), `error::need_buffers` if no progress is possible or
 205         if there was not enough room in the output buffer when `Flush::finish` is
 206         used. Note that `error::need_buffers` is not fatal, and `write` can be called
 207         again with more input and more output space to continue decompressing.
 208     */
 209     void
 210     write(z_params& zs, Flush flush, error_code& ec)
 211     {
 212         doWrite(zs, flush, ec);
 213     }
 214 };
 215
 216 } // zlib
 217 } // beast
 218 } // boost
 219
 220 #endif