Programming with the Xceed Compression Class Library

Introduction

This section of the manual is designed to show you how to program using the Xceed Compression class library once you have read the Introduction to the Xceed Compression namespace. If you only need basic memory buffer compression and decompression operations, jump to the Programming the with QuickCompression class topic.

Topics

  • Compressing a stream

  • Decompressing a stream

  • Handling exceptions


Compressing a stream

Introduction

This topic demonstrates how to compress data as it is read from a stream using the CompressedStream class.

Basic steps

To compress a stream, the following steps must be performed:

  • Open the source into a stream.

  • Create an instance of the CompressedStream class around the source stream so that all the data read from the stream will be compressed.

For the purposes of this example, we will be using a FileStream as both the source and destination streams.

C# demonstration

using Xceed.Compression;

using System.IO;

FileStream sourceStream = new FileStream( @"c:\test.txt", FileMode.Open, FileAccess.Read );

FileStream destStream = new FileStream( @"c:\test.cmp", FileMode.Create, FileAccess.Write );

CompressedStream compStream = new CompressedStream( destStream );

VB.NET demonstration

Imports Xceed.Compression

Imports System.IO

Dim sourceStream As New FileStream( "c:\test.txt", FileMode.Open, FileAccess.Read )

Dim destStream As New FileStream( "c:\test.cmp", FileMode.Create, FileAccess.Write )

Dim compStream As New CompressedStream( sourceStream )

Things you should consider

The main questions you should ask yourself when compressing a stream are:

  • Do you want to prevent the source stream from being closed when the CompressedStream is closed? Set the Transient property of the CompressedStream class to true.


Decompressing a stream

Introduction

This topic demonstrates how to decompress data as it is read from a stream using the CompressedStream class.

Basic steps

To decompress a stream, the following steps must be performed:

  • Open the source into a stream.

  • Create an instance of the CompressedStream class around the source stream so that all the data read from the stream will be decompressed.

For the purposes of this example, we will be using a FileStream as both the source and destination streams.

C# demonstration

using Xceed.Compression;

using System.IO;

FileStream sourceStream = new FileStream( @"c:\test.cmp", FileMode.Open, FileAccess.Read );

FileStream destStream = new FileStream( @"c:\test.txt", FileMode.Create, FileAccess.Write );

CompressedStream compStream = new CompressedStream( sourceStream );

VB.NET demonstration

Imports Xceed.Compression

Imports System.IO

Dim sourceStream As New FileStream( "c:\test.cmp", FileMode.Open, FileAccess.Read )

Dim destStream As New FileStream( "c:\test.txt", FileMode.Create, FileAccess.Write )

Dim compStream As New CompressedStream( sourceStream )

Things you should consider

The main questions you should ask yourself when decompressing a stream are:

  • Do you want to prevent the source stream from being closed when the CompressedStream is closed? Set the Transient property of the CompressedStream class to true.


Exceptions

Xceed.Compression Namespace

Handling exceptions

Introduction

An exception is any error condition or unexpected behavior encountered by an executing program. Whenever an error occurs, an Exception object is created to represent the exception.

Handling exceptions.

The exceptions that can be thrown by the Xceed.Compression namespace, are handled in the same manner as regular run-time exceptions using Try/Catch blocks. It is possible to intercept the exceptions before they are thrown using the ItemException event in order to try and recover from the exception before it is actually thrown.

The following table provides a listing of all the exceptions that can be thrown when an error occurs within the Xceed.Compression namespace:

Exception | Description
CompressionException | Exception that is thrown when there is a problem compressing or decompressing data.
CompressionInternalException | Exception that is thrown when something unexpected occurs while compressing or decompressing data.

The CompressionException class derives directly from the FileSystemEvents class. The CompressionInternalException class derives from the CompressionException class.

For more information regarding the exception classes native to the Xceed.FileSystem namespace, please refer to the Handling exceptions topic of this namespace.


Programming with the QuickCompression Class

Introduction

This section of the manual has but one goal: To show you, as fast as possible, how to start programming using the QuickCompression class.

The QuickCompression class exposes static methods that allow quick and easy compression and decompression of memory buffers. For more complex streaming compression and decompression operations, jump to the Programming with the Xceed Compression Class Library topic.

If all else fails, use the "search" feature of the manual, or browse the sample applications. Feel free to contact Xceed Software at any time if you have questions.

Topics

  • Compressing a memory buffer

  • Decompressing a memory buffer

  • Converting strings to byte arrays

  • Handling exceptions


Compressing a memory buffer

Introduction

This topic demonstrates how to compress a memory buffer.

C# demonstrations

The Compress method has three overloads that can be used:

using Xceed.Compression;

byte[] sourceBuffer = new byte[ 256 ];

The first overload only requires the memory buffer to compress as a parameter.

byte[] destBuffer = QuickCompression.Compress( sourceBuffer );

With second overload of the Compress method, you can specify the compression method and the compression level to use to compress the memory buffer. This is done by setting the CompressionMethod and CompressionLevel parameters.

byte[] destBuffer = QuickCompression.Compress( sourceBuffer, CompressionMethod.Deflated,

CompressionLevel.Normal );

The third overload of the Compress method provides the same options as the previous overloads as well as provides the opportunity to specify the offset from which to begin compressing the memory buffer and the number of bytes to compress. This is done by setting the offset and the count parameters.

byte[] destBuffer = QuickCompression.Compress( sourceBuffer, 0, 100,

CompressionMethod.Deflated, CompressionLevel.Normal );

VB.NET demonstrations

The Compress method has three overloads that can be used:

Imports Xceed.Compression

Dim sourceBuffer(255) As Byte

The first overload only requires the memory buffer to compress as a parameter.

Dim destBuffer() As Byte = QuickCompression.Compress( sourceBuffer )

With second overload of the Compress method, you can specify the compression method and the compression level to use to compress the memory buffer. This is done by setting the CompressionMethod and CompressionLevel parameters.

Dim destBuffer() As Byte = QuickCompression.Compress( sourceBuffer, CompressionMethod.Deflated,

CompressionLevel.Normal )

The third overload of the Compress method provides the same options as the previous overloads as well as provides the opportunity to specify the offset from which to begin compressing the memory buffer and the number of bytes to compress. This is done by setting the offset and the count parameters.

Dim destBuffer() As Byte = QuickCompression.Compress( sourceBuffer, 0, 100,

CompressionMethod.Deflated, CompressionLevel.Normal )

Things you should consider

The main questions you should ask yourself when compressing a memory buffer are:

  • Do you want to compress streaming data? Use the CompressedStream class rather than the QuickCompression class.

  • Do you need to convert a string to a byte array? Jump to the Converting strings to byte arrays topic.


Decompressing a memory buffer

Introduction

This topic demonstrates how to decompress compressed memory buffers.

C# demonstration

The Decompress method has three overloads that can be used:

using Xceed.Compression;

The first overload only requires the memory buffer to decompress as a parameter.

byte[] destBuffer = QuickCompression.Decompress( compressedBuffer );

With the second overload of the decompress method, you can specify the compression method to use to decompress the memory buffer. This is done by setting the CompressionMethod parameter.

byte[] destBuffer = QuickCompression.Decompress( compressedBuffer, CompressionMethod.Deflated );

The third overload of the decompress method provides the same options as the previous overloads as well as provides the opportunity to specify the offset from which to begin decompressing the memory buffer and the number of bytes to decompress. This is done by setting the offset and the count parameters.

byte[] destBuffer = QuickCompression.Decompress( compressedBuffer, 0, 100,

CompressionMethod.Deflated );

VB.NET demonstration

The Decompress method has three overloads that can be used:

Imports Xceed.Compression

The first overload only requires the memory buffer to decompress as a parameter.

Dim destBuffer() As Byte = QuickCompression.Decompress( compressedBuffer )

With second overload of the decompress method, you can specify the compression method to use to decompress the memory buffer. This is done by setting the CompressionMethod parameter.

Dim destBuffer() As Byte = QuickCompression.Decompress( compressedBuffer, CompressionMethod.Deflated )

The third overload of the decompress method provides the same options as the previous overloads as well as provides the opportunity to specify the offset from which to begin decompressing the memory buffer and the number of bytes to decompress. This is done by setting the offset and the count parameters.

Dim destBuffer() As Byte = QuickCompression.Decompress( compressedBuffer, 0, 100,

CompressionMethod.Deflated )

Things you should consider

The main questions you should ask yourself when decompressing a memory buffer are:

  • Do you want to decompress streaming compressed data? Use the CompressedStream class rather than the QuickCompression class.

  • Do you need to convert a byte array to a string? Jump to the Converting strings to byte arrays topic.


Converting strings to byte arrays

Introduction

This topic demonstrates how to convert strings into byte arrays in order to compress them using the QuickCompression class. It also demonstrates how to convert a byte array back to a string once it has been decompressed.

Basic Steps

To convert a string into a byte array, the following steps must be performed.

  • Call the GetBytes methods of the System.Text.Encoding class to encode the string. This method will return a byte array containing the encoded string.

  • You can then compress the byte array using the Compress method of the QuickCompression class.

To convert the uncompressed byte array back into a string:

  • Call the Decompress method of the QuickCompression class to decompress the compressed byte array.

  • Call the GetString method of the System.Text.Encoding class to decode the byte array back into a string.

C# demonstration

string stringData = "This is the data to compress";

byte[] byteData = System.Text.Encoding.Default.GetBytes( stringData );

byte[] compressedData = Xceed.Compression.QuickCompression.Compress( byteData );

byte[] uncompressedData = Xceed.Compression.QuickCompression.Decompress( compressedData );

string data = System.Text.Encoding.Default.GetString( uncompressedData );

Console.WriteLine( data );

VB.NET demonstration

Dim stringData As String = "This is the data to compress"

Dim byteData() As Byte = System.Text.Encoding.Default.GetBytes( stringData )

Dim compressedData() As Byte = Xceed.Compression.QuickCompression.Compress( byteData )

Dim uncompressedData() As Byte = Xceed.Compression.QuickCompression.Decompress( compressedData )

Dim data As String = System.Text.Encoding.Default.GetString( uncompressedData )

Console.WriteLine( data )


Handling exceptions

Introduction

An exception is any error condition or unexpected behavior encountered by an executing program. Whenever an error occurs, an Exception object is created to represent the exception. The CompressionException exception class that is thrown by the QuickCompression class is handled in the same manner as regular run-time exceptions using Try/Catch blocks.

C# demonstration

This example assumes that you are in a console application.

try

{

byte[] destBuffer = Xceed.Compression.QuickCompression.Decompress( compressedBuffer );

}

catch( Xceed.Compression.CompressionException e )

{

Console.WriteLine( e.Message );

}

VB.NET demonstration

This example assumes that you are in a console application

Try

Dim destBuffer() As Byte = Xceed.Compression.QuickCompression.Decompress( compressedBuffer )

Catch e As Xceed.Compression.CompressionException

Console.WriteLine( e.Message )

End Try


Introduction to the Xceed Compression namespace

Xceed.Compression Namespace

Introduction to the Xceed.Compression namespace

Introduction

The Xceed.Compression namespace defines the CompressedStream class which can be constructed around any kind of System.IO.Stream object to compress data that is written to the stream, and decompress data that is read from the stream. It also defines the QuickCompression class which exposes static methods that allow quick and easy compression and decompression of memory buffers.

The following diagram represents the relationship between the CompressedStream and the Stream classes:

CompressedStream class

The CompressedStream class is a pass-through stream that applies compression and decompression to any type of inner stream, for example a FileStream, MemoryStream, etc...

Keep in mind that once a CompressedStream class is created around a Stream class, it becomes the owner of the Stream class and both streams will be closed when the CompressedStream is closed. To bypass this behavior, you can set the Transient property of the CompressedStream class to true. This will prevent the Stream class from being closed along with the CompressedStream class.

QuickCompression class

The QuickCompression class exposes static methods that allow quick and easy compression and decompression of memory buffers. The QuickCompression class does not provide as much flexibility as the CompressedStream class. In cases where more complex operations, such as streaming, are required, developers will need to use the CompressedStream class.


Full Template

Xceed.Compression Namespace

Header Example

Extra Information example

public Example {abstract get; abstract set;}

Property Value Example

Description of property.

Remarks

Remarks

Note: Note

Example Table Header

Example Type | Example Description
example1 | description example
example2 | description example

See Also