---
product: Chilkat
product_version: 11.7.0
language: wcpp
language_label: Unicode C++
class: DirTree
class_name: CkDirTreeW
license: free
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/wcppCkDirTreeWRef.html
---
# Chilkat DirTree — Unicode C++ — v11.7.0

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

## Purpose

**Iterate through files and subdirectories under a base directory.**

`Chilkat.DirTree` is a lightweight directory-tree iterator for traversing files and subdirectories under a selected base directory. It supports recursive and non-recursive traversal and exposes useful information about the current item, including absolute path, UNC path, relative path, file size, and whether the current item is a directory.

**Directory traversal**

Iterate through the contents of a base directory, either recursively or one level at a time.

**Current-item details**

Get the current item's full path, relative path, UNC path, size, and directory/file status.

**Recursive scanning**

Traverse entire directory trees when an application needs to process all nested files and folders.

**Non-recursive listing**

Limit iteration to the immediate contents of the base directory when deeper traversal is not needed.

**Path-friendly output**

Use absolute or relative paths depending on whether the application needs filesystem access or archive-style relative names.

**Error-aware iteration**

Use `DoneIterating` to distinguish normal completion from an error when an iteration method returns false.

**Common pattern:** Set the base directory and recursion behavior, begin iterating, process each current item using the path and metadata properties, then check `DoneIterating` when iteration stops to determine whether traversal completed normally or ended because of an error.

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

## Object creation, unlocking and error handling

**Object Creation**

```cpp
// Local variable on the stack
CkDirTreeW obj;

// Dynamically allocate/delete
CkDirTreeW *pObj = new CkDirTreeW();
// ...
delete pObj;
```

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

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## 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 get_DebugLogFilePath(CkString &str); const wchar_t *debugLogFilePath(void); void put_DebugLogFilePath(const wchar_t *str);` | 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 get_LastErrorHtml(CkString &str); const wchar_t *lastErrorHtml(void);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void get_LastErrorText(CkString &str); const wchar_t *lastErrorText(void);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void get_LastErrorXml(CkString &str); const wchar_t *lastErrorXml(void);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `bool get_LastMethodSuccess(void); void put_LastMethodSuccess(bool newVal);` | read/write | Indicates the success or failure of the most recent method call: `true` means success, `false` means failure. |
| `VerboseLogging` | `bool get_VerboseLogging(void); void put_VerboseLogging(bool newVal);` | read/write | If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void get_Version(CkString &str); const wchar_t *version(void);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `BaseDir` | property, read/write | `void get_BaseDir(CkString &str); const wchar_t *baseDir(void); void put_BaseDir(const wchar_t *str);` |
| `DoneIterating` | property, read-only | `bool get_DoneIterating(void);` |
| `FileSize32` | property, read-only | `int get_FileSize32(void);` |
| `FileSize64` | property, read-only | `__int64 get_FileSize64(void);` |
| `FileSizeStr` | property, read-only | `void get_FileSizeStr(CkString &str); const wchar_t *fileSizeStr(void);` |
| `FullPath` | property, read-only | `void get_FullPath(CkString &str); const wchar_t *fullPath(void);` |
| `FullUncPath` | property, read-only | `void get_FullUncPath(CkString &str); const wchar_t *fullUncPath(void);` |
| `IsDirectory` | property, read-only | `bool get_IsDirectory(void);` |
| `Recurse` | property, read/write | `bool get_Recurse(void); void put_Recurse(bool newVal);` |
| `RelativePath` | property, read-only | `void get_RelativePath(CkString &str); const wchar_t *relativePath(void);` |
| `UncommonOptions` | property, read/write | `void get_UncommonOptions(CkString &str); const wchar_t *uncommonOptions(void); void put_UncommonOptions(const wchar_t *str);` |
| `AdvancePosition` | method | `bool AdvancePosition(void);` |
| `BeginIterate` | method | `bool BeginIterate(void);` |

## Properties

### DirTree.BaseDir

`Chilkat 11.7.0 · wcpp · DirTree · BaseDir · property · read/write`

```cpp
void get_BaseDir(CkString &str);

const wchar_t *baseDir(void);

void put_BaseDir(const wchar_t *str);
```

Specifies the root directory whose contents are traversed. Set this property before calling `BeginIterate`.

The value may be an absolute filesystem path or a relative path. A relative path is resolved from the calling process's current working directory.

**Iteration scope:** The iterator visits the files and subdirectories contained under this directory. The `Recurse` property determines whether nested levels are included.

### DirTree.DoneIterating

`Chilkat 11.7.0 · wcpp · DirTree · DoneIterating · property · read-only`

```cpp
bool get_DoneIterating(void);
```

Indicates whether the traversal has reached its normal end and no current item remains.

This property is especially important because both `BeginIterate` and `AdvancePosition` can return *`false`* for either normal completion or an error:

| Method result | `DoneIterating` | Meaning |
| :--- | :--- | :--- |
| `false` | `true` | The directory was empty, or the last item has been passed. This is normal completion. |
| `false` | `false` | An error occurred. Examine `LastErrorText`. |

### DirTree.FileSize32

`Chilkat 11.7.0 · wcpp · DirTree · FileSize32 · property · read-only`

```cpp
int get_FileSize32(void);
```

Returns the size of the current file in bytes as a 32-bit integer. The value is `0` when the current item is a directory.

**Large files:** A 32-bit integer cannot represent all modern file sizes. Use `FileSize64` when the language binding provides it, or `FileSizeStr` when a decimal string is more portable.

### DirTree.FileSize64

`Chilkat 11.7.0 · wcpp · DirTree · FileSize64 · property · read-only`

```cpp
__int64 get_FileSize64(void);
```

Returns the size of the current file in bytes as a 64-bit integer. The value is `0` when the current item is a directory.

This is the preferred numeric size property for files that may exceed the range of `FileSize32`. In bindings that do not expose a 64-bit integer property, use `FileSizeStr`.

### DirTree.FileSizeStr

`Chilkat 11.7.0 · wcpp · DirTree · FileSizeStr · property · read-only · since 9.5.0.88`

```cpp
void get_FileSizeStr(CkString &str);

const wchar_t *fileSizeStr(void);
```

Returns the size of the current file in bytes as an unsigned decimal string. The value is `0` when the current item is a directory.

This representation is useful for very large files and for language bindings where a 64-bit integer is unavailable or inconvenient. Convert the string to an appropriate arbitrary-precision or 64-bit numeric type only when arithmetic is required.

### DirTree.FullPath

`Chilkat 11.7.0 · wcpp · DirTree · FullPath · property · read-only`

```cpp
void get_FullPath(CkString &str);

const wchar_t *fullPath(void);
```

Returns the absolute filesystem path of the current file or subdirectory, including the item's name.

The path uses the native path syntax for the operating system. For a path relative to `BaseDir`, use `RelativePath`.

### DirTree.FullUncPath

`Chilkat 11.7.0 · wcpp · DirTree · FullUncPath · property · read-only`

```cpp
void get_FullUncPath(CkString &str);

const wchar_t *fullUncPath(void);
```

Returns the current item's Windows extended-length absolute path. For example, a local path may be returned as `\\?\C:\data\reports\file.txt`; a network path may use the `\\?\UNC\server\share\...` form.

**Windows path form:** The `\\?\` prefix asks Windows to use extended-length path parsing and is useful when working with paths that may exceed legacy path-length limits. Use `FullPath` when an ordinary native absolute path is preferred.

### DirTree.IsDirectory

`Chilkat 11.7.0 · wcpp · DirTree · IsDirectory · property · read-only`

```cpp
bool get_IsDirectory(void);
```

Returns *`true`* when the current item is a subdirectory and *`false`* when it is a file.

Check this property before using a file-size property. Directory items report a size of `0`.

### DirTree.Recurse

`Chilkat 11.7.0 · wcpp · DirTree · Recurse · property · read/write`

```cpp
bool get_Recurse(void);

void put_Recurse(bool newVal);
```

Controls whether traversal descends into nested subdirectories.

| `true` | Visit files and directories throughout the complete tree rooted at `BaseDir`. |
| :--- | --- |
| `false` | Visit only the immediate contents of `BaseDir`. |

The default value is *`true`*. Set this property before calling `BeginIterate`.

### DirTree.RelativePath

`Chilkat 11.7.0 · wcpp · DirTree · RelativePath · property · read-only`

```cpp
void get_RelativePath(CkString &str);

const wchar_t *relativePath(void);
```

Returns the path of the current file or subdirectory relative to `BaseDir`, including the item's name.

For example, if `BaseDir` is `C:\data` and the current item is `C:\data\images\logo.png`, this property returns `images\logo.png` on Windows. Path separators follow the operating system's native convention.

### DirTree.UncommonOptions

`Chilkat 11.7.0 · wcpp · DirTree · UncommonOptions · property · read/write · since 11.1.0`

```cpp
void get_UncommonOptions(CkString &str);

const wchar_t *uncommonOptions(void);

void put_UncommonOptions(const wchar_t *str);
```

Provides a comma-separated list of specialized compatibility options. The default is the empty string, and applications should normally leave it unchanged.

| Keyword | Effect |
| :--- | :--- |
| `Q_EncodePaths` | Returns path-valued output properties in Chilkat's Q-encoded representation. Introduced in Chilkat v11.1.0. This changes only the returned string representation; it does not change which filesystem items are traversed. |

## Methods

### DirTree.AdvancePosition

`Chilkat 11.7.0 · wcpp · DirTree · AdvancePosition · method`

```cpp
bool AdvancePosition(void);
```

Advances the traversal from the current item to the next file or subdirectory.

If the method returns *`true`*, the current-item properties—such as `FullPath`, `RelativePath`, `IsDirectory`, and the file-size properties—describe the newly selected item.

| Return value | `DoneIterating` | Meaning |
| :--- | :--- | :--- |
| `true` | `false` | The iterator advanced successfully and a current item is available. |
| `false` | `true` | The last item has been passed; traversal completed normally. |
| `false` | `false` | An error occurred. Examine `LastErrorText`. |

Returns true for success, false for failure.

### DirTree.BeginIterate

`Chilkat 11.7.0 · wcpp · DirTree · BeginIterate · method`

```cpp
bool BeginIterate(void);
```

Initializes a new traversal using the current `BaseDir` and `Recurse` settings.

If the method returns *`true`*, the iterator is positioned at the first file or subdirectory, and the current-item properties can be read immediately. Continue by processing that item and then calling `AdvancePosition`.

| Return value | `DoneIterating` | Meaning |
| :--- | :--- | :--- |
| `true` | `false` | The first item is available. |
| `false` | `true` | The directory contains no items in the selected traversal scope. This is not an error. |
| `false` | `false` | Initialization failed. Examine `LastErrorText`. |

**Property lifetime:** Treat the current-item properties as valid only while the iterator is positioned on an item—that is, after a successful `BeginIterate` or `AdvancePosition`.

Returns true for success, false for failure.