---
product: Chilkat
product_version: 11.7.0
language: wc
language_label: Unicode C
class: Bz2
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/wc_CkBz2WRef.html
---
# Chilkat Bz2 — Unicode C — v11.7.0

> Chilkat 11.7.0 · language=wc · class=Bz2
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Bz2.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/guide.md`.

## Purpose

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

For an extended overview, see [Bz2 Class Overview](https://www.chilkatsoft.com/bz2_class_overview.asp)

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkBz2W instance = CkBz2W_Create();
// ...
CkBz2W_Dispose(instance);
```

`HCkBz2W CkBz2W_Create(void);`

Creates an instance of the HCkBz2W object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkBz2W_Dispose(HCkBz2W handle);`

Objects created by calling CkBz2W_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkBz2W_Dispose.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Unicode C.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `void CkBz2W_getDebugLogFilePath(HCkBz2W cHandle, HCkString retval); void CkBz2W_putDebugLogFilePath(HCkBz2W cHandle, const wchar_t *newVal); const wchar_t *CkBz2W_debugLogFilePath(HCkBz2W cHandle);` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `void CkBz2W_getLastErrorHtml(HCkBz2W cHandle, HCkString retval); const wchar_t *CkBz2W_lastErrorHtml(HCkBz2W cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkBz2W_getLastErrorText(HCkBz2W cHandle, HCkString retval); const wchar_t *CkBz2W_lastErrorText(HCkBz2W cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkBz2W_getLastErrorXml(HCkBz2W cHandle, HCkString retval); const wchar_t *CkBz2W_lastErrorXml(HCkBz2W cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkBz2W_getLastMethodSuccess(HCkBz2W cHandle); void CkBz2W_putLastMethodSuccess(HCkBz2W cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkBz2W_getVerboseLogging(HCkBz2W cHandle); void CkBz2W_putVerboseLogging(HCkBz2W cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkBz2W_getVersion(HCkBz2W cHandle, HCkString retval); const wchar_t *CkBz2W_version(HCkBz2W cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `AbortCurrent` | property, read/write | `BOOL CkBz2W_getAbortCurrent(HCkBz2W cHandle); void CkBz2W_putAbortCurrent(HCkBz2W cHandle, BOOL newVal);` |
| `HeartbeatMs` | property, read/write | `int CkBz2W_getHeartbeatMs(HCkBz2W cHandle); void CkBz2W_putHeartbeatMs(HCkBz2W cHandle, int newVal);` |
| `CompressBd` | method | `BOOL CkBz2W_CompressBd(HCkBz2W cHandle, HCkBinDataW bd);` |
| `CompressFile` | method | `BOOL CkBz2W_CompressFile(HCkBz2W cHandle, const wchar_t *inFilename, const wchar_t *toPath);` |
| `LoadTaskCaller` | method | `BOOL CkBz2W_LoadTaskCaller(HCkBz2W cHandle, HCkTaskW task);` |
| `UncompressBd` | method | `BOOL CkBz2W_UncompressBd(HCkBz2W cHandle, HCkBinDataW bd);` |
| `UncompressFile` | method | `BOOL CkBz2W_UncompressFile(HCkBz2W cHandle, const wchar_t *inFilename, const wchar_t *toPath);` |

Deprecated members are listed at the end of this file with their replacements; do not use them in new code.

## Properties

### Bz2.AbortCurrent

`Chilkat 11.7.0 · wc · Bz2 · AbortCurrent · property · read/write · since 9.5.0.58`

```c
BOOL CkBz2W_getAbortCurrent(HCkBz2W cHandle);
void CkBz2W_putAbortCurrent(HCkBz2W cHandle, BOOL newVal);
```

Set this property to `TRUE` to request cancellation of the compression or decompression operation currently executing on this object. Long-running operations check the request periodically; an operation that finishes quickly may complete before the request is observed.

A synchronous call can be cancelled by setting this property from another thread. After cancellation is processed, Chilkat resets the property to `FALSE`. If no operation is running, a previously set value is cleared when the next method begins.

**Cancellation is cooperative:** Setting this property requests an abort; it does not guarantee immediate termination. Check the method's return value and `LastErrorText` to determine the final outcome.

### Bz2.HeartbeatMs

`Chilkat 11.7.0 · wc · Bz2 · HeartbeatMs · property · read/write`

```c
int CkBz2W_getHeartbeatMs(HCkBz2W cHandle);
void CkBz2W_putHeartbeatMs(HCkBz2W cHandle, int newVal);
```

**Full documentation for this property (same in every language):** [Event Callback Examples](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/event_callback_examples.md)

Specifies the interval, in milliseconds, between `AbortCheck` event callbacks during supported long-running compression and decompression operations. The default is `0`, which disables `AbortCheck` callbacks.

Set a positive value, such as `200`, when the application needs periodic opportunities to request cancellation. The interval is approximate; callbacks occur only while an operation is at a point where progress events can be delivered.

**Cancellation workflow:** In an `AbortCheck` handler, set the callback's abort value to request termination. A synchronous method may also be cancelled from another thread by setting `AbortCurrent` to `TRUE`.

## Methods

### Bz2.CompressBd

`Chilkat 11.7.0 · wc · Bz2 · CompressBd · method · since 11.0.0`

```c
BOOL CkBz2W_CompressBd(HCkBz2W cHandle, HCkBinDataW bd);
```

Compresses the current contents of `bd` in place. On success, the `BinData` no longer contains the original bytes; it contains the complete standard BZip2 stream that may be saved with a `.bz2` extension.

**In-place transformation:** Preserve a copy of the original data if it is still needed after this call. A BZip2 stream contains a stream header, one or more compressed blocks with integrity checks, and an end-of-stream marker. It does not contain archive filenames or directory entries.

Returns TRUE for success, FALSE for failure.

Async variant: `CompressBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Bz2.CompressFile

`Chilkat 11.7.0 · wc · Bz2 · CompressFile · method`

```c
BOOL CkBz2W_CompressFile(HCkBz2W cHandle, const wchar_t *inFilename, const wchar_t *toPath);
```

Reads the file at `inFilename` and writes its compressed bytes as a standard BZip2 stream to the file at `toPath`. The output is conventionally given a `.bz2` extension.

Both arguments must identify files, not directories. They may be absolute or relative paths, for example `data/report.txt` and `data/report.txt.bz2`.

**BZip2 is a compressor, not an archive format:** A `.bz2` file represents one compressed byte stream. It does not store the original filename, directory path, timestamps, permissions, or multiple archive entries. Formats such as `.tar.bz2` first combine files in a TAR archive and then compress that TAR stream with BZip2.

Returns TRUE for success, FALSE for failure.

Async variant: `CompressFileAsync` — same arguments, returns a `Task` (see Async variants below).

### Bz2.LoadTaskCaller

`Chilkat 11.7.0 · wc · Bz2 · LoadTaskCaller · method · since 9.5.0.80`

```c
BOOL CkBz2W_LoadTaskCaller(HCkBz2W cHandle, HCkTaskW task);
```

Loads this `Bz2` object with the caller state associated with the asynchronous operation represented by `task`.

**Advanced async infrastructure:** This method is used to recover the original caller object associated with a completed task. It is not normally needed by application code. Pass a `Task` created by a compatible `Bz2` asynchronous method; an unrelated task cannot be loaded.

Returns TRUE for success, FALSE for failure.

### Bz2.UncompressBd

`Chilkat 11.7.0 · wc · Bz2 · UncompressBd · method · since 11.0.0`

```c
BOOL CkBz2W_UncompressBd(HCkBz2W cHandle, HCkBinDataW bd);
```

Decompresses the BZip2 stream currently contained in `bd` in place. On success, the `BinData` is replaced with the original uncompressed bytes.

**Input requirement:** `bd` must contain a complete, valid BZip2 stream, such as the bytes of a `.bz2` file or the output of `CompressBd`. This method operates on binary data and does not perform character-set conversion.

Returns TRUE for success, FALSE for failure.

Async variant: `UncompressBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Bz2.UncompressFile

`Chilkat 11.7.0 · wc · Bz2 · UncompressFile · method`

```c
BOOL CkBz2W_UncompressFile(HCkBz2W cHandle, const wchar_t *inFilename, const wchar_t *toPath);
```

Reads the BZip2 stream from the file at `inFilename`, decompresses it, and writes the original uncompressed bytes to the file at `toPath`.

Both arguments must identify files, not directories. Chilkat does not derive the destination name from the `.bz2` filename because the BZip2 stream does not contain the original filename.

**Terminology:** This method decompresses BZip2 data; it does not “unzip” a ZIP archive. A `.bz2` file normally contains a single compressed byte stream rather than a collection of named files.

Returns TRUE for success, FALSE for failure.

Async variant: `UncompressFileAsync` — same arguments, returns a `Task` (see Async variants below).

## Events and callbacks

This binding delivers progress information through callbacks (AbortCheck, PercentDone, ProgressInfo, TaskCompleted) rather than events. See `guide.md` for how to attach them in Unicode C.

## Async variants

Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on.

```c
HCkTaskW CkBz2W_CompressBdAsync(HCkBz2W cHandle, HCkBinDataW bd);
HCkTaskW CkBz2W_CompressFileAsync(HCkBz2W cHandle, const wchar_t *inFilename, const wchar_t *toPath);
HCkTaskW CkBz2W_UncompressBdAsync(HCkBz2W cHandle, HCkBinDataW bd);
HCkTaskW CkBz2W_UncompressFileAsync(HCkBz2W cHandle, const wchar_t *inFilename, const wchar_t *toPath);
```

## Deprecated members — do not use in new code

| Member | Kind | Deprecated in | Use instead |
|---|---|---|---|
| `CompressFileToMem` | method | before 11.6.1 | — |
| `CompressMemory` | method | before 11.6.1 | — |
| `CompressMemToFile` | method | before 11.6.1 | — |
| `UncompressFileToMem` | method | before 11.6.1 | — |
| `UncompressMemory` | method | before 11.6.1 | — |
| `UncompressMemToFile` | method | before 11.6.1 | — |

## Related classes

[`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/BinData.md), [`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/wc/classes/Task.md)

