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

> Chilkat 11.7.0 · language=c · 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/c/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
HCkBz2 instance = CkBz2_Create();
// ...
CkBz2_Dispose(instance);
```

`HCkBz2 CkBz2_Create(void);`

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

`void CkBz2_Dispose(HCkBz2 handle);`

Objects created by calling CkBz2_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 CkBz2_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 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 CkBz2_getDebugLogFilePath(HCkBz2 cHandle, HCkString retval); void CkBz2_putDebugLogFilePath(HCkBz2 cHandle, const char *newVal); const char *CkBz2_debugLogFilePath(HCkBz2 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 CkBz2_getLastErrorHtml(HCkBz2 cHandle, HCkString retval); const char *CkBz2_lastErrorHtml(HCkBz2 cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkBz2_getLastErrorText(HCkBz2 cHandle, HCkString retval); const char *CkBz2_lastErrorText(HCkBz2 cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkBz2_getLastErrorXml(HCkBz2 cHandle, HCkString retval); const char *CkBz2_lastErrorXml(HCkBz2 cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkBz2_getLastMethodSuccess(HCkBz2 cHandle); void CkBz2_putLastMethodSuccess(HCkBz2 cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `Utf8` | `BOOL CkBz2_getUtf8(HCkBz2 cHandle); void CkBz2_putUtf8(HCkBz2 cHandle, BOOL newVal);` | read/write | When set to `TRUE`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `BOOL CkBz2_getVerboseLogging(HCkBz2 cHandle); void CkBz2_putVerboseLogging(HCkBz2 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 CkBz2_getVersion(HCkBz2 cHandle, HCkString retval); const char *CkBz2_version(HCkBz2 cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `AbortCurrent` | property, read/write | `BOOL CkBz2_getAbortCurrent(HCkBz2 cHandle); void CkBz2_putAbortCurrent(HCkBz2 cHandle, BOOL newVal);` |
| `HeartbeatMs` | property, read/write | `int CkBz2_getHeartbeatMs(HCkBz2 cHandle); void CkBz2_putHeartbeatMs(HCkBz2 cHandle, int newVal);` |
| `CompressBd` | method | `BOOL CkBz2_CompressBd(HCkBz2 cHandle, HCkBinData bd);` |
| `CompressFile` | method | `BOOL CkBz2_CompressFile(HCkBz2 cHandle, const char *inFilename, const char *toPath);` |
| `LoadTaskCaller` | method | `BOOL CkBz2_LoadTaskCaller(HCkBz2 cHandle, HCkTask task);` |
| `UncompressBd` | method | `BOOL CkBz2_UncompressBd(HCkBz2 cHandle, HCkBinData bd);` |
| `UncompressFile` | method | `BOOL CkBz2_UncompressFile(HCkBz2 cHandle, const char *inFilename, const char *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 · c · Bz2 · AbortCurrent · property · read/write · since 9.5.0.58`

```c
BOOL CkBz2_getAbortCurrent(HCkBz2 cHandle);
void CkBz2_putAbortCurrent(HCkBz2 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 · c · Bz2 · HeartbeatMs · property · read/write`

```c
int CkBz2_getHeartbeatMs(HCkBz2 cHandle);
void CkBz2_putHeartbeatMs(HCkBz2 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 · c · Bz2 · CompressBd · method · since 11.0.0`

```c
BOOL CkBz2_CompressBd(HCkBz2 cHandle, HCkBinData 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 · c · Bz2 · CompressFile · method`

```c
BOOL CkBz2_CompressFile(HCkBz2 cHandle, const char *inFilename, const char *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 · c · Bz2 · LoadTaskCaller · method · since 9.5.0.80`

```c
BOOL CkBz2_LoadTaskCaller(HCkBz2 cHandle, HCkTask 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 · c · Bz2 · UncompressBd · method · since 11.0.0`

```c
BOOL CkBz2_UncompressBd(HCkBz2 cHandle, HCkBinData 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 · c · Bz2 · UncompressFile · method`

```c
BOOL CkBz2_UncompressFile(HCkBz2 cHandle, const char *inFilename, const char *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 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
HCkTask CkBz2_CompressBdAsync(HCkBz2 cHandle, HCkBinData bd);
HCkTask CkBz2_CompressFileAsync(HCkBz2 cHandle, const char *inFilename, const char *toPath);
HCkTask CkBz2_UncompressBdAsync(HCkBz2 cHandle, HCkBinData bd);
HCkTask CkBz2_UncompressFileAsync(HCkBz2 cHandle, const char *inFilename, const char *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/c/classes/BinData.md), [`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/Task.md)