void write( z_params& zs, Flush flush, error_code& ec);
This function decompresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush.
One or both of the following actions are performed:
zs.avail_inaccordingly. If not all input can be processed (because there is not enough room in the output buffer),
zs.next_inis updated and processing will resume at this point for the next call.
writeprovides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter).
Before the call, the application should ensure that at least one of the
actions is possible, by providing more input and/or consuming more output,
and updating the values in
accordingly. The application can consume the uncompressed output when it
wants, for example when the output buffer is full (
or after each call. If
returns no error and with zero
it must be called again after making room in the output buffer because
there might be more output pending.
The flush parameter may be
Flush::sync requests to flush as much output
as possible to the output buffer.
requests to stop if and when it gets to the next deflate block boundary.
When decoding the zlib or gzip format, this will cause
to return immediately after the header and before the first block. When
doing a raw inflate,
will go ahead and process the first block, and will return when it gets
to the end of that block, or when it runs out of data.
Flush::block option assists in appending to
or combining deflate streams. Also to assist in this, on return
write will set
to the number of unused bits in the last byte taken from
plus 64 if
write is currently
decoding the last block in the deflate stream, plus 128 if
write returned immediately after decoding
an end-of-block code or decoding the complete header up to just before
the first byte of the deflate stream. The end-of-block will not be indicated
until all of the uncompressed data from that block has been written to
zs.next_out. The number of unused bits may
in general be greater than seven, except when bit 7 of
is set, in which case the number of unused bits will be less than eight.
zs.data_type is set as noted here every
write returns for
all flush options, and so can be used to determine the amount of currently
consumed input in bits.
Flush::trees option behaves as
Flush::block does, but it also returns when
the end of each deflate block header is reached, before any actual data
in that block is decoded. This allows the caller to determine the length
of the deflate block header for later use in random access within a deflate
block. 256 is added to the value of
write returns immediately
after reaching the end of the deflate block header.
write should normally be
called until it returns
or another error. However if all decompression is to be performed in a
single step (a single call of
the parameter flush should be set to
In this case all pending input is processed and all pending output is flushed;
zs.avail_out must be large enough to hold
all of the uncompressed data for the operation to complete. (The size of
the uncompressed data may have been saved by the compressor for this purpose.)
The use of
Flush::finish is not required to perform an
inflation in one step. However it may be used to inform inflate that a
faster approach can be used for the single call.
also informs inflate to not maintain a sliding window if the stream completes,
which reduces inflate's memory footprint. If the stream does not complete,
either because not all of the stream is provided or not enough output space
is provided, then a sliding window will be allocated and
write can be called again to continue
the operation as if
had been used.
In this implementation,
always flushes as much output as possible to the output buffer, and always
uses the faster approach on the first call. So the effects of the flush
parameter in this implementation are on the return value of
write as noted below, when
write returns early when
is used, and when
avoids the allocation of memory for a sliding window when
Flush::finsih is used.
If a preset dictionary is needed after this call (see dictionary below),
to the Adler-32 checksum of the dictionary chosen by the compressor and
error::need_dictionary; otherwise it sets
to the Adler-32 checksum of all output produced so far (that is,
bytes) and returns no error,
error::end_of_stream, or an error code as described
below. At the end of the stream,
checks that its computed adler32 checksum is equal to that saved by the
compressor and returns
only if the checksum is correct.
This function returns no error if some progress has been made (more input
processed or more output produced),
if the end of the compressed data has been reached and all uncompressed
output has been produced,
if a preset dictionary is needed at this point,
if the input data was corrupted (input stream not conforming to the zlib
format or incorrect check value),
if the stream structure was inconsistent (for example if
zs.next_out was null),
if no progress is possible or if there was not enough room in the output
Flush::finish is used. Note that
error::need_buffers is not fatal, and
write can be called again with more input
and more output space to continue decompressing.