ZipStream Component

Properties Methods Events Configuration 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 non-fatal errors.

Configuration Settings

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


CodePage	The system code page used for Unicode to Multibyte translations.

CloseBaseStream Property (ZipStream Component)

Whether or not to close the underlying stream.

Syntax

[VB.NET]
Public Property CloseBaseStream As Boolean

[C#]
public bool CloseBaseStream {get; set;}

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.

Default Value

True

CompressionLevel Property (ZipStream Component)

The compression level to use.

Syntax

[VB.NET]
Public Property CompressionLevel As Integer

[C#]
public int CompressionLevel {get; set;}

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.

Default Value

InputData Property (ZipStream Component)

Specifies the data to compress or decompress.

Syntax

[VB.NET]
Public Property InputData As String
Public Property InputDataB As Byte()

[C#]
public string InputData {get; set;}
public byte[] InputDataB {get; set;}

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.

Default Value

OutputData Property (ZipStream Component)

The output data after compression or decompression.

Syntax

[VB.NET]
Public ReadOnlyProperty OutputData As String
Public ReadOnlyProperty OutputDataB As Byte()

[C#]
public string OutputData {get;}
public byte[] OutputDataB {get;}

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.

Default Value

StreamFormat Property (ZipStream Component)

The stream format to use.

Syntax

[VB.NET]
Public Property StreamFormat As ZipstreamStreamFormats

[C#]
public ZipstreamStreamFormats StreamFormat {get; set;}


enum ZipstreamStreamFormats {
  sfDeflate,
  sfZlib,
  sfGzip
}

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

Default Value

CompressBlock Method (ZipStream Component)

Compresses a block of data.

Syntax

[VB.NET]
Public Sub CompressBlock(ByVal LastBlock As Boolean)

[C#]
public void CompressBlock(bool lastBlock);

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

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.

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

[VB.NET]
Public Sub CompressData()

[C#]
public void CompressData();

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

[VB.NET]
Public Function Config(ByVal ConfigurationString As String) As String

[C#]
public string Config(string configurationString);

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

[VB.NET]
Public Sub DecompressBlock()

[C#]
public void DecompressBlock();

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

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.

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

[VB.NET]
Public Sub DecompressData()

[C#]
public void DecompressData();

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

[VB.NET]
Public Function GetCompressionStream(ByVal BaseStream As System.IO.Stream) As System.IO.Stream

[C#]
public System.IO.Stream GetCompressionStream(System.IO.Stream baseStream);

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

[VB.NET]
Public Function GetDecompressionStream(ByVal BaseStream As System.IO.Stream) As System.IO.Stream

[C#]
public System.IO.Stream GetDecompressionStream(System.IO.Stream baseStream);

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

[VB.NET]
Public Sub Reset()

[C#]
public void Reset();

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

[VB.NET]
Public Event OnCompressedData As OnCompressedDataHandler

[C#]
public event OnCompressedDataHandler OnCompressedData;

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

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

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

[VB.NET]
Public Event OnDecompressedData As OnDecompressedDataHandler

[C#]
public event OnDecompressedDataHandler OnDecompressedData;

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

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

Remarks

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

Data holds the current block of decompressed data.

Error Event (ZipStream Component)

Information about non-fatal errors.

Syntax

[VB.NET]
Public Event OnError As OnErrorHandler

[C#]
public event OnErrorHandler OnError;

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

class ZipstreamErrorEventArgs : EventArgs {
  string Description {get;}
  int ErrorCode {get;}
  int Index {get;}
  string Filename {get;}
  bool Ignore {get; set;}
}

Remarks

The Error event is fired when non-fatal errors occur during compression or decompression. Note that if this event is fired during decompression this may indicate that the archive is corrupt.

By default these errors will cause the component to fail with an exception. The exception may be overridden by setting Ignore to true. This will cause the error to be ignored, the file will be skipped if necessary, and the component will continue operation.

ErrorCode will correspond to one of the following errors:


1	Bad or missing CRC-32 checksum.
2	Failed to set creation date of a file.
111	Can't open file for read (skipping).

Description contains a textual description of the error. Index and Filename contain the array index (where appropriate) and filename of the file being processed at the time of the error.

Configuration 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 Configuration Settings


	GUIAvailable: Tells the component 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.
	UseBackgroundThread: Whether threads created by the component are background threads. If set to True, when the component creates a thread the thread's IsBackground property will be explicitly set to True. By default this setting is False.
	UseInternalSecurityAPI: Tells the component whether or not to use the system security libraries or an internal implementation. By default the component will use the system security libraries to perform cryptographic functions. When set to False 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 to True tells the component to use the internal implementation instead of using the system's security API. 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 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).