Chilkat.Bz2 Class Overview

Chilkat.Bz2 provides BZip2 compression and decompression for files, memory buffers, and BinData. It can create standard .bz2 file images, decompress .bz2 content back to its original bytes, and support abortable long-running operations.

What the Class Is Used For

Use Chilkat.Bz2 when an application needs to compress data into BZip2 .bz2 format or decompress existing .bz2 content. The class supports common workflows such as file-to-file compression, file-to-memory compression, memory-to-file compression, memory-to-memory compression, and in-place BinData conversion.

Compress Files Create a .bz2 file from an input file using CompressFile.
Compress Memory Compress byte arrays or BinData into .bz2 format.
Decompress Files Restore original content from a .bz2 file using file, memory, or BinData methods.
Abort Long Operations Use AbortCurrent and HeartbeatMs for cancellable longer operations.

Important Format Note

.bz2 file format: The compressed output produced by this class is the binary content of a .bz2 file. A .bz2 file is slightly different from simple BZIP2 compressed data because it contains a header, compressed blocks, and an end-of-stream trailer.

Typical Workflow: Compress a File

  1. Create a Bz2 object.
  2. Optionally set HeartbeatMs if the operation may be long-running and the application needs abort callbacks.
  3. Call CompressFile with the input file path and the destination .bz2 file path.
  4. Check the boolean return value.
  5. If the method returns false, inspect LastErrorText.
Path note: Both inFilename and toPath should be full or relative file paths, not just directory paths.

Typical Workflow: Decompress a File

  1. Create a Bz2 object.
  2. Provide the path to the existing .bz2 file.
  3. Call UncompressFile with the input .bz2 path and the destination output file path.
  4. Check the boolean return value.
  5. If decompression fails, inspect LastErrorText.

Core Concepts

Concept Meaning Important Members
File Compression Compresses an input file and writes a .bz2 file. CompressFile
Memory Compression Compresses bytes in memory and returns or writes a .bz2 file image. CompressMemory, CompressFileToMem, CompressMemToFile
BinData Compression Compresses the contents of a BinData object in-place. CompressBd
File Decompression Decompresses a .bz2 file and writes the original content to a file. UncompressFile
Memory Decompression Decompresses a .bz2 file image held in memory. UncompressMemory, UncompressFileToMem, UncompressMemToFile
Abort Support Allows long-running operations to be cancelled. AbortCurrent, HeartbeatMs

Properties

Property Purpose Guidance
AbortCurrent Causes the currently running method to abort when set to true. Useful for longer file operations. If no method is running, it is automatically reset when the next method is called. After an abort occurs, the property is reset to false.
HeartbeatMs Interval in milliseconds between AbortCheck event callbacks. Default is 0, meaning no AbortCheck callbacks are triggered. Set to a positive value when an application needs periodic abort checks.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Compression Methods

Method Input Output Use When
CompressFile File path .bz2 file path Compress a file directly to a destination file.
CompressFileToMem File path Byte array containing a .bz2 file image Compress a file and keep the compressed result in memory.
CompressMemory Byte array Byte array containing a .bz2 file image Compress in-memory data to in-memory compressed data.
CompressMemToFile Byte array .bz2 file path Compress in-memory data and write it as a .bz2 file.
CompressBd BinData Same BinData object, replaced with .bz2 content Compress a BinData object in-place.

Decompression Methods

Method Input Output Use When
UncompressFile .bz2 file path Destination file path Decompress a .bz2 file directly to a file.
UncompressFileToMem .bz2 file path Byte array containing original uncompressed data Decompress a file and keep the restored data in memory.
UncompressMemory Byte array containing a .bz2 file image Byte array containing original uncompressed data Decompress in-memory .bz2 content to memory.
UncompressMemToFile Byte array containing a .bz2 file image Destination file path Decompress in-memory .bz2 content to a file.
UncompressBd BinData containing .bz2 bytes Same BinData object, replaced with original uncompressed content Decompress a BinData object in-place.

Input and Output Patterns

Workflow Compression Method Decompression Method
File to file CompressFile UncompressFile
File to memory CompressFileToMem UncompressFileToMem
Memory to memory CompressMemory UncompressMemory
Memory to file CompressMemToFile UncompressMemToFile
BinData in-place CompressBd UncompressBd

Abort and Heartbeat Behavior

Member Behavior Use When
AbortCurrent When set to true, causes the currently running operation to abort. Both synchronous and asynchronous method calls can be aborted. Use from another thread or event callback when a long-running compression or decompression should stop.
HeartbeatMs Sets the interval between AbortCheck event callbacks. Use when an application wants periodic opportunities to cancel a long-running operation.
Quick methods: Methods that always finish quickly are not affected by AbortCurrent.

Method Summary by Category

Category Methods / Properties Purpose
Compress CompressFile, CompressFileToMem, CompressMemory, CompressMemToFile, CompressBd Create .bz2 content from files, byte arrays, or BinData.
Decompress UncompressFile, UncompressFileToMem, UncompressMemory, UncompressMemToFile, UncompressBd Restore original content from .bz2 files or .bz2 file images.
Abort control AbortCurrent, HeartbeatMs Provide cancellation support for longer-running operations.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
File compression fails CompressFile, LastErrorText Confirm both arguments are file paths, not directory paths, and inspect diagnostic text for file access or compression details.
File decompression fails UncompressFile, LastErrorText Confirm the input contains valid .bz2 content and that the destination file path can be written.
Memory decompression fails UncompressMemory Confirm the input byte array is an in-memory image of a .bz2 file.
BinData result is unexpected CompressBd, UncompressBd These methods modify the supplied BinData object in-place.
Abort is not occurring AbortCurrent, HeartbeatMs Confirm the operation is long-running enough to be abortable and that heartbeat callbacks are configured when needed.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected compression, decompression, async, or abort behavior.

Common Pitfalls

Pitfall Better Approach
Passing a directory path where a file path is required. For methods such as CompressFile, provide full or relative file paths for both input and output.
Assuming CompressMemory returns raw compressed blocks only. The returned bytes are an in-memory image of a .bz2 file.
Passing ordinary uncompressed bytes to UncompressMemory. Pass bytes that contain a .bz2 file image.
Expecting CompressBd or UncompressBd to create a new object. These methods replace the contents of the supplied BinData object.
Expecting very quick operations to be affected by AbortCurrent. AbortCurrent applies to operations that can run long enough to be aborted.
Ignoring diagnostics after failed compression or decompression. Check LastErrorText for details.

Best Practices

Recommendation Reason
Choose the method that matches the source and destination. The class provides clear file, memory, and BinData variants for both compression and decompression.
Use CompressFile and UncompressFile for straightforward file workflows. They avoid manually loading and saving file content.
Use memory methods when the compressed or uncompressed bytes are already in memory. This avoids unnecessary temporary files.
Use BinData methods for in-place buffer workflows. CompressBd and UncompressBd modify the existing buffer.
Set HeartbeatMs for long-running operations that may need cancellation. It enables periodic abort checks.
Check LastErrorText after failures. It provides useful diagnostic detail for failed or unexpected compression and decompression behavior.

Summary

Chilkat.Bz2 is a BZip2 utility class for creating and reading .bz2 content. It supports compression and decompression across file, memory, and BinData workflows, and includes abort support for longer-running operations.

The most important practical guidance is to choose the method that matches the source and destination, remember that memory-based compressed data represents a .bz2 file image, provide file paths rather than directory paths for file methods, understand that BinData methods modify the object in-place, and inspect LastErrorText whenever compression or decompression fails.