Name

deflateParams — Alters the compression parameters for the compression stream object stream..

Library

Libz.lib

Synopsis

#include <zlib.h>

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

Return Value

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

Detailed 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.

Examples

To alter the compression parameters for the compression stream object stream to level=Z_NO_COMPRESSION and strategy = Z_DEFAULT_STRATEGY:

#include <stdio.h>
#include <zlib.h>
void Deflateparams( )
{     
    z_stream c_stream; /* compression stream */    
    Byte * compr;    
    uLong comprLen = 20*sizeof(int);    
    compr    = (Byte*)calloc((uInt)comprLen, 1); 
    const char hello[] = "hello, hello!";
    uLong len = (uLong)strlen(hello)+1;

    c_stream.zalloc = (alloc_func)0;
    c_stream.zfree = (free_func)0;
    c_stream.opaque = (voidpf)0;

    deflateInit(&c_stream, Z_DEFAULT_COMPRESSION);  
    c_stream.next_in  = (Bytef*)hello;
    c_stream.next_out = compr;     
    deflateParams(&c_stream, Z_NO_COMPRESSION, Z_DEFAULT_STRATEGY);    
    deflateEnd(&c_stream);
    free(compr);
}

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.

Feedback

For additional information or queries on this page send feedback