Zstd Class

Properties   Methods   Events   Config Settings   Errors  

The Zstd class implements a Zstandard (zstd) compressor and decompressor.

Syntax

Zstd

Remarks

The Zstd class is compliant with RFC 8878, the Zstandard Compression Format specification. Data compressed by the class can be decompressed by any standard zstd-compatible tool or library, and the class can in turn decompress data produced by any standard zstd encoder.

The CompressionLevel property selects the compression level to use, from 1 (fastest) to 22 (most compact). The class favors speed and simplicity over maximum compression, so at very high levels it may not reach the same compression ratio as the reference zstd encoder; however, the resulting data is still fully standard and can be decompressed by any zstd decoder.

Data may be operated on in multiple ways as discussed below.

Compression and Decompression Streams

The GetDecompressionStream and GetCompressionStream methods are used to retrieve streams that read or write compressed data, as appropriate. The underlying stream should be passed to either method as a parameter.

CompressBlock and DecompressBlock

The CompressBlock and DecompressBlock methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the OutputData property is not applicable. Instead, data are made available via the CompressedData and DecompressedData events.

If all data is available ahead of time, the CompressData and DecompressData methods may be called instead.

Compress Data

The InputData property should be set to the current block to be compressed. Next, the CompressBlock method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the CompressedData event will fire with the compressed data. Note that this event may not fire for every call to CompressBlock due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the CompressedData event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the OutputData property is not applicable when compressing block data.

Decompress Data

The InputData property should be set to the current block to be decompressed. Next, the DecompressBlock method should be called to decompress the current block.

During decompression, the DecompressedData event will fire with the decompressed data. Note that this event may not fire for every call to DecompressBlock due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the DecompressedData event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the OutputData property is not applicable when decompressing block data.

CompressData and DecompressData

The CompressData and DecompressData methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the InputData property before calling either method.

To compress and decompress data in blocks (chunks), refer to the CompressBlock and DecompressBlock methods.

Compress Data

The InputData property should be set to the decompressed data. This should be the entire data to be compressed. Next, the CompressData method should be called, after which the OutputData property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the CompressedData event.

Decompress Data

The InputData property should be set to the compressed data. This should be the entire data to be decompressed. Next, the DecompressData method should be called, after which the OutputData property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to OutputData, the decompressed data may also be accumulated within the DecompressedData event.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

CompressionLevel Property (Zstd Class)

The compression level to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetCompressionLevel();
int SetCompressionLevel(int iCompressionLevel);

Unicode (Windows)
INT GetCompressionLevel();
INT SetCompressionLevel(INT iCompressionLevel);

int ipworkszip_zstd_getcompressionlevel(void* lpObj);
int ipworkszip_zstd_setcompressionlevel(void* lpObj, int iCompressionLevel);

int getCompressionLevel();
int setCompressionLevel(int iCompressionLevel);

Default Value

4

Remarks

This property dictates the compression level to use, from 1 to 22. Higher values will cause the class to compress better; lower values will cause the class to compress faster.

Note that some levels may produce functionally identical results to a neighboring level. A higher level will never compress worse than a lower one, but it is not guaranteed to compress better at every step.

When the GetCompressionStream method is invoked, the stream will be created with the specified compression level. After a stream has been created, it is independent of the class, and changing this property will have no effect on existing streams.

Data Type

Integer

InputData Property (Zstd Class)

The data to compress or decompress.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetInputData(char* &lpInputData, int &lenInputData);
int SetInputData(const char* lpInputData, int lenInputData);

Unicode (Windows)
INT GetInputData(LPSTR &lpInputData, INT &lenInputData);
INT SetInputData(LPCSTR lpInputData, INT lenInputData);

int ipworkszip_zstd_getinputdata(void* lpObj, char** lpInputData, int* lenInputData);
int ipworkszip_zstd_setinputdata(void* lpObj, const char* lpInputData, int lenInputData);

QByteArray getInputData();
int setInputData(QByteArray qbaInputData);

Default Value

""

Remarks

This property specifies the data to compress or decompress.

When decompressing, this should be set to the compressed data before the DecompressData or DecompressBlock methods are called.

When compressing, this should be set to the decompressed data before the CompressData or CompressBlock methods are called.

Note that this property is not automatically cleared after each operation when performing operations on multiple chunks of data.

Data Type

Binary String

OutputData Property (Zstd Class)

The output data after compression or decompression.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutputData(char* &lpOutputData, int &lenOutputData);

Unicode (Windows)
INT GetOutputData(LPSTR &lpOutputData, INT &lenOutputData);

int ipworkszip_zstd_getoutputdata(void* lpObj, char** lpOutputData, int* lenOutputData);

QByteArray getOutputData();

Default Value

""

Remarks

This property holds the compressed or decompressed data after the CompressData or DecompressData methods are called.

This property is not applicable when calling the CompressBlock or DecompressBlock methods.

This property is read-only and not available at design time.

Data Type

Binary String

CompressBlock Method (Zstd Class)

Compresses a block of data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CompressBlock(int bLastBlock);

Unicode (Windows)
INT CompressBlock(BOOL bLastBlock);

int ipworkszip_zstd_compressblock(void* lpObj, int bLastBlock);

int compressBlock(bool bLastBlock);

Remarks

This method compresses the block of data specified by the InputData property.

The CompressBlock and DecompressBlock methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the OutputData property is not applicable. Instead, data are made available via the CompressedData and DecompressedData events.

If all data is available ahead of time, the CompressData and DecompressData methods may be called instead.

Compress Data

The InputData property should be set to the current block to be compressed. Next, the CompressBlock method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the CompressedData event will fire with the compressed data. Note that this event may not fire for every call to CompressBlock due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the CompressedData event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the OutputData property is not applicable when compressing block data.

Decompress Data

The InputData property should be set to the current block to be decompressed. Next, the DecompressBlock method should be called to decompress the current block.

During decompression, the DecompressedData event will fire with the decompressed data. Note that this event may not fire for every call to DecompressBlock due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the DecompressedData event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the OutputData property is not applicable when decompressing block data.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CompressData Method (Zstd Class)

Compresses the specified data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CompressData();

Unicode (Windows)
INT CompressData();

int ipworkszip_zstd_compressdata(void* lpObj);

int compressData();

Remarks

This method compresses the data specified by the InputData property. After calling this method, the OutputData property holds the compressed data.

The CompressData and DecompressData methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the InputData property before calling either method.

To compress and decompress data in blocks (chunks), refer to the CompressBlock and DecompressBlock methods.

Compress Data

The InputData property should be set to the decompressed data. This should be the entire data to be compressed. Next, the CompressData method should be called, after which the OutputData property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the CompressedData event.

Decompress Data

The InputData property should be set to the compressed data. This should be the entire data to be decompressed. Next, the DecompressData method should be called, after which the OutputData property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to OutputData, the decompressed data may also be accumulated within the DecompressedData event.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (Zstd Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworkszip_zstd_config(void* lpObj, const char* lpszConfigurationString);

QString config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value ; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DecompressBlock Method (Zstd Class)

Decompresses a block of data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DecompressBlock();

Unicode (Windows)
INT DecompressBlock();

int ipworkszip_zstd_decompressblock(void* lpObj);

int decompressBlock();

Remarks

This method decompresses the block of data specified by the InputData property.

The CompressBlock and DecompressBlock methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the OutputData property is not applicable. Instead, data are made available via the CompressedData and DecompressedData events.

If all data is available ahead of time, the CompressData and DecompressData methods may be called instead.

Compress Data

The InputData property should be set to the current block to be compressed. Next, the CompressBlock method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the CompressedData event will fire with the compressed data. Note that this event may not fire for every call to CompressBlock due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the CompressedData event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the OutputData property is not applicable when compressing block data.

Decompress Data

The InputData property should be set to the current block to be decompressed. Next, the DecompressBlock method should be called to decompress the current block.

During decompression, the DecompressedData event will fire with the decompressed data. Note that this event may not fire for every call to DecompressBlock due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the DecompressedData event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the OutputData property is not applicable when decompressing block data.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DecompressData Method (Zstd Class)

Decompresses the specified data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DecompressData();

Unicode (Windows)
INT DecompressData();

int ipworkszip_zstd_decompressdata(void* lpObj);

int decompressData();

Remarks

This method decompresses the data specified by the InputData property. After calling this method, the OutputData property holds the decompressed data.

The CompressData and DecompressData methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the InputData property before calling either method.

To compress and decompress data in blocks (chunks), refer to the CompressBlock and DecompressBlock methods.

Compress Data

The InputData property should be set to the decompressed data. This should be the entire data to be compressed. Next, the CompressData method should be called, after which the OutputData property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to OutputData, the compressed data may also be accumulated within the CompressedData event.

Decompress Data

The InputData property should be set to the compressed data. This should be the entire data to be decompressed. Next, the DecompressData method should be called, after which the OutputData property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to OutputData, the decompressed data may also be accumulated within the DecompressedData event.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (Zstd Class)

Resets the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworkszip_zstd_reset(void* lpObj);

int reset();

Remarks

This method is used to reset the state of the class. All properties are set to their default values, and any open files are closed.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CompressedData Event (Zstd Class)

Fires with compressed data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCompressedData(ZstdCompressedDataEventParams *e);

typedef struct {
  const char* Data;
  int lenData;
  int reserved;
} ZstdCompressedDataEventParams;


Unicode (Windows)
virtual INT FireCompressedData(ZstdCompressedDataEventParams *e);

typedef struct {
  LPCSTR Data;
  INT lenData;
  INT reserved;
} ZstdCompressedDataEventParams;

#define EID_ZSTD_COMPRESSEDDATA 1

virtual INT IPWORKSZIP_CALL FireCompressedData(char* &lpData, INT &lenData);

class ZstdCompressedDataEventParams {
public:
  const QByteArray& data();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass Zstd and override this emitter function.
virtual int fireCompressedData(ZstdCompressedDataEventParams *e) {...}
// Or, connect one or more slots to this signal.
void compressedData(ZstdCompressedDataEventParams *e);

Remarks

This event is fired one or more times as compressed data become available when the CompressData or CompressBlock methods are called.

Data holds the current block of compressed data.

DecompressedData Event (Zstd Class)

Fires with decompressed data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDecompressedData(ZstdDecompressedDataEventParams *e);

typedef struct {
  const char* Data;
  int lenData;
  int reserved;
} ZstdDecompressedDataEventParams;


Unicode (Windows)
virtual INT FireDecompressedData(ZstdDecompressedDataEventParams *e);

typedef struct {
  LPCSTR Data;
  INT lenData;
  INT reserved;
} ZstdDecompressedDataEventParams;

#define EID_ZSTD_DECOMPRESSEDDATA 2

virtual INT IPWORKSZIP_CALL FireDecompressedData(char* &lpData, INT &lenData);

class ZstdDecompressedDataEventParams {
public:
  const QByteArray& data();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass Zstd and override this emitter function.
virtual int fireDecompressedData(ZstdDecompressedDataEventParams *e) {...}
// Or, connect one or more slots to this signal.
void decompressedData(ZstdDecompressedDataEventParams *e);

Remarks

This event is fired one or more times as decompressed data become available when the DecompressData or DecompressBlock methods are called.

Data holds the current block of decompressed data.

Error Event (Zstd Class)

Fires with information about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(ZstdErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char* Description;
  int reserved;
} ZstdErrorEventParams;


Unicode (Windows)
virtual INT FireError(ZstdErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} ZstdErrorEventParams;

#define EID_ZSTD_ERROR 3

virtual INT IPWORKSZIP_CALL FireError(int &iErrorCode, char* &lpszDescription);

class ZstdErrorEventParams {
public:
  int errorCode();

  const QString& description();

  int eventRetVal();
  void setEventRetVal(int iRetVal);
};

// To handle, subclass Zstd and override this emitter function.
virtual int fireError(ZstdErrorEventParams *e) {...}
// Or, connect one or more slots to this signal.
void error(ZstdErrorEventParams *e);

Remarks

This event is fired in case of exceptional conditions during message processing. Normally, the class fails with an error.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (Zstd Class)

No configuration settings defined.

Base Config Settings

Trappable Errors (Zstd Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ZipStream Errors