ZipStream Component

Properties Methods Events Config Settings Errors

The ZipStream component is used to perform compression or decompression.

Syntax

nsoftware.IPWorksZip.ZipStream

Remarks

The ZipStream component provides a way to compress and decompress streamed data.

Data may be operated on in multiple ways as discussed below. The StreamFormat property specifies the algorithm to us. Possible values are:

Deflate
Zlib
Gzip

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 it becomes available.

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

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

Compress Data

Set InputData to the current block to be compressed. Next call CompressBlock to compress the current block. Note that CompressBlock takes a LastBlock parameter. If the block of data is the final block to be compressed set this to True. For all other blocks set this to 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. For example:

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

Note that OutputData is not applicable when compressing block data.

Decompress Data

Set InputData to the current block to be decompressed. Next call DecompressBlock 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. For example:

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 OutputData 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 InputData before calling either method.

To compress and decompress data in blocks (chunks) see CompressBlock and DecompressBlock.

Compress Data

Set InputData to the decompressed data. This should be the entire data to be compressed. Next call CompressData. After compression OutputData will hold the compressed data. For example:

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

Set InputData to the compressed data. This should be the entire data to be decompressed. Next call DecompressData. After decompression OutputData will hold the decompressed data. For example:

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

In addition to OutputData, the compressed 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	Specifies the data to compress or decompress.
OutputData	The output data after compression or decompression.
StreamFormat	The stream format to use.

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	This event fires with compressed data.
DecompressedData	This event fires with decompressed data.
Error	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 (ZipStream Component)

Whether or not to close the underlying stream.

public bool CloseBaseStream { get; set; }

Public Property CloseBaseStream As Boolean

Default Value

True

Remarks

If true, streams created by GetCompressionStream and GetDecompressionStream will close their underlying streams when their Close method is invoked. If false, the underlying streams will remain open.

CompressionLevel Property (ZipStream Component)

The compression level to use.

Syntax

C#
VB.NET

public int CompressionLevel { get; set; }

Public Property CompressionLevel As Integer

Default Value

Remarks

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 GetCompressionStream is invoked the stream will be created with the specified compression level. After a stream has been created it is independent of the control, and changing CompressionLevel will have no effect on existing streams.

InputData Property (ZipStream Component)

Specifies the data to compress or decompress.

Syntax

C#
VB.NET

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 calling DecompressData or DecompressBlock.

When compressing this should be set to the decompressed data before calling CompressData or CompressBlock.

When performing operations on multiple chunks of data, note that this property is not automatically cleared after each operation.

OutputData Property (ZipStream Component)

The output data after compression or decompression.

Syntax

C#
VB.NET

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 CompressData or DecompressData is called.

This property is not applicable when calling CompressBlock or DecompressBlock.

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

StreamFormat Property (ZipStream Component)

The stream format to use.

Syntax

C#
VB.NET

public ZipStreamStreamFormats StreamFormat { get; set; }

enum ZipStreamStreamFormats {
  sfDeflate,
  sfZlib,
  sfGzip
}

Public Property StreamFormat As ZipstreamStreamFormats

Enum ZipStreamStreamFormats
  sfDeflate
  sfZlib
  sfGzip
End Enum

Default Value

Remarks

The stream format to use, by default Deflate.

All three stream formats use the Deflate algorithm specified in RFC 1951, which is the same algorithm used by Zip. The Zlib stream format adds a two-byte header and an Adler-32 checksum; the Gzip format adds a longer header and a CRC checksum, and is identical to the Gzip file format.

Caution: The terms zlib and deflate are sometimes used interchangeably (which is technically incorrect).

CompressBlock Method (ZipStream Component)

Compresses a block of data.

Syntax

C#
VB.NET

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 InputData.

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

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

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

Compress Data

Note that OutputData is not applicable when compressing block data.

Decompress Data

Set InputData to the current block to be decompressed. Next call DecompressBlock to decompress the current block.

Note that OutputData is not applicable when decompressing block data.

CompressData Method (ZipStream Component)

Compresses the specified data.

Syntax

C#
VB.NET

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 InputData. After calling this method OutputData 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 InputData before calling either method.

To compress and decompress data in blocks (chunks) see CompressBlock and DecompressBlock.

Compress Data

Set InputData to the decompressed data. This should be the entire data to be compressed. Next call CompressData. After compression OutputData will hold the compressed data. For example:

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

Set InputData to the compressed data. This should be the entire data to be decompressed. Next call DecompressData. After decompression OutputData will hold the decompressed data. For example:

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

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

Config Method (ZipStream Component)

Sets or retrieves a configuration setting.

Syntax

C#
VB.NET

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

Decompresses a block of data.

Syntax

C#
VB.NET

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 InputData.

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

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

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

Compress Data

Note that OutputData is not applicable when compressing block data.

Decompress Data

Set InputData to the current block to be decompressed. Next call DecompressBlock to decompress the current block.

Note that OutputData is not applicable when decompressing block data.

DecompressData Method (ZipStream Component)

Decompresses the specified data.

Syntax

C#
VB.NET

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 InputData. After calling this method OutputData 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 InputData before calling either method.

To compress and decompress data in blocks (chunks) see CompressBlock and DecompressBlock.

Compress Data

Set InputData to the decompressed data. This should be the entire data to be compressed. Next call CompressData. After compression OutputData will hold the compressed data. For example:

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

Set InputData to the compressed data. This should be the entire data to be decompressed. Next call DecompressData. After decompression OutputData will hold the decompressed data. For example:

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

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

GetCompressionStream Method (ZipStream Component)

Creates an output stream used to write compressed data.

Syntax

C#
VB.NET

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

GetCompressionStream returns a System.IO.Stream used to compress data as it is written to an underlying stream. The BaseStream parameter should be the System.IO.Stream to which the compressed data will be written.

The format (zlib or gzip) is selected with the StreamFormat property; zlib is the default.

The return value provides the following standard System.IO.Stream methods. Please see the official .NET Framework documentation for details.

public bool CanWrite { get }

Returns true.

public void Close()

Closes the stream. Also closes BaseStream if CloseBaseStream is set to true before this stream is created.

public void Flush()

Flushes the output stream, and forces all data to be compressed and written to the underlying stream. Caution: Flush only when necessary, as repeated flushing may degrade the compression ratio.

public void WriteByte(byte b)

Compresses and writes the byte b to the underlying stream.

public void Write(byte[] b, int off, int len)

Compresses and writes the byte array b to the underlying stream.

Other System.IO.Stream methods will throw a NotSupportedException.

GetDecompressionStream Method (ZipStream Component)

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

Syntax

C#
VB.NET

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

GetDecompressionStream returns a System.IO.Stream used to read the decompressed data from a compressed stream. The BaseStream parameter should be the System.IO.Stream providing the compressed data.

The format (zlib or gzip) is selected with the StreamFormat property; zlib is the default.

The return value provides the following standard System.IO.Stream methods. Please see the official .NET Framework documentation for details.

public bool CanRead { get }

Returns true.

public void Close()

Closes the stream. Also closes BaseStream if CloseBaseStream is set to true before this stream is created.

public int Read(byte[] b, int off, int len)

Reads decompressed data into the provided byte array, and returns the number of bytes actually read. Returns -1 if the stream was finished.

public int ReadByte()

Reads a single byte of data from the input stream. Returns -1 if no data was able to be read.

Other System.IO.Stream methods will throw a NotSupportedException.

Reset Method (ZipStream Component)

Resets the component.

Syntax

C#
VB.NET

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

Reset resets the state of the component. All properties will be set to their default values, and any files open will be closed.

CompressedData Event (ZipStream Component)

This event fires with compressed data.

Syntax

C#
VB.NET

public event OnCompressedDataHandler OnCompressedData;

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

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

Public Event OnCompressedData As OnCompressedDataHandler

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

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

Remarks

The CompressedData event fires as compressed data is available when CompressData or CompressBlock is called. This may fire one or more times when data is compressed.

Data holds the current block of compressed data.

DecompressedData Event (ZipStream Component)

This event fires with decompressed data.

Syntax

C#
VB.NET

public event OnDecompressedDataHandler OnDecompressedData;

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

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

Public Event OnDecompressedData As OnDecompressedDataHandler

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

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

Remarks

The DecompressedData event fires as compressed data is available when DecompressData or DecompressBlock is called. This may fire one or more times as data is decompressed.

Data holds the current block of decompressed data.

Error Event (ZipStream Component)

Information about errors during data delivery.

Syntax

C#
VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

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

Remarks

The Error 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 (ZipStream 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.

This setting only works on these components: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

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.

If using the .NET Standard Library, this setting will be true on all platforms. The .NET Standard library does not support using the system security libraries.

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 (ZipStream 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).