Name

inflateSetDictionary — Initializes the decompression dictionary.

Library

Libz.lib

Synopsis

#include <zlib.h>

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

Return Value

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

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

Examples

To initialize the decompression dictionary:

#include <stdio.h>
#include <zlib.h>

void InflateSetDictionary( )
{     
    Byte *compr, *uncompr;
    uLong comprLen = 100*sizeof(int); 
    uLong uncomprLen = comprLen;                        
    compr    = (Byte*)calloc((uInt)comprLen, 1);
    uncompr  = (Byte*)calloc((uInt)uncomprLen, 1);
    compress(compr, &comprLen, (const Bytef*)hello, len);
    const char dictionary[] = "hello";
    z_stream d_stream; /* decompression stream */
    strcpy((char*)uncompr, "garbage");

    d_stream.zalloc = (alloc_func)0;
    d_stream.zfree = (free_func)0;
    d_stream.opaque = (voidpf)0;
    d_stream.next_in  = compr;
    d_stream.avail_in = (uInt)comprLen;
    inflateInit(&d_stream);   
    d_stream.next_out = uncompr;
    d_stream.avail_out = (uInt)uncomprLen;

    for (;;) 
       {
        err = inflate(&d_stream, Z_NO_FLUSH);
        if (err == Z_STREAM_END) break;
        if (err == Z_NEED_DICT) 
          {
            if (d_stream.adler != dictId)
            {
                fprintf(stderr, "unexpected dictionary");
                exit(1);
            }
            inflateSetDictionary(&d_stream, (const Bytef*)dictionary,
                                       sizeof(dictionary));
          }        
      }
    inflateEnd(&d_stream);
    free(compr);
    free(uncompr);   
}

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.

Feedback

For additional information or queries on this page send feedback