Home License Awareness Highly Reusable Software By activity Professions, Sciences, Humanities, Business, ... User Interface Text-based, GUI, Audio, Video, Keyboards, Mouse, Images,... Text Strings Conversions, tests, processing, manipulation,... Math Integer, Floating point, Matrix, Statistics, Boolean, ... Processing Algorithms, Memory, Process control, Debugging, ... Stored Data Data storage, Integrity, Encryption, Compression, ... Communications Networks, protocols, Interprocess, Remote, Client Server, ... Hard World Timing, Calendar and Clock, Audio, Video, Printer, Controls... File System Management, Filtering, File & Directory access, Viewers, ...

NAME

SYNOPSIS

#include <librock/target/types.c>
#include <librock/zlibh.h>

const char *
  librock_z_zlibVersion (void);

The application can compare zlibVersion and librock_ZLIB_VERSION for consistency. If the first character differs, the library code actually used is not compatible with the zlib.h header file used by the application.

This check is automatically made by deflateInit and inflateInit.

int
librock_z_uncompress (librock_z_Bytef *dest,
                      librock_z_uLongf *destLen,
                      const librock_z_Bytef *source,
                      librock_z_uLong sourceLen);

Decompresses the source buffer into the destination buffer. sourceLen is the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be large enough to hold the entire uncompressed data. (The size of the uncompressed data must have been saved previously by the compressor and transmitted to the decompressor by some mechanism outside the scope of this compression library.) Upon exit, destLen is the actual size of the compressed buffer.

This function can be used to decompress a whole file at once if the input file is mmap'ed.

librock_z_uncompress() returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not enough memory, librock_Z_BUF_ERROR if there was not enough room in the output buffer, or librock_Z_DATA_ERROR if the input data was corrupted.

This is a utility function implemented by calling the basic stream-oriented librock_z_inflate* functions described below. To simplify the interface, some default options are assumed (compression level and memory usage, standard memory allocation functions). The source code of these utility functions can easily be modified if you need special options.

int
librock_z_inflateInit (struct librock_z_stream *strm);

Initializes the internal stream state for decompression. The fields strm->zalloc , strm->zfree and strm->opaque must be initialized before by the caller. If strm->zalloc and strm->zfree are set to librock_Z_NULL, librock_z_deflateInit updates them to use default allocation functions, malloc() and free()

The strm->opaque value provided by the application will be passed as the first parameter for calls of custom zalloc and zfree. This can be useful for custom memory management. The zlib functions attach no meaning to the opaque value. A custom strm->zalloc must return librock_Z_NULL if there is not enough memory for the object.

If zlib is used in a multi-threaded application, the allocation functions must be thread safe.

strm->next_in , strm->avail_in, must be initialized before by the caller. If strm->next_in is not librock_Z_NULL and strm->avail_in is large enough (the exact value depends on the compression method), librock_z_inflateInit determines the compression method from the zlib header and allocates all data structures accordingly; otherwise the allocation will be deferred to the first call of librock_z_inflate() .

The application must update strm->next_in and strm->avail_in when strm->avail_in has dropped to zero. It must update strm->next_out and strm->avail_out when strm->avail_out has dropped to zero. All other fields are set by the implementation and must not be updated by the application.

The fields strm->total_in and strm->total_out can be used for statistics or progress reports.

The complete fields of struct librock_z_stream_s are:

struct librock_z_stream_s {
    librock_z_Bytef    *next_in;  /* next input byte */
    librock_z_uInt     avail_in;  /* number of bytes available at next_in */
    librock_z_uLong    total_in;  /* total nb of input bytes read so librock_PTR */

    librock_z_Bytef    *next_out; /* next output byte should be put there */
    librock_z_uInt     avail_out; /* remaining free space at next_out */
    librock_z_uLong    total_out; /* total nb of bytes output so librock_PTR */

    char     *msg;      /* last error message, NULL if no error */
    struct librock_z_internal_state librock_PTR *state; /* not visible by applications */

    librock_z_alloc_func zalloc;  /* used to allocate the internal state */
    librock_z_free_func  zfree;   /* used to free the internal state */
    librock_z_voidpf     opaque;  /* private data object passed to zalloc and zfree */

    int     data_type;  /* best guess about the data type: ascii or binary */
    librock_z_uLong   adler;      /* adler32 value of the uncompressed data */
    librock_z_uLong   reserved;   /* reserved for future use */
};

inflateInit() returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not enough memory, librock_Z_VERSION_ERROR if the zlib library version is incompatible with the version assumed by the caller. strm->msg is set to null if there is no error message. librock_z_inflateInit does not perform any decompression apart from reading the zlib header if present: this will be done by librock_z_inflate() . (So strm->next_in and strm->avail_in may be modified, but strm->next_out and strm->avail_out are unchanged.)

librock_z_inflateInit() is actually a macro which expands to int librock_z_inflateInit_ (librock_z_streamp strm,

                      const char *version,
                      int stream_size);


int
librock_z_inflateInit2 (librock_z_streamp strm,
                        int  windowBits);

This is another version of librock_z_inflateInit with an extra parameter. The fields strm->next_in , strm->avail_in , strm->zalloc , strm->zfree and strm->opaque must be initialized before by the caller.

The windowBits parameter is the base two logarithm of the maximum window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. The default value is 15 if librock_z_inflateInit is used instead. If a compressed stream with a larger window size is given as input, librock_z_inflate() will return with the error code librock_Z_DATA_ERROR instead of trying to allocate a larger window.

librock_z_inflateInit2() returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not enough memory, librock_Z_STREAM_ERROR if a parameter is invalid (such as a negative memLevel). msg is set to null if there is no error message. librock_z_inflateInit2 does not perform any decompression apart from reading the librock_zlib header if present: this will be done by librock_z_inflate(). (So strm->next_in and strm->avail_in may be modified, but strm->next_out and strm->avail_out are unchanged.)

librock_z_inflateInit2 is actually a macro which expands to

    int librock_z_inflateInit2_ (librock_z_streamp strm,
                                 int  windowBits,
                                 const char *version,
                                 int stream_size);


int
librock_z_inflate (librock_z_streamp strm,
                      int flush);

librock_z_inflate() decompresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush.

The detailed semantics are as follows. librock_z_inflate() performs one or both of the following actions:

• Decompress more input starting at strm->next_in and update strm->next_in and strm->avail_in accordingly. If not all input can be processed (because there is not enough room in the output buffer), strm->next_in is updated and processing will resume at this point for the next call of librock_z_inflate().

• Provide more output starting at strm->next_out and update strm->next_out and strm->avail_out accordingly. librock_z_inflate() provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter).

Before the call of librock_z_inflate() , the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating the strm->next_* and strm->avail_* values accordingly. The application can consume the uncompressed output when it wants, for example when the output buffer is full (strm->avail_out == 0), or after each call of librock_z_inflate(). If librock_z_inflate returns librock_Z_OK and with zero strm->avail_out, it must be called again after making room in the output buffer because there might be more output pending.

If the parameter flush is set to librock_Z_SYNC_FLUSH, librock_z_inflate flushes as much output as possible to the output buffer. The flushing behavior of librock_z_inflate is not specified for values of the flush parameter other than librock_Z_SYNC_FLUSH and librock_Z_FINISH, but the current implementation actually flushes as much output as possible anyway.

librock_z_inflate() should normally be called until it returns librock_Z_STREAM_END or an error. However if all decompression is to be performed in a single step (a single call of librock_z_inflate), the parameter flush should be set to librock_Z_FINISH . In this case all pending input is processed and all pending output is flushed; strm->avail_out must be large enough to hold all the uncompressed data. (The size of the uncompressed data may have been saved by the compressor for this purpose.) The next operation on this stream must be librock_z_inflateEnd to deallocate the decompression state. The use of librock_Z_FINISH is never required, but can be used to inform librock_z_inflate that a faster routine may be used for the single librock_z_inflate() call.

If a preset dictionary is needed at this point (see librock_z_inflateSetDictionary below), librock_z_inflate sets strm->adler to the librock_z_adler32 checksum of the dictionary chosen by the compressor and returns librock_Z_NEED_DICT; otherwise it sets strm->adler to the librock_z_adler32 checksum of all output produced so far (that is, total_out bytes) and returns librock_Z_OK, librock_Z_STREAM_END or an error code as described below. At the end of the stream, librock_z_inflate() checks that its computed librock_z_adler32 checksum is equal to that saved by the compressor and returns librock_Z_STREAM_END only if the checksum is correct.

librock_z_inflate() returns librock_Z_OK if some progress has been made (more input processed or more output produced), librock_Z_STREAM_END if the end of the compressed data has been reached and all uncompressed output has been produced, librock_Z_NEED_DICT if a preset dictionary is needed at this point, librock_Z_DATA_ERROR if the input data was corrupted (input stream not conforming to the librock_zlib format or incorrect librock_z_adler32 checksum), librock_Z_STREAM_ERROR if the stream structure was inconsistent (for example if strm->next_in or strm->next_out was NULL), librock_Z_MEM_ERROR if there was not enough memory, librock_Z_BUF_ERROR if no progress is possible or if there was not enough room in the output buffer when librock_Z_FINISH is used. In the librock_Z_DATA_ERROR case, the application may then call librock_z_inflateSync() to look for a good compression block.

int
librock_z_inflateEnd(librock_z_streamp strm);

 All dynamically allocated data structures for this stream are freed.
This function discards any unprocessed input and does not flush any
pending output.

librock_z_inflateEnd() returns librock_Z_OK if success, librock_Z_STREAM_ERROR if the stream state
was inconsistent. In the error case, strm->msg may be set but then points to a
static string (which must not be deallocated).


const char   *
librock_z_zError(int err);

allow conversion of error code to string for librock_z_compress() and librock_z_uncompress(). For most other functions strm->msg is already set.

SPECIAL FUNCTIONS

    The following functions are needed only in some special applications.


int
librock_z_inflateSetDictionary (librock_z_streamp strm,
                      const librock_z_Bytef *dictionary,
                      librock_z_uInt  dictLength);

int
librock_z_inflateSync (librock_z_streamp strm);

int
librock_z_inflateReset (librock_z_streamp strm);

int
librock_z_inflateSyncPoint (librock_z_streamp z);

 */


/*

    memcpy
    memset
    calloc
    free

    Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler
  Licensed under BSD-ish license, NO WARRANTY. Copies must retain this block.
  License text in <librock/license/zlib.txt> librock_LIDESC_HC=d49ece91d0f3402f1ca405bc4ae7b2a989a56ab2