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 | Tells the component whether or not a message loop is available for processing events. |
| LicenseInfo | Information about the current license. |
| MaskSensitive | Whether sensitive data is masked in log messages. |
| UseInternalSecurityAPI | Tells the component 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.
Syntax
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
Default Value
4
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
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
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
public ZipstreamStreamFormats StreamFormat { get; set; }
enum ZipstreamStreamFormats { sfDeflate, sfZlib, sfGzip }
Public Property StreamFormat As ZipstreamStreamFormats
Enum ZipstreamStreamFormats sfDeflate sfZlib sfGzip End Enum
Default Value
0
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
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
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 Method (ZipStream 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 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
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
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
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.
DecompressData Method (ZipStream 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 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
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
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
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
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
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
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
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.
- 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.
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.
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). |