Lz4 Component

Properties   Methods   Events   Config Settings   Errors  

The Lz4 component implements an LZ4 compressor and decompressor.

Syntax

nsoftware.IPWorksZip.Lz4

Remarks

The Lz4 component is compliant with the LZ4 Frame Format specification. Data compressed by the component can be decompressed by any standard LZ4-compatible tool or library, and the component can in turn decompress data produced by any standard LZ4 encoder, including frames using linked blocks, block checksums, or skippable frames. Note that the legacy LZ4 frame format and LZ4 dictionaries are not supported, and frames using either are rejected with an error.

The CompressionLevel property selects the compression level to use, from 1 (fastest) to 6 (most compact).

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 component with short descriptions. Click on the links for further details.

CloseBaseStream Whether or not to close the underlying stream.
CompressionLevel The compression level to use.
InputData The data to compress or decompress.
OutputData The output data after compression or decompression.

Method List

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

CompressBlock Compresses a block of data.
CompressData Compresses the specified data.
Config Sets or retrieves a configuration setting.
DecompressBlock Decompresses a block of data.
DecompressData Decompresses the specified data.
GetCompressionStream Creates an output stream used to write compressed data.
GetDecompressionStream Creates an input stream used to read data from a compressed stream.
Reset Resets the component.

Event List

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

CompressedData Fires with compressed data.
DecompressedData Fires with decompressed data.
Error Fires with information about errors during data delivery.

Config Settings

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

BuildInfo Information about the product's build.
GUIAvailable Whether or not a message loop is available for processing events.
LicenseInfo Information about the current license.
MaskSensitiveData Whether sensitive data is masked in log messages.
UseInternalSecurityAPI Whether or not to use the system security libraries or an internal implementation.

CloseBaseStream Property (Lz4 Component)

Whether or not to close the underlying stream.

Syntax

public bool CloseBaseStream { get; set; }
                
Public Property CloseBaseStream As Boolean

Default Value

True

Remarks

This property controls whether streams created via the GetCompressionStream and GetDecompressionStream methods will close their underlying streams when their Close method is invoked.

When enabled, the underlying streams are closed; otherwise, they will remain open.

CompressionLevel Property (Lz4 Component)

The compression level to use.

Syntax

public int CompressionLevel { get; set; }
                
Public Property CompressionLevel As Integer

Default Value

4

Remarks

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

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 component, and changing this property will have no effect on existing streams.

InputData Property (Lz4 Component)

The data to compress or decompress.

Syntax

public string InputData { get; set; }
public byte[] InputDataB { get; set; }
                
Public Property InputData As String
Public Property InputDataB As Byte()

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.

OutputData Property (Lz4 Component)

The output data after compression or decompression.

Syntax

public string OutputData { get; }
public byte[] OutputDataB { get; }
                
Public ReadOnly Property OutputData As String
Public ReadOnly Property OutputDataB As Byte()

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.

CompressBlock Method (Lz4 Component)

Compresses a block of data.

Syntax

public void CompressBlock(bool lastBlock);

Async Version
public async Task CompressBlock(bool lastBlock);
public async Task CompressBlock(bool lastBlock, CancellationToken cancellationToken);
                
Public Sub CompressBlock(ByVal LastBlock As Boolean)

Async Version
Public Sub CompressBlock(ByVal LastBlock As Boolean) As Task
Public Sub CompressBlock(ByVal LastBlock As Boolean, cancellationToken As CancellationToken) As Task

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.

CompressData Method (Lz4 Component)

Compresses the specified data.

Syntax

public void CompressData();

Async Version
public async Task CompressData();
public async Task CompressData(CancellationToken cancellationToken);
                
Public Sub CompressData()

Async Version
Public Sub CompressData() As Task
Public Sub CompressData(cancellationToken As CancellationToken) As Task

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.

Config Method (Lz4 Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);
                
Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

DecompressBlock Method (Lz4 Component)

Decompresses a block of data.

Syntax

public void DecompressBlock();

Async Version
public async Task DecompressBlock();
public async Task DecompressBlock(CancellationToken cancellationToken);
                
Public Sub DecompressBlock()

Async Version
Public Sub DecompressBlock() As Task
Public Sub DecompressBlock(cancellationToken As CancellationToken) As Task

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.

DecompressData Method (Lz4 Component)

Decompresses the specified data.

Syntax

public void DecompressData();

Async Version
public async Task DecompressData();
public async Task DecompressData(CancellationToken cancellationToken);
                
Public Sub DecompressData()

Async Version
Public Sub DecompressData() As Task
Public Sub DecompressData(cancellationToken As CancellationToken) As Task

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.

GetCompressionStream Method (Lz4 Component)

Creates an output stream used to write compressed data.

Syntax

public System.IO.Stream GetCompressionStream(System.IO.Stream baseStream);

Async Version
public async Task<System.IO.Stream> GetCompressionStream(System.IO.Stream baseStream);
public async Task<System.IO.Stream> GetCompressionStream(System.IO.Stream baseStream, CancellationToken cancellationToken);
                
Public Function GetCompressionStream(ByVal BaseStream As System.IO.Stream) As System.IO.Stream

Async Version
Public Function GetCompressionStream(ByVal BaseStream As System.IO.Stream) As Task(Of System.IO.Stream)
Public Function GetCompressionStream(ByVal BaseStream As System.IO.Stream, cancellationToken As CancellationToken) As Task(Of System.IO.Stream)

Remarks

This method returns a stream used to compress data as they are written to an underlying stream. The BaseStream parameter should be set to the stream to which the compressed data will be written.

The returned stream is independent of the component once created; thus, subsequently changing the CompressionLevel property has no effect on it. Closing the returned stream also closes BaseStream if the CloseBaseStream property is enabled before the stream is created.

GetDecompressionStream Method (Lz4 Component)

Creates an input stream used to read data from a compressed stream.

Syntax

public System.IO.Stream GetDecompressionStream(System.IO.Stream baseStream);

Async Version
public async Task<System.IO.Stream> GetDecompressionStream(System.IO.Stream baseStream);
public async Task<System.IO.Stream> GetDecompressionStream(System.IO.Stream baseStream, CancellationToken cancellationToken);
                
Public Function GetDecompressionStream(ByVal BaseStream As System.IO.Stream) As System.IO.Stream

Async Version
Public Function GetDecompressionStream(ByVal BaseStream As System.IO.Stream) As Task(Of System.IO.Stream)
Public Function GetDecompressionStream(ByVal BaseStream As System.IO.Stream, cancellationToken As CancellationToken) As Task(Of System.IO.Stream)

Remarks

This method returns a stream used to read decompressed data as they are read from an underlying compressed stream. The BaseStream parameter should be set to the stream providing the compressed data.

The returned stream is independent of the component once created. Closing the returned stream also closes BaseStream if the CloseBaseStream property is enabled before the stream is created.

Reset Method (Lz4 Component)

Resets the component.

Syntax

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);
                
Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

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

CompressedData Event (Lz4 Component)

Fires with compressed data.

Syntax

public event OnCompressedDataHandler OnCompressedData;

public delegate void OnCompressedDataHandler(object sender, Lz4CompressedDataEventArgs e);

public class Lz4CompressedDataEventArgs : EventArgs {
  public string Data { get; }
  public byte[] DataB { get; }
}

Async Version
public event AsyncEventHandler<Lz4CompressedDataEventArgs> OnCompressedData;

public delegate Task AsyncEventHandler<TEventArgs>(object sender, TEventArgs e);

public class Lz4CompressedDataEventArgs : AsyncEventArgs {
  public CancellationToken CancellationToken { get; }
  public string Data { get; }
  public byte[] DataB { get; }
}
                
Public Event OnCompressedData As OnCompressedDataHandler

Public Delegate Sub OnCompressedDataHandler(sender As Object, e As Lz4CompressedDataEventArgs)

Public Class Lz4CompressedDataEventArgs Inherits EventArgs
  Public ReadOnly Property Data As String
  Public ReadOnly Property DataB As Byte()
End Class

Async Version
Public Event OnCompressedData As AsyncEventHandler(Of Lz4CompressedDataEventArgs)

Public Delegate Function AsyncEventHandler(Of TEventArgs)(sender As Object, e As TEventArgs) As Task

Public Class Lz4CompressedDataEventArgs Inherits AsyncEventArgs
  Public ReadOnly Property CancellationToken As CancellationToken
  Public ReadOnly Property Data As String
  Public ReadOnly Property DataB As Byte()
End Class

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 (Lz4 Component)

Fires with decompressed data.

Syntax

public event OnDecompressedDataHandler OnDecompressedData;

public delegate void OnDecompressedDataHandler(object sender, Lz4DecompressedDataEventArgs e);

public class Lz4DecompressedDataEventArgs : EventArgs {
  public string Data { get; }
  public byte[] DataB { get; }
}

Async Version
public event AsyncEventHandler<Lz4DecompressedDataEventArgs> OnDecompressedData;

public delegate Task AsyncEventHandler<TEventArgs>(object sender, TEventArgs e);

public class Lz4DecompressedDataEventArgs : AsyncEventArgs {
  public CancellationToken CancellationToken { get; }
  public string Data { get; }
  public byte[] DataB { get; }
}
                
Public Event OnDecompressedData As OnDecompressedDataHandler

Public Delegate Sub OnDecompressedDataHandler(sender As Object, e As Lz4DecompressedDataEventArgs)

Public Class Lz4DecompressedDataEventArgs Inherits EventArgs
  Public ReadOnly Property Data As String
  Public ReadOnly Property DataB As Byte()
End Class

Async Version
Public Event OnDecompressedData As AsyncEventHandler(Of Lz4DecompressedDataEventArgs)

Public Delegate Function AsyncEventHandler(Of TEventArgs)(sender As Object, e As TEventArgs) As Task

Public Class Lz4DecompressedDataEventArgs Inherits AsyncEventArgs
  Public ReadOnly Property CancellationToken As CancellationToken
  Public ReadOnly Property Data As String
  Public ReadOnly Property DataB As Byte()
End Class

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 (Lz4 Component)

Fires with information about errors during data delivery.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, Lz4ErrorEventArgs e);

public class Lz4ErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Async Version
public event AsyncEventHandler<Lz4ErrorEventArgs> OnError;

public delegate Task AsyncEventHandler<TEventArgs>(object sender, TEventArgs e);

public class Lz4ErrorEventArgs : AsyncEventArgs {
  public CancellationToken CancellationToken { get; }
  public int ErrorCode { get; }
  public string Description { get; }
}
                
Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As Lz4ErrorEventArgs)

Public Class Lz4ErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Async Version
Public Event OnError As AsyncEventHandler(Of Lz4ErrorEventArgs)

Public Delegate Function AsyncEventHandler(Of TEventArgs)(sender As Object, e As TEventArgs) As Task

Public Class Lz4ErrorEventArgs Inherits AsyncEventArgs
  Public ReadOnly Property CancellationToken As CancellationToken
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

This event is fired in case of exceptional conditions during message processing. Normally, the component throws an exception.

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 (Lz4 Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

No configuration settings defined.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).
  • Last Valid Build: The last valid build number for which the license will work.
MaskSensitiveData:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to false, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments, this is not desirable. To use a completely managed security implementation, set this setting to true.

Setting this configuration setting to true tells the component to use the internal implementation instead of using the system security libraries.

On Windows, this setting is set to false by default. On Linux/macOS, this setting is set to true by default.

NOTE: This setting is static. The value set is applicable to all components used in the application.

When this value is set, the product's system dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file.

Trappable Errors (Lz4 Component)

Note that the streams returned by GetCompressionStream and GetDecompressionStream will throw standard IOExceptions in case of error.

ZipStream Errors

101   The data is of an invalid or unsupported format.
111   Can't open file for read.
150   An I/O error has occurred (details follow).