Detailed Description

Encoder and Decoder for ZLIB and DEFLATE (IETF RFC1950 and RFC1951).

This class compresses and decompresses data according to the Deflate algorithm and optionally, the ZLIB format, as documented in RFC 1950 - ZLIB

and RFC 1951 - DEFLATE

.

Public Member Functions

 ZlibCodec ()
 Create a ZlibCodec. More...
 
 ZlibCodec (CompressionMode mode)
 Create a ZlibCodec that either compresses or decompresses. More...
 
int InitializeInflate ()
 Initialize the inflation state. More...
 
int InitializeInflate (bool expectRfc1950Header)
 Initialize the inflation state with an explicit flag to govern the handling of RFC1950 header bytes. More...
 
int InitializeInflate (int windowBits)
 Initialize the ZlibCodec for inflation, with the specified number of window bits. More...
 
int InitializeInflate (int windowBits, bool expectRfc1950Header)
 Initialize the inflation state with an explicit flag to govern the handling of RFC1950 header bytes. More...
 
int EndInflate ()
 Ends an inflation session. More...
 
int SyncInflate ()
 I don't know what this does! More...
 
int InitializeDeflate ()
 Initialize the ZlibCodec for deflation operation. More...
 
int InitializeDeflate (CompressionLevel level)
 Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel. More...
 
int InitializeDeflate (CompressionLevel level, bool wantRfc1950Header)
 Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, and the explicit flag governing whether to emit an RFC1950 header byte pair. More...
 
int InitializeDeflate (CompressionLevel level, int bits)
 Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, and the specified number of window bits. More...
 
int InitializeDeflate (CompressionLevel level, int bits, bool wantRfc1950Header)
 Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, the specified number of window bits, and the explicit flag governing whether to emit an RFC1950 header byte pair. More...
 
int EndDeflate ()
 End a deflation session. More...
 
void ResetDeflate ()
 Reset a codec for another deflation session. More...
 
int SetDictionary (byte[] dictionary)
 Set the dictionary to be used for either Inflation or Deflation. More...
 

Public Attributes

byte[] InputBuffer
 The buffer from which data is taken. More...
 
int NextIn
 An index into the InputBuffer array, indicating where to start reading. More...
 
int AvailableBytesIn
 The number of bytes available in the InputBuffer, starting at NextIn. More...
 
long TotalBytesIn
 Total number of bytes read so far, through all calls to Inflate()/Deflate(). More...
 
byte[] OutputBuffer
 Buffer to store output data. More...
 
int NextOut
 An index into the OutputBuffer array, indicating where to start writing. More...
 
int AvailableBytesOut
 The number of bytes available in the OutputBuffer, starting at NextOut. More...
 
long TotalBytesOut
 Total number of bytes written to the output so far, through all calls to Inflate()/Deflate(). More...
 
System.String Message
 used for diagnostics, when something goes wrong! More...
 
CompressionLevel CompressLevel = CompressionLevel.Default
 The compression level to use in this codec. Useful only in compression mode. More...
 
int WindowBits = ZlibConstants.WindowBitsDefault
 The number of Window Bits to use. More...
 

Package Functions

int Inflate (FlushType flush)
 Inflate the data in the InputBuffer, placing the result in the OutputBuffer. More...
 
int Deflate (FlushType flush)
 Deflate one batch of data. More...
 
int SetDeflateParams (CompressionLevel level, CompressionStrategy strategy)
 Set the CompressionStrategy and CompressionLevel for a deflation session. More...
 
void flush_pending ()
 
int read_buf (byte[] buf, int start, int size)
 

Package Attributes

DeflateManager dstate
 
InflateManager istate
 
uint _Adler32
 
CompressionStrategy Strategy = CompressionStrategy.Default
 The compression strategy to use. More...
 

Properties

int Adler32 [get]
 The Adler32 checksum on the data transferred through the codec so far. You probably don't need to look at this. More...
 

Private Member Functions

int _InternalInitializeDeflate (bool wantRfc1950Header)
 

Constructor & Destructor Documentation

Zlib.ZlibCodec.ZlibCodec ( )
inline

Create a ZlibCodec.

If you use this default constructor, you will later have to explicitly call InitializeInflate() or InitializeDeflate() before using the ZlibCodec to compress or decompress.

Zlib.ZlibCodec.ZlibCodec ( CompressionMode  mode)
inline

Create a ZlibCodec that either compresses or decompresses.

Parameters
modeIndicates whether the codec should compress (deflate) or decompress (inflate).

Member Function Documentation

int Zlib.ZlibCodec._InternalInitializeDeflate ( bool  wantRfc1950Header)
inlineprivate
int Zlib.ZlibCodec.Deflate ( FlushType  flush)
inlinepackage

Deflate one batch of data.

You must have set InputBuffer and OutputBuffer before calling this method.

private void DeflateBuffer(CompressionLevel level)
{
int bufferSize = 1024;
byte[] buffer = new byte[bufferSize];
ZlibCodec compressor = new ZlibCodec();
Console.WriteLine("\n============================================");
Console.WriteLine("Size of Buffer to Deflate: {0} bytes.", UncompressedBytes.Length);
MemoryStream ms = new MemoryStream();
int rc = compressor.InitializeDeflate(level);
compressor.InputBuffer = UncompressedBytes;
compressor.NextIn = 0;
compressor.AvailableBytesIn = UncompressedBytes.Length;
compressor.OutputBuffer = buffer;
// pass 1: deflate
do
{
compressor.NextOut = 0;
compressor.AvailableBytesOut = buffer.Length;
rc = compressor.Deflate(FlushType.None);
if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END)
throw new Exception("deflating: " + compressor.Message);
ms.Write(compressor.OutputBuffer, 0, buffer.Length - compressor.AvailableBytesOut);
}
while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0);
// pass 2: finish and flush
do
{
compressor.NextOut = 0;
compressor.AvailableBytesOut = buffer.Length;
rc = compressor.Deflate(FlushType.Finish);
if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK)
throw new Exception("deflating: " + compressor.Message);
if (buffer.Length - compressor.AvailableBytesOut > 0)
ms.Write(buffer, 0, buffer.Length - compressor.AvailableBytesOut);
}
while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0);
compressor.EndDeflate();
ms.Seek(0, SeekOrigin.Begin);
CompressedBytes = new byte[compressor.TotalBytesOut];
ms.Read(CompressedBytes, 0, CompressedBytes.Length);
}
Parameters
flushwhether to flush all data as you deflate. Generally you will want to use Z_NO_FLUSH here, in a series of calls to Deflate(), and then call EndDeflate() to flush everything.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.EndDeflate ( )
inline

End a deflation session.

Call this after making a series of one or more calls to Deflate(). All buffers are flushed.

Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.EndInflate ( )
inline

Ends an inflation session.

Call this after successively calling Inflate(). This will cause all buffers to be flushed. After calling this you cannot call Inflate() without a intervening call to one of the InitializeInflate() overloads.

Returns
Z_OK if everything goes well.
void Zlib.ZlibCodec.flush_pending ( )
inlinepackage
int Zlib.ZlibCodec.Inflate ( FlushType  flush)
inlinepackage

Inflate the data in the InputBuffer, placing the result in the OutputBuffer.

You must have set InputBuffer and OutputBuffer, NextIn and NextOut, and AvailableBytesIn and AvailableBytesOut before calling this method.

private void InflateBuffer()
{
int bufferSize = 1024;
byte[] buffer = new byte[bufferSize];
ZlibCodec decompressor = new ZlibCodec();
Console.WriteLine("\n============================================");
Console.WriteLine("Size of Buffer to Inflate: {0} bytes.", CompressedBytes.Length);
MemoryStream ms = new MemoryStream(DecompressedBytes);
int rc = decompressor.InitializeInflate();
decompressor.InputBuffer = CompressedBytes;
decompressor.NextIn = 0;
decompressor.AvailableBytesIn = CompressedBytes.Length;
decompressor.OutputBuffer = buffer;
// pass 1: inflate
do
{
decompressor.NextOut = 0;
decompressor.AvailableBytesOut = buffer.Length;
rc = decompressor.Inflate(FlushType.None);
if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END)
throw new Exception("inflating: " + decompressor.Message);
ms.Write(decompressor.OutputBuffer, 0, buffer.Length - decompressor.AvailableBytesOut);
}
while (decompressor.AvailableBytesIn > 0 || decompressor.AvailableBytesOut == 0);
// pass 2: finish and flush
do
{
decompressor.NextOut = 0;
decompressor.AvailableBytesOut = buffer.Length;
rc = decompressor.Inflate(FlushType.Finish);
if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK)
throw new Exception("inflating: " + decompressor.Message);
if (buffer.Length - decompressor.AvailableBytesOut > 0)
ms.Write(buffer, 0, buffer.Length - decompressor.AvailableBytesOut);
}
while (decompressor.AvailableBytesIn > 0 || decompressor.AvailableBytesOut == 0);
decompressor.EndInflate();
}
Parameters
flushThe flush to use when inflating.
Returns
Z_OK if everything goes well.
int Zlib.ZlibCodec.InitializeDeflate ( )
inline

Initialize the ZlibCodec for deflation operation.

The codec will use the MAX window bits and the default level of compression.

int bufferSize = 40000;
byte[] CompressedBytes = new byte[bufferSize];
byte[] DecompressedBytes = new byte[bufferSize];
ZlibCodec compressor = new ZlibCodec();
compressor.InitializeDeflate(CompressionLevel.Default);
compressor.InputBuffer = System.Text.ASCIIEncoding.ASCII.GetBytes(TextToCompress);
compressor.NextIn = 0;
compressor.AvailableBytesIn = compressor.InputBuffer.Length;
compressor.OutputBuffer = CompressedBytes;
compressor.NextOut = 0;
compressor.AvailableBytesOut = CompressedBytes.Length;
while (compressor.TotalBytesIn != TextToCompress.Length && compressor.TotalBytesOut < bufferSize)
{
compressor.Deflate(FlushType.None);
}
while (true)
{
int rc= compressor.Deflate(FlushType.Finish);
if (rc == ZlibConstants.Z_STREAM_END) break;
}
compressor.EndDeflate();
Returns
Z_OK if all goes well. You generally don't need to check the return code.
int Zlib.ZlibCodec.InitializeDeflate ( CompressionLevel  level)
inline

Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel.

The codec will use the maximum window bits (15) and the specified CompressionLevel. It will emit a ZLIB stream as it compresses.

Parameters
levelThe compression level for the codec.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.InitializeDeflate ( CompressionLevel  level,
bool  wantRfc1950Header 
)
inline

Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, and the explicit flag governing whether to emit an RFC1950 header byte pair.

The codec will use the maximum window bits (15) and the specified CompressionLevel. If you want to generate a zlib stream, you should specify true for wantRfc1950Header. In this case, the library will emit a ZLIB header, as defined in RFC 1950

, in the compressed stream.

Parameters
levelThe compression level for the codec.
wantRfc1950Headerwhether to emit an initial RFC1950 byte pair in the compressed stream.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.InitializeDeflate ( CompressionLevel  level,
int  bits 
)
inline

Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, and the specified number of window bits.

The codec will use the specified number of window bits and the specified CompressionLevel.

Parameters
levelThe compression level for the codec.
bitsthe number of window bits to use. If you don't know what this means, don't use this method.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.InitializeDeflate ( CompressionLevel  level,
int  bits,
bool  wantRfc1950Header 
)
inline

Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, the specified number of window bits, and the explicit flag governing whether to emit an RFC1950 header byte pair.

Parameters
levelThe compression level for the codec.
wantRfc1950Headerwhether to emit an initial RFC1950 byte pair in the compressed stream.
bitsthe number of window bits to use. If you don't know what this means, don't use this method.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.InitializeInflate ( )
inline

Initialize the inflation state.

It is not necessary to call this before using the ZlibCodec to inflate data; It is implicitly called when you call the constructor.

Returns
Z_OK if everything goes well.
int Zlib.ZlibCodec.InitializeInflate ( bool  expectRfc1950Header)
inline

Initialize the inflation state with an explicit flag to govern the handling of RFC1950 header bytes.

By default, the ZLIB header defined in RFC 1950

is expected. If you want to read a zlib stream you should specify true for expectRfc1950Header. If you have a deflate stream, you will want to specify false. It is only necessary to invoke this initializer explicitly if you want to specify false.

Parameters
expectRfc1950Headerwhether to expect an RFC1950 header byte pair when reading the stream of data to be inflated.
Returns
Z_OK if everything goes well.
int Zlib.ZlibCodec.InitializeInflate ( int  windowBits)
inline

Initialize the ZlibCodec for inflation, with the specified number of window bits.

Parameters
windowBitsThe number of window bits to use. If you need to ask what that is, then you shouldn't be calling this initializer.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.InitializeInflate ( int  windowBits,
bool  expectRfc1950Header 
)
inline

Initialize the inflation state with an explicit flag to govern the handling of RFC1950 header bytes.

If you want to read a zlib stream you should specify true for expectRfc1950Header. In this case, the library will expect to find a ZLIB header, as defined in RFC 1950

, in the compressed stream. If you will be reading a DEFLATE or GZIP stream, which does not have such a header, you will want to specify false.

Parameters
expectRfc1950Headerwhether to expect an RFC1950 header byte pair when reading the stream of data to be inflated.
windowBitsThe number of window bits to use. If you need to ask what that is, then you shouldn't be calling this initializer.
Returns
Z_OK if everything goes well.
int Zlib.ZlibCodec.read_buf ( byte[]  buf,
int  start,
int  size 
)
inlinepackage
void Zlib.ZlibCodec.ResetDeflate ( )
inline

Reset a codec for another deflation session.

Call this to reset the deflation state. For example if a thread is deflating non-consecutive blocks, you can call Reset() after the Deflate(Sync) of the first block and before the next Deflate(None) of the second block.

Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.SetDeflateParams ( CompressionLevel  level,
CompressionStrategy  strategy 
)
inlinepackage

Set the CompressionStrategy and CompressionLevel for a deflation session.

Parameters
levelthe level of compression to use.
strategythe strategy to use for compression.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.SetDictionary ( byte[]  dictionary)
inline

Set the dictionary to be used for either Inflation or Deflation.

Parameters
dictionaryThe dictionary bytes to use.
Returns
Z_OK if all goes well.
int Zlib.ZlibCodec.SyncInflate ( )
inline

I don't know what this does!

Returns
Z_OK if everything goes well.

Member Data Documentation

uint Zlib.ZlibCodec._Adler32
package
int Zlib.ZlibCodec.AvailableBytesIn

The number of bytes available in the InputBuffer, starting at NextIn.

Generally you should set this to InputBuffer.Length before the first Inflate() or Deflate() call. The class will update this number as calls to Inflate/Deflate are made.

int Zlib.ZlibCodec.AvailableBytesOut

The number of bytes available in the OutputBuffer, starting at NextOut.

Generally you should set this to OutputBuffer.Length before the first Inflate() or Deflate() call. The class will update this number as calls to Inflate/Deflate are made.

CompressionLevel Zlib.ZlibCodec.CompressLevel = CompressionLevel.Default

The compression level to use in this codec. Useful only in compression mode.

DeflateManager Zlib.ZlibCodec.dstate
package
byte [] Zlib.ZlibCodec.InputBuffer

The buffer from which data is taken.

InflateManager Zlib.ZlibCodec.istate
package
System.String Zlib.ZlibCodec.Message

used for diagnostics, when something goes wrong!

int Zlib.ZlibCodec.NextIn

An index into the InputBuffer array, indicating where to start reading.

int Zlib.ZlibCodec.NextOut

An index into the OutputBuffer array, indicating where to start writing.

byte [] Zlib.ZlibCodec.OutputBuffer

Buffer to store output data.

CompressionStrategy Zlib.ZlibCodec.Strategy = CompressionStrategy.Default
package

The compression strategy to use.

This is only effective in compression. The theory offered by ZLIB is that different strategies could potentially produce significant differences in compression behavior for different data sets. Unfortunately I don't have any good recommendations for how to set it differently. When I tested changing the strategy I got minimally different compression performance. It's best to leave this property alone if you don't have a good feel for it. Or, you may want to produce a test harness that runs through the different strategy options and evaluates them on different file types. If you do that, let me know your results.

long Zlib.ZlibCodec.TotalBytesIn

Total number of bytes read so far, through all calls to Inflate()/Deflate().

long Zlib.ZlibCodec.TotalBytesOut

Total number of bytes written to the output so far, through all calls to Inflate()/Deflate().

int Zlib.ZlibCodec.WindowBits = ZlibConstants.WindowBitsDefault

The number of Window Bits to use.

This gauges the size of the sliding window, and hence the compression effectiveness as well as memory consumption. It's best to just leave this setting alone if you don't know what it is. The maximum value is 15 bits, which implies a 32k window.

Property Documentation

int Zlib.ZlibCodec.Adler32
get

The Adler32 checksum on the data transferred through the codec so far. You probably don't need to look at this.