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

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

## Purpose

**Run multiple asynchronous Chilkat tasks in a defined sequence.**

`Chilkat.TaskChain` manages a sequence of `Chilkat.Task` objects and runs them one after another. It is useful when multiple asynchronous Chilkat operations must execute in a predictable order while still allowing the entire chain to be started, monitored, waited on, canceled, or run synchronously. A task chain can stop when a task fails, or continue depending on the configured behavior.

**Sequential async workflow**

Append multiple `Task` objects and run them in order when one operation must finish before the next begins.

**Chain-level execution**

Start the entire chain, run it synchronously, wait for completion, or cancel the chain as a single coordinated operation.

**Monitor progress and status**

Inspect whether the chain is live, finished, inert, canceled, failed, or still running.

**Access individual tasks**

Retrieve tasks by index after execution to inspect each task's status, success flag, error text, and result.

**Stop-on-failure control**

Use `StopOnFailedTask` to control whether the chain stops at the first failed task or continues to later tasks.

**Diagnostics**

Use task and chain status information together with `LastErrorText` and each task's result details to troubleshoot ordered async workflows.

**Common pattern:** Create the individual async tasks, append them to a `TaskChain` in the required order, set `StopOnFailedTask` as appropriate, run the chain, wait for completion, then inspect each task's success status and result. Use `TaskChain` when operations must run sequentially; use individual `Task` objects when each async operation can be managed on its own.

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

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkTaskChain instance = CkTaskChain_Create();
// ...
CkTaskChain_Dispose(instance);
```

`HCkTaskChain CkTaskChain_Create(void);`

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

`void CkTaskChain_Dispose(HCkTaskChain handle);`

Objects created by calling CkTaskChain_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 CkTaskChain_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 CkTaskChain_getDebugLogFilePath(HCkTaskChain cHandle, HCkString retval); void CkTaskChain_putDebugLogFilePath(HCkTaskChain cHandle, const char *newVal); const char *CkTaskChain_debugLogFilePath(HCkTaskChain 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 CkTaskChain_getLastErrorHtml(HCkTaskChain cHandle, HCkString retval); const char *CkTaskChain_lastErrorHtml(HCkTaskChain cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkTaskChain_getLastErrorText(HCkTaskChain cHandle, HCkString retval); const char *CkTaskChain_lastErrorText(HCkTaskChain cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkTaskChain_getLastErrorXml(HCkTaskChain cHandle, HCkString retval); const char *CkTaskChain_lastErrorXml(HCkTaskChain cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkTaskChain_getLastMethodSuccess(HCkTaskChain cHandle); void CkTaskChain_putLastMethodSuccess(HCkTaskChain cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `Utf8` | `BOOL CkTaskChain_getUtf8(HCkTaskChain cHandle); void CkTaskChain_putUtf8(HCkTaskChain cHandle, BOOL newVal);` | read/write | When set to `TRUE`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `BOOL CkTaskChain_getVerboseLogging(HCkTaskChain cHandle); void CkTaskChain_putVerboseLogging(HCkTaskChain 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 CkTaskChain_getVersion(HCkTaskChain cHandle, HCkString retval); const char *CkTaskChain_version(HCkTaskChain cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `Finished` | property, read-only | `BOOL CkTaskChain_getFinished(HCkTaskChain cHandle);` |
| `HeartbeatMs` | property, read/write | `int CkTaskChain_getHeartbeatMs(HCkTaskChain cHandle); void CkTaskChain_putHeartbeatMs(HCkTaskChain cHandle, int newVal);` |
| `Inert` | property, read-only | `BOOL CkTaskChain_getInert(HCkTaskChain cHandle);` |
| `Live` | property, read-only | `BOOL CkTaskChain_getLive(HCkTaskChain cHandle);` |
| `NumTasks` | property, read-only | `int CkTaskChain_getNumTasks(HCkTaskChain cHandle);` |
| `Status` | property, read-only | `void CkTaskChain_getStatus(HCkTaskChain cHandle, HCkString retval); const char *CkTaskChain_status(HCkTaskChain cHandle);` |
| `StatusInt` | property, read-only | `int CkTaskChain_getStatusInt(HCkTaskChain cHandle);` |
| `StopOnFailedTask` | property, read/write | `BOOL CkTaskChain_getStopOnFailedTask(HCkTaskChain cHandle); void CkTaskChain_putStopOnFailedTask(HCkTaskChain cHandle, BOOL newVal);` |
| `Append` | method | `BOOL CkTaskChain_Append(HCkTaskChain cHandle, HCkTask task);` |
| `Cancel` | method | `BOOL CkTaskChain_Cancel(HCkTaskChain cHandle);` |
| `GetTask` | method | `HCkTask CkTaskChain_GetTask(HCkTaskChain cHandle, int index);` |
| `Run` | method | `BOOL CkTaskChain_Run(HCkTaskChain cHandle);` |
| `RunSynchronously` | method | `BOOL CkTaskChain_RunSynchronously(HCkTaskChain cHandle);` |
| `SleepMs` | method | `void CkTaskChain_SleepMs(HCkTaskChain cHandle, int numMs);` |
| `Wait` | method | `BOOL CkTaskChain_Wait(HCkTaskChain cHandle, int maxWaitMs);` |

## Properties

### TaskChain.Finished

`Chilkat 11.7.0 · c · TaskChain · Finished · property · read-only · since 9.5.0.52`

```c
BOOL CkTaskChain_getFinished(HCkTaskChain cHandle);
```

`TRUE` if the task status is `canceled`, `aborted`, or `completed`. A task chain can only reach the `canceled` status if it was activated via the Run method, made it onto the internal thread pool thread's queue, was waiting for a pool thread to become available, and was then canceled prior to the task actually starting.

### TaskChain.HeartbeatMs

`Chilkat 11.7.0 · c · TaskChain · HeartbeatMs · property · read/write · since 9.5.0.52`

```c
int CkTaskChain_getHeartbeatMs(HCkTaskChain cHandle);
void CkTaskChain_putHeartbeatMs(HCkTaskChain cHandle, int newVal);
```

The number of milliseconds between each AbortCheck event callback. The AbortCheck callback allows an application to abort the Wait method. If HeartbeatMs is 0 (the default), no AbortCheck event callbacks will fire. **Note:** An asynchronous task chain running in a background thread (in one of the thread pool threads) does not fire events. The task chain's event callbacks pertain only to the Wait method.

### TaskChain.Inert

`Chilkat 11.7.0 · c · TaskChain · Inert · property · read-only · since 9.5.0.52`

```c
BOOL CkTaskChain_getInert(HCkTaskChain cHandle);
```

`TRUE` if the task status is `empty` or `loaded`. When a task chain is inert, it has been loaded but is not scheduled to run yet.

### TaskChain.Live

`Chilkat 11.7.0 · c · TaskChain · Live · property · read-only · since 9.5.0.52`

```c
BOOL CkTaskChain_getLive(HCkTaskChain cHandle);
```

`TRUE` if the task status is `queued` or `running`. When a task chain is live, it is either already running, or is on the thread pool thread's queue waiting for a thread to become available.

### TaskChain.NumTasks

`Chilkat 11.7.0 · c · TaskChain · NumTasks · property · read-only · since 9.5.0.52`

```c
int CkTaskChain_getNumTasks(HCkTaskChain cHandle);
```

The number of tasks contained within the task chain.

### TaskChain.Status

`Chilkat 11.7.0 · c · TaskChain · Status · property · read-only · since 9.5.0.52`

```c
void CkTaskChain_getStatus(HCkTaskChain cHandle, HCkString retval);
const char *CkTaskChain_status(HCkTaskChain cHandle);
```

The current status of the task chain. Possible values are:

- `empty` -- No tasks have yet been appended to the task chain.
- `loaded` -- The task chain has been loaded (appended) with one or more task objects.
- `queued` -- The task chain is in the thread pool's queue of tasks awaiting to be run.
- `running` -- The task chain is currently running.
- `canceled` -- The task chain was canceled before it entered the `running` state.
- `aborted` -- The task chain was canceled while it was in the running state.
- `completed` -- The task chain completed.

### TaskChain.StatusInt

`Chilkat 11.7.0 · c · TaskChain · StatusInt · property · read-only · since 9.5.0.52`

```c
int CkTaskChain_getStatusInt(HCkTaskChain cHandle);
```

The current status of the task as an integer value. Possible values are:

- **1** -- `empty` -- No tasks have yet been appended to the task chain.
- **2** -- `loaded` -- The task chain has been loaded (appended) with one or more task objects.
- **3** -- `queued` -- The task chain is in the thread pool's queue of tasks awaiting to be run.
- **4** -- `running` -- The task chain is currently running.
- **5** -- `canceled` -- The task chain was canceled before it entered the `running` state.
- **6** -- `aborted` -- The task chain was canceled while it was in the running state.
- **7** -- `completed` -- The task chain completed.

### TaskChain.StopOnFailedTask

`Chilkat 11.7.0 · c · TaskChain · StopOnFailedTask · property · read/write · since 9.5.0.52`

```c
BOOL CkTaskChain_getStopOnFailedTask(HCkTaskChain cHandle);
void CkTaskChain_putStopOnFailedTask(HCkTaskChain cHandle, BOOL newVal);
```

If `TRUE` then stops execution of the task chain if any individual task fails. Task failure is defined by the standard LastMethodSuccess property. If `FALSE`, then all of the tasks in the chain will be run even if some fail. The default value of this property is `TRUE`.

## Methods

### TaskChain.Append

`Chilkat 11.7.0 · c · TaskChain · Append · method · since 9.5.0.52`

```c
BOOL CkTaskChain_Append(HCkTaskChain cHandle, HCkTask task);
```

Appends a task to the task chain. Can fail if the task is already part of another chain. (A task can only be part of a single chain.)

Returns TRUE for success, FALSE for failure.

### TaskChain.Cancel

`Chilkat 11.7.0 · c · TaskChain · Cancel · method · since 9.5.0.52`

```c
BOOL CkTaskChain_Cancel(HCkTaskChain cHandle);
```

Cancels execution of the asynchronous task chain.

Returns TRUE for success, FALSE for failure.

### TaskChain.GetTask

`Chilkat 11.7.0 · c · TaskChain · GetTask · method · since 9.5.0.52`

```c
HCkTask CkTaskChain_GetTask(HCkTaskChain cHandle, int index);
```

Returns the Nth task in the chain. The 1st task is at index 0.

Returns `NULL` on failure

### TaskChain.Run

`Chilkat 11.7.0 · c · TaskChain · Run · method · since 9.5.0.52`

```c
BOOL CkTaskChain_Run(HCkTaskChain cHandle);
```

Queues the task chain to run on the internal Chilkat thread pool. Each task in the chain will run, one after the other.

Returns TRUE for success, FALSE for failure.

### TaskChain.RunSynchronously

`Chilkat 11.7.0 · c · TaskChain · RunSynchronously · method · since 9.5.0.52`

```c
BOOL CkTaskChain_RunSynchronously(HCkTaskChain cHandle);
```

Runs the task chain synchronously. Then this method returns after all the tasks in the chain have been run.

Returns TRUE for success, FALSE for failure.

### TaskChain.SleepMs

`Chilkat 11.7.0 · c · TaskChain · SleepMs · method · since 9.5.0.52`

```c
void CkTaskChain_SleepMs(HCkTaskChain cHandle, int numMs);
```

Convenience method to force the calling thread to sleep for a number of milliseconds.

### TaskChain.Wait

`Chilkat 11.7.0 · c · TaskChain · Wait · method · since 9.5.0.52`

```c
BOOL CkTaskChain_Wait(HCkTaskChain cHandle, int maxWaitMs);
```

Waits for the task chain to complete. Returns when all of the tasks in the chain have completed, or after `maxWaitMs` milliseconds have elapsed. (A `maxWaitMs` value of 0 is to wait indefinitely.) Returns (`FALSE`) if the task chain has not yet been started by calling the Run method, or if the `maxWaitMs` expired. If the task chain completed, was already completed, was canceled, or aborted, then this method returns `TRUE`.

Returns TRUE for success, FALSE for failure.

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

## Related classes

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