Linux Standard Base Core Specification 3.0Preview1 | ||
---|---|---|
<<< Previous | Next >>> |
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
0
and 9
, or the value
Z_DEFAULT_COMPRESSION
. A level
of 1
requests the highest speed, while a level
of 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
(i.e. 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:
Z_DEFAULT_STRATEGY
use the system default compression strategy. Z_DEFAULT_STRATEGY
is particularly appropriate for text data.
Z_FILTERED
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 Z_DEFAULT_STRATEGY
.
Z_HUFFMAN_ONLY
force Huffman encoding only, with no string match.
On success, the deflateParams() function shall return
Z_OK
.
Otherwise, deflateParams() shall return
a value as described below to indicate the error.
On error, deflateParams() shall return one of the following error indicators:
Z_STREAM_ERROR
Invalid parameter.
Z_MEM_ERROR
Insufficient memory available.
Z_BUF_ERROR
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
deflate().
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.
<<< Previous | Home | Next >>> |
deflateInit_ | Up | deflateReset |