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

> Chilkat 11.7.0 · language=wc · 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/wc/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
HCkTaskChainW instance = CkTaskChainW_Create();
// ...
CkTaskChainW_Dispose(instance);
```

`HCkTaskChainW CkTaskChainW_Create(void);`

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

`void CkTaskChainW_Dispose(HCkTaskChainW handle);`

Objects created by calling CkTaskChainW_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 CkTaskChainW_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 CkTaskChainW_getDebugLogFilePath(HCkTaskChainW cHandle, HCkString retval); void CkTaskChainW_putDebugLogFilePath(HCkTaskChainW cHandle, const wchar_t *newVal); const wchar_t *CkTaskChainW_debugLogFilePath(HCkTaskChainW 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 CkTaskChainW_getLastErrorHtml(HCkTaskChainW cHandle, HCkString retval); const wchar_t *CkTaskChainW_lastErrorHtml(HCkTaskChainW cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkTaskChainW_getLastErrorText(HCkTaskChainW cHandle, HCkString retval); const wchar_t *CkTaskChainW_lastErrorText(HCkTaskChainW cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkTaskChainW_getLastErrorXml(HCkTaskChainW cHandle, HCkString retval); const wchar_t *CkTaskChainW_lastErrorXml(HCkTaskChainW cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkTaskChainW_getLastMethodSuccess(HCkTaskChainW cHandle); void CkTaskChainW_putLastMethodSuccess(HCkTaskChainW cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkTaskChainW_getVerboseLogging(HCkTaskChainW cHandle); void CkTaskChainW_putVerboseLogging(HCkTaskChainW 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 CkTaskChainW_getVersion(HCkTaskChainW cHandle, HCkString retval); const wchar_t *CkTaskChainW_version(HCkTaskChainW cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `Finished` | property, read-only | `BOOL CkTaskChainW_getFinished(HCkTaskChainW cHandle);` |
| `HeartbeatMs` | property, read/write | `int CkTaskChainW_getHeartbeatMs(HCkTaskChainW cHandle); void CkTaskChainW_putHeartbeatMs(HCkTaskChainW cHandle, int newVal);` |
| `Inert` | property, read-only | `BOOL CkTaskChainW_getInert(HCkTaskChainW cHandle);` |
| `Live` | property, read-only | `BOOL CkTaskChainW_getLive(HCkTaskChainW cHandle);` |
| `NumTasks` | property, read-only | `int CkTaskChainW_getNumTasks(HCkTaskChainW cHandle);` |
| `Status` | property, read-only | `void CkTaskChainW_getStatus(HCkTaskChainW cHandle, HCkString retval); const wchar_t *CkTaskChainW_status(HCkTaskChainW cHandle);` |
| `StatusInt` | property, read-only | `int CkTaskChainW_getStatusInt(HCkTaskChainW cHandle);` |
| `StopOnFailedTask` | property, read/write | `BOOL CkTaskChainW_getStopOnFailedTask(HCkTaskChainW cHandle); void CkTaskChainW_putStopOnFailedTask(HCkTaskChainW cHandle, BOOL newVal);` |
| `Append` | method | `BOOL CkTaskChainW_Append(HCkTaskChainW cHandle, HCkTaskW task);` |
| `Cancel` | method | `BOOL CkTaskChainW_Cancel(HCkTaskChainW cHandle);` |
| `GetTask` | method | `HCkTaskW CkTaskChainW_GetTask(HCkTaskChainW cHandle, int index);` |
| `Run` | method | `BOOL CkTaskChainW_Run(HCkTaskChainW cHandle);` |
| `RunSynchronously` | method | `BOOL CkTaskChainW_RunSynchronously(HCkTaskChainW cHandle);` |
| `SleepMs` | method | `void CkTaskChainW_SleepMs(HCkTaskChainW cHandle, int numMs);` |
| `Wait` | method | `BOOL CkTaskChainW_Wait(HCkTaskChainW cHandle, int maxWaitMs);` |

## Properties

### TaskChain.Finished

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

```c
BOOL CkTaskChainW_getFinished(HCkTaskChainW 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 · wc · TaskChain · HeartbeatMs · property · read/write · since 9.5.0.52`

```c
int CkTaskChainW_getHeartbeatMs(HCkTaskChainW cHandle);
void CkTaskChainW_putHeartbeatMs(HCkTaskChainW 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 · wc · TaskChain · Inert · property · read-only · since 9.5.0.52`

```c
BOOL CkTaskChainW_getInert(HCkTaskChainW 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 · wc · TaskChain · Live · property · read-only · since 9.5.0.52`

```c
BOOL CkTaskChainW_getLive(HCkTaskChainW 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 · wc · TaskChain · NumTasks · property · read-only · since 9.5.0.52`

```c
int CkTaskChainW_getNumTasks(HCkTaskChainW cHandle);
```

The number of tasks contained within the task chain.

### TaskChain.Status

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

```c
void CkTaskChainW_getStatus(HCkTaskChainW cHandle, HCkString retval);
const wchar_t *CkTaskChainW_status(HCkTaskChainW 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 · wc · TaskChain · StatusInt · property · read-only · since 9.5.0.52`

```c
int CkTaskChainW_getStatusInt(HCkTaskChainW 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 · wc · TaskChain · StopOnFailedTask · property · read/write · since 9.5.0.52`

```c
BOOL CkTaskChainW_getStopOnFailedTask(HCkTaskChainW cHandle);
void CkTaskChainW_putStopOnFailedTask(HCkTaskChainW 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 · wc · TaskChain · Append · method · since 9.5.0.52`

```c
BOOL CkTaskChainW_Append(HCkTaskChainW cHandle, HCkTaskW 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 · wc · TaskChain · Cancel · method · since 9.5.0.52`

```c
BOOL CkTaskChainW_Cancel(HCkTaskChainW cHandle);
```

Cancels execution of the asynchronous task chain.

Returns TRUE for success, FALSE for failure.

### TaskChain.GetTask

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

```c
HCkTaskW CkTaskChainW_GetTask(HCkTaskChainW 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 · wc · TaskChain · Run · method · since 9.5.0.52`

```c
BOOL CkTaskChainW_Run(HCkTaskChainW 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 · wc · TaskChain · RunSynchronously · method · since 9.5.0.52`

```c
BOOL CkTaskChainW_RunSynchronously(HCkTaskChainW 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 · wc · TaskChain · SleepMs · method · since 9.5.0.52`

```c
void CkTaskChainW_SleepMs(HCkTaskChainW cHandle, int numMs);
```

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

### TaskChain.Wait

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

```c
BOOL CkTaskChainW_Wait(HCkTaskChainW 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 Unicode C.

## Related classes

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