inflateSetDictionary

Name

inflateSetDictionary -- initialize decompression dictionary

Synopsis

#include <zlib.h>

int inflateSetDictionary(z_streamp stream, const Bytef * dictionary, uInt dictlen);

Description

The inflateSetDictionary() function shall initialize the decompression dictionary associated with stream using the dictlen bytes referenced by dictionary.

The inflateSetDictionary() function should be called immediately after a call to inflate() has failed with return value Z_NEED_DICT. The dictionary must have the same Adler-32 checksum as the dictionary used for the compression (see deflateSetDictionary()).

stream shall reference an initialized decompression stream, with total_in zero (i.e. no data has been decompressed since the stream was initialized).

Return Value

On success, inflateSetDictionary() shall return Z_OK. Otherwise it shall return a value as indicated below.

Errors

On error, inflateSetDictionary() shall return a value as described below:

Z_STREAM_ERROR 

The state in stream is inconsistent, or stream was NULL.

Z_DATA_ERROR 

The Adler-32 checksum of the supplied dictionary does not match that used for the compression.

Application Usage (informative)

The application should provide a dictionary consisting of strings {{{ed note: do we really mean "strings"? Null terminated?}}} that are likely to be encountered in the data to be compressed. The application should ensure that the dictionary is sorted such that the most commonly used strings occur at the end of the dictionary.

The use of a dictionary is optional; however if the data to be compressed is relatively short and has a predictable structure, the use of a dictionary can substantially improve the compression ratio.