Tcl Reference Manual: TclZlib

NAME

Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate, Tcl_ZlibStreamAdler32, Tcl_ZlibStreamClose, Tcl_ZlibStreamEof, Tcl_ZlibStreamGet, Tcl_ZlibStreamGetCommandName, Tcl_ZlibStreamInit, Tcl_ZlibStreamPut -
compression and decompression functions

SYNOPSIS

#include <tcl.h>

Tcl_Obj *
Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)

Tcl_Obj *
Tcl_ZlibInflate(interp, format, dataObj, dictObj)

unsigned int
Tcl_ZlibCRC32(initValue, bytes, length)

unsigned int
Tcl_ZlibAdler32(initValue, bytes, length)

int
Tcl_ZlibStreamInit(interp, mode, format, level, dictObj, zshandlePtr)

Tcl_Obj *
Tcl_ZlibStreamGetCommandName(zshandle)

int
Tcl_ZlibStreamEof(zshandle)

int
Tcl_ZlibStreamClose(zshandle)

int
Tcl_ZlibStreamAdler32(zshandle)

int
Tcl_ZlibStreamPut(zshandle, dataObj, flush)

int
Tcl_ZlibStreamGet(zshandle, dataObj, count)

ARGUMENTS

Type	Name	Mode
Tcl_Interp	*interp	in
	The interpreter to store resulting compressed or uncompressed data in. Also where any error messages are written.
int	format	in
	What format of compressed data to work with. Must be one of TCL_ZLIB_FORMAT_ZLIB for zlib-format data, TCL_ZLIB_FORMAT_GZIP for gzip-format data, or TCL_ZLIB_FORMAT_RAW for raw compressed data. In addition, for decompression only, TCL_ZLIB_FORMAT_AUTO may also be chosen which can automatically detect whether the compressed data was in zlib or gzip format.
Tcl_Obj	*dataObj	in/out
	A byte-array object containing the data to be compressed or decompressed, or which is set to the data extracted from the stream when passed to Tcl_ZlibStreamGet.
int	level	in
	What level of compression to use. Should be a number from 0 to 9 or one of the following: TCL_ZLIB_COMPRESS_NONE for no compression, TCL_ZLIB_COMPRESS_FAST for fast but inefficient compression, TCL_ZLIB_COMPRESS_BEST for slow but maximal compression, or TCL_ZLIB_COMPRESS_DEFAULT for the level recommended by the zlib library.
Tcl_Obj	*dictObj	in/out
	A dictionary that contains, or which will be updated to contain, a description of the gzip header associated with the compressed data. Only useful when the format is TCL_ZLIB_FORMAT_GZIP or TCL_ZLIB_FORMAT_AUTO. If a NULL is passed, a default header will be used on compression and the header will be ignored (apart from integrity checks) on decompression.
unsigned int	initValue	in
	The initial value for the checksum algorithm.
unsigned char	*bytes	in
	An array of bytes to run the checksum algorithm over, or NULL to get the recommended initial value for the checksum algorithm.
int	length	in
	The number of bytes in the array.
int	mode	in
	What mode to operate the stream in. Should be either TCL_ZLIB_STREAM_DEFLATE for a compressing stream or TCL_ZLIB_STREAM_INFLATE for a decompressing stream.
Tcl_ZlibStream	*zshandlePtr	out
	A pointer to a variable in which to write the abstract token for the stream upon successful creation.
Tcl_ZlibStream	zshandle	in
	The abstract token for the stream to operate on.
int	flush	in
	Whether and how to flush the stream after writing the data to it. Must be one of: TCL_ZLIB_NO_FLUSH if no flushing is to be done, TCL_ZLIB_FLUSH if the currently compressed data must be made available for access using Tcl_ZlibStreamGet, TCL_ZLIB_FULLFLUSH if the stream must be put into a state where the decompressor can recover from on corruption, or TCL_ZLIB_FINALIZE to ensure that the stream is finished and that any trailer demanded by the format is written.
int	count	in
	The maximum number of bytes to get from the stream, or -1 to get all remaining bytes from the stream's buffers.

DESCRIPTION

These functions form the interface from the Tcl library to the Zlib library by Jean-loup Gailly and Mark Adler.

Tcl_ZlibDeflate and Tcl_ZlibInflate compress and decompress data respectively. Upon success, they leave the resulting compressed or decompressed data in a byte-array object that is the Tcl interpreter's result. Note that the dictObj parameter is only used when the format parameter is TCL_ZLIB_FORMAT_GZIP or TCL_ZLIB_FORMAT_AUTO.

Tcl_ZlibAdler32 and Tcl_ZlibCRC32 compute checksums on arrays of bytes. Typical usage is:

checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length);

Tcl_ZlibStreamInit creates a compressing or decompressing stream that is linked to a Tcl command, according to its arguments, and provides an abstract token for the stream; Tcl_ZlibStreamGetCommandName returns the name of that command given the stream token. Once a stream has been constructed, Tcl_ZlibStreamPut is used to add data to the stream and Tcl_ZlibStreamGet is used to retrieve data from the stream after processing. Tcl_ZlibStreamAdler32 returns the checksum computed over the uncompressed data, and Tcl_ZlibStreamEof returns whether the end of the uncompressed data has been reached. Finally, Tcl_ZlibStreamClose will clean up the stream and delete the associated command: using Tcl_DeleteCommand on the stream's command is equivalent.

PORTABILITY NOTES

These functions will fail gracefully if Tcl is not linked with the zlib library.

KEYWORDS