The deflateParams() function shall dynamically alter the compression parameters for the compression stream object stream. On entry, stream shall refer to a user supplied z_stream object (a z_stream_s structure), already initialized via a call to deflateInit_() or deflateInit2_().
The level supplied shall be a value between
9, or the value
Z_DEFAULT_COMPRESSION. A level
1 requests the highest speed, while a level
9 requests the highest compression.
A level of
0 indicates that no
compression should be used, and the output shall be the same as the input.
If the compression level is altered by deflateParams(),
and some data has already been compressed with this stream
total_in is not zero),
and the new level requires a different
underlying compression method, then stream
shall be flushed by a call to deflate().
The strategy parameter selects the compression strategy to use:
use the system default compression strategy.
is particularly appropriate for text data.
use a compression strategy tuned for data consisting largely of small values with a
fairly random distribution.
Z_FILTERED uses more Huffman encoding
and less string matching than
force Huffman encoding only, with no string match.
On success, the deflateParams() function shall return
Otherwise, deflateParams() shall return
a value as described below to indicate the error.
On error, deflateParams() shall return one of the following error indicators:
Insufficient memory available.
Insufficient space in stream to flush the current output.
In addition, the
msg field of the strm
may be set to an error message.
Applications should ensure that the stream is flushed,
e.g. by a call to deflate(stream, Z_SYNC_FLUSH)
before calling deflateParams(), or ensure that there is
sufficient space in
next_out (as identified by
avail_out) to ensure that all pending output and
all uncompressed input can be flushed in a single call to
Rationale: Although the deflateParams() function should flush pending output and compress all pending input, the result is unspecified if there is insufficient space in the output buffer. Applications should only call deflateParams() when the stream is effectively empty (flushed).
The deflateParams() can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy.