deflateParams

Name

deflateParams -- set compression parameters

Synopsis

#include <zlib.h>

int deflateParams(z_streamp stream, int level, int strategy);

Description

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.

Return Value

On success, the deflateParams() function shall return Z_OK. Otherwise, deflateParams() shall return a value as described below to indicate the error.

Errors

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.

Application Usage (Informative)

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.