Gzip C Library Reference

Gzip

GZip compression C library.

Create/Dispose

HCkGzip CkGzip_Create(void);

Creates an instance of the CkGzip object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkGzip_Dispose(HCkGzip handle);

Objects created by calling CkGzip_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

C "Properties"

void CkGzip_getComment(HCkGzip cHandle, HCkString retval);
void CkGzip_putComment(HCkGzip cHandle, const char *newVal);

Specifies an optional comment string that can be embedded within the .gz when any Compress* method is called.

void CkGzip_getExtraData(HCkGzip cHandle, HCkByteData retval);
void CkGzip_putExtraData(HCkGzip cHandle, HCkByteData newVal);

Optional extra-data that can be included within a .gz when a Compress* method is called.

void CkGzip_getFilename(HCkGzip cHandle, HCkString retval);
void CkGzip_putFilename(HCkGzip cHandle, const char *newVal);

The filename that is embedded within the .gz during any Compress* method call. When extracting from a .gz using applications such as WinZip, this will be the filename that is created.

void CkGzip_getLastErrorHtml(HCkGzip cHandle, HCkString retval);

Error information in HTML format for the last method called.

void CkGzip_getLastErrorText(HCkGzip cHandle, HCkString retval);

Error information in plain-text format for the last method called.

void CkGzip_getLastErrorXml(HCkGzip cHandle, HCkString retval);

Error information in XML format for the last method called.

void CkGzip_getLastMod(HCkGzip cHandle, SYSTEMTIME *retval);
void CkGzip_putLastMod(HCkGzip cHandle, SYSTEMTIME *newVal);

The last-modification date/time to be embedded within the .gz when a Compress* method is called. By default, the current system date/time is used.

BOOL CkGzip_getUseCurrentDate(HCkGzip cHandle);
void CkGzip_putUseCurrentDate(HCkGzip cHandle, BOOL newVal);

If set to true, the file produced by an Uncompress* method will use the current date/time for the last-modification date instead of the date/time found within the Gzip format.

BOOL CkGzip_getUtf8(HCkGzip cHandle);
void CkGzip_putUtf8(HCkGzip cHandle, BOOL newVal);

When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.

BOOL CkGzip_getVerboseLogging(HCkGzip cHandle);
void CkGzip_putVerboseLogging(HCkGzip cHandle, BOOL newVal);

To be documented soon...

void CkGzip_getVersion(HCkGzip cHandle, HCkString retval);

Version of the component, such as "1.0.0"

C "Methods"

BOOL CkGzip_CompressFile(HCkGzip cHandle, const char *inFilename, const char *outFilename);

Compresses a file to create a GZip compressed file (.gz).

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_CompressFile2(HCkGzip cHandle, const char *inFilename, const char *embeddedFilename, const char *outFilename);

Compresses a file to create a GZip compressed file (.gz). inFilename is the actual filename on disk. embeddedFilename is the filename to be embedded in the .gz such that when it is un-gzipped, this is the name of the file that will be created.

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_CompressFileToMem(HCkGzip cHandle, const char *inFilename, HCkByteData outData);

Gzip compresses a file to an in-memory image of a .gz file.

BOOL CkGzip_CompressMemToFile(HCkGzip cHandle, HCkByteData db, const char *outFilename);

Gzip compresses and creates a .gz file from in-memory data.

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_CompressMemory(HCkGzip cHandle, HCkByteData dbIn, HCkByteData outData);

Compresses in-memory data to an in-memory image of a .gz file.

BOOL CkGzip_CompressString(HCkGzip cHandle, const char *inStr, const char *outCharset, HCkByteData outBytes);

Gzip compresses a string and writes the output to a byte array. The string is first converted to the charset specified by outCharset. Typical charsets are "utf-8", "iso-8859-1", "shift_JIS", etc.

Full List of Charset Names

BOOL CkGzip_CompressStringToFile(HCkGzip cHandle, const char *inStr, const char *outCharset, const char *outFilename);

Gzip compresses a string and writes the output to a .gz compressed file. The string is first converted to the charset specified by ARG2. Typical charsets are "utf-8", "iso-8859-1", "shift_JIS", etc.

Returns TRUE for success, FALSE for failure.

Full List of Charset Names

BOOL CkGzip_Decode(HCkGzip cHandle, const char *str, const char *encoding, HCkByteData outBytes);

Decodes an encoded string and returns the original data. The encoding mode is determined by encoding. It may be "base64", "hex", "quoted-printable", or "url".

void CkGzip_DeflateStringENC(HCkGzip cHandle, const char *str, const char *charset, const char *encoding, HCkString outStr);

Provides the ability to use the zip/gzip's deflate algorithm directly to compress a string. Internal to this method, inString is first converted to the charset specified by charsetName. The data is then compressed using the deflate compression algorithm. The binary output is then encoded according to outputEncoding. Possible values for outputEncoding are "hex", "base64", "url", and "quoted-printable".

Note: The output of this method is compressed data with no Gzip file format. Use the Compress* methods to produce Gzip file format output.

Full List of Charset Names

BOOL CkGzip_Encode(HCkGzip cHandle, HCkByteData byteData, const char *encoding, HCkString outStr);

Encodes binary data to a printable string. The encoding mode is determined by encoding. It may be "base64", "hex", "quoted-printable", or "url".

BOOL CkGzip_ExamineFile(HCkGzip cHandle, const char *inGzFilename);

Determines if the inGzFilename is a Gzip formatted file. Returns true if it is a Gzip formatted file, otherwise returns false.

BOOL CkGzip_ExamineMemory(HCkGzip cHandle, HCkByteData inGzData);

Determines if the in-memory bytes (inGzData) contain a Gzip formatted file. Returns true if it is Gzip format, otherwise returns false.

void CkGzip_InflateStringENC(HCkGzip cHandle, const char *str, const char *charset, const char *encoding, HCkString outStr);

This the reverse of DeflateStringENC.

The input string is first decoded according to inputEncoding. (Possible values for inputEncoding are "hex", "base64", "url", and "quoted-printable".) The compressed data is then inflated, and the result is then converted from convertFromCharset (if necessary) to return a string.

BOOL CkGzip_IsUnlocked(HCkGzip cHandle);

Returns true if the component has been unlocked.

BOOL CkGzip_ReadFile(HCkGzip cHandle, const char *filename, HCkByteData outBytes);

Reads a binary file into memory and returns the byte array. Note: This method does not parse a Gzip, it is only a convenience method for reading a binary file into memory.

BOOL CkGzip_SaveLastError(HCkGzip cHandle, const char *filename);

Saves the last error information to an XML formatted file.

BOOL CkGzip_UnTarGz(HCkGzip cHandle, const char *gzFilename, const char *destDir, BOOL bNoAbsolute);

Unpacks a .tar.gz file. The ungzip and untar occur in streaming mode. There are no temporary files and the memory footprint is constant (and small) while untarring. bNoAbsolute may be true or false. A value of true protects from untarring to absolute paths. (For example, imagine the trouble if the tar contains files with absolute paths beginning with /Windows/system32)

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_UncompressFile(HCkGzip cHandle, const char *inFilename, const char *outFilename);

Un-Gzips a .gz file. The output filename is specified by the 2nd argument and not by the filename embedded within the .gz.

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_UncompressFileToMem(HCkGzip cHandle, const char *inFilename, HCkByteData outData);

Un-Gzips a .gz file directly to memory.

BOOL CkGzip_UncompressFileToString(HCkGzip cHandle, const char *inFilename, const char *inCharset, HCkString outStr);

Uncompresses a .gz file that contains a text file. The contents of the text file are returned as a string. The character encoding of the text file is specified by charset. Typical charsets are "iso-8859-1", "utf-8", "windows-1252", "shift_JIS", "big5", etc.

List of Valid Charsets

BOOL CkGzip_UncompressMemToFile(HCkGzip cHandle, HCkByteData db, const char *outFilename);

Un-Gzips from an in-memory image of a .gz file to a file.

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_UncompressMemory(HCkGzip cHandle, HCkByteData dbIn, HCkByteData outData);

Un-Gzips from an in-memory image of a .gz file directly into memory.

BOOL CkGzip_UncompressString(HCkGzip cHandle, HCkByteData inData, const char *inCharset, HCkString outStr);

The reverse of CompressString.

The bytes in inData are uncompressed, then converted from inCharset (if necessary) to return a string.

Full List of Charset Names

BOOL CkGzip_UnlockComponent(HCkGzip cHandle, const char *unlockCode);

Unlocks the component allowing for the full functionality to be used.

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_WriteFile(HCkGzip cHandle, const char *filename, HCkByteData binaryData);

A convenience method for writing a binary byte array to a file.

Returns TRUE for success, FALSE for failure.

BOOL CkGzip_XfdlToXml(HCkGzip cHandle, const char *xfdl, HCkString outStr);

Converts base64-gzip .xfdl data to a decompressed XML string. The xfldData contains the base64 data. This method returns the decoded/decompressed XML string.

const char *CkGzip_comment(HCkGzip cHandle);

Specifies an optional comment string that can be embedded within the .gz when any Compress* method is called.

Returns a null on failure

const char *CkGzip_deflateStringENC(HCkGzip cHandle, const char *str, const char *charset, const char *encoding);

Provides the ability to use the zip/gzip's deflate algorithm directly to compress a string. Internal to this method, inString is first converted to the charset specified by charsetName. The data is then compressed using the deflate compression algorithm. The binary output is then encoded according to outputEncoding. Possible values for outputEncoding are "hex", "base64", "url", and "quoted-printable".

Note: The output of this method is compressed data with no Gzip file format. Use the Compress* methods to produce Gzip file format output.

Returns a null on failure

Full List of Charset Names

const char *CkGzip_encode(HCkGzip cHandle, HCkByteData byteData, const char *encoding);

Encodes binary data to a printable string. The encoding mode is determined by encoding. It may be "base64", "hex", "quoted-printable", or "url".

Returns a null on failure

const char *CkGzip_filename(HCkGzip cHandle);

The filename that is embedded within the .gz during any Compress* method call. When extracting from a .gz using applications such as WinZip, this will be the filename that is created.

Returns a null on failure

const char *CkGzip_inflateStringENC(HCkGzip cHandle, const char *str, const char *charset, const char *encoding);

This the reverse of DeflateStringENC.

The input string is first decoded according to inputEncoding. (Possible values for inputEncoding are "hex", "base64", "url", and "quoted-printable".) The compressed data is then inflated, and the result is then converted from convertFromCharset (if necessary) to return a string.

Returns a null on failure

const char *CkGzip_lastErrorHtml(HCkGzip cHandle);

Error information in HTML format for the last method called.

Returns a null on failure

const char *CkGzip_lastErrorText(HCkGzip cHandle);

Error information in plain-text format for the last method called.

Returns a null on failure

const char *CkGzip_lastErrorXml(HCkGzip cHandle);

Error information in XML format for the last method called.

Returns a null on failure

const char *CkGzip_uncompressFileToString(HCkGzip cHandle, const char *inFilename, const char *inCharset);

Uncompresses a .gz file that contains a text file. The contents of the text file are returned as a string. The character encoding of the text file is specified by charset. Typical charsets are "iso-8859-1", "utf-8", "windows-1252", "shift_JIS", "big5", etc.

Returns a null on failure

List of Valid Charsets

const char *CkGzip_uncompressString(HCkGzip cHandle, HCkByteData inData, const char *inCharset);

The reverse of CompressString.

The bytes in inData are uncompressed, then converted from inCharset (if necessary) to return a string.

Returns a null on failure

Full List of Charset Names

const char *CkGzip_version(HCkGzip cHandle);

Version of the component, such as "1.0.0"

Returns a null on failure

const char *CkGzip_xfdlToXml(HCkGzip cHandle, const char *xfdl);

Converts base64-gzip .xfdl data to a decompressed XML string. The xfldData contains the base64 data. This method returns the decoded/decompressed XML string.

Returns a null on failure