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

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

## Purpose

**Configure DNS resolution and query DNS records directly from Chilkat.**

`Chilkat.Dns` is a focused class for DNS configuration and DNS record querying. It allows applications to control the nameservers used by Chilkat, query common DNS record types into JSON, configure DNS-over-TLS preference, set DNS query timeouts, and obtain useful diagnostics through `LastErrorText`.

**DNS record queries**

Query common DNS record types and receive structured JSON results that are easy to inspect or pass to other application logic.

**Nameserver control**

Configure the nameservers Chilkat uses instead of relying only on the operating system's default DNS configuration.

**DNS-over-TLS preference**

Prefer DNS-over-TLS when appropriate for applications that need encrypted DNS lookups.

**Timeout settings**

Control how long DNS queries may wait before failing, which is useful for responsive applications and troubleshooting.

**Application-wide behavior**

Nameserver settings affect DNS resolution across Chilkat classes, not only the current `Dns` object.

**Diagnostics**

Use `LastErrorText` to troubleshoot DNS configuration, lookup failures, timeout problems, or nameserver connectivity issues.

**Common pattern:** Use `Dns` either to perform direct DNS lookups, or to configure the DNS behavior used by Chilkat as a whole. Because nameserver changes can affect DNS resolution across Chilkat classes, treat them as application-wide configuration rather than object-local state.

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

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkDnsW instance = CkDnsW_Create();
// ...
CkDnsW_Dispose(instance);
```

`HCkDnsW CkDnsW_Create(void);`

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

`void CkDnsW_Dispose(HCkDnsW handle);`

Objects created by calling CkDnsW_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 CkDnsW_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 CkDnsW_getDebugLogFilePath(HCkDnsW cHandle, HCkString retval); void CkDnsW_putDebugLogFilePath(HCkDnsW cHandle, const wchar_t *newVal); const wchar_t *CkDnsW_debugLogFilePath(HCkDnsW 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 CkDnsW_getLastErrorHtml(HCkDnsW cHandle, HCkString retval); const wchar_t *CkDnsW_lastErrorHtml(HCkDnsW cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkDnsW_getLastErrorText(HCkDnsW cHandle, HCkString retval); const wchar_t *CkDnsW_lastErrorText(HCkDnsW cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkDnsW_getLastErrorXml(HCkDnsW cHandle, HCkString retval); const wchar_t *CkDnsW_lastErrorXml(HCkDnsW cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkDnsW_getLastMethodSuccess(HCkDnsW cHandle); void CkDnsW_putLastMethodSuccess(HCkDnsW cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `VerboseLogging` | `BOOL CkDnsW_getVerboseLogging(HCkDnsW cHandle); void CkDnsW_putVerboseLogging(HCkDnsW 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 CkDnsW_getVersion(HCkDnsW cHandle, HCkString retval); const wchar_t *CkDnsW_version(HCkDnsW cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `HeartbeatMs` | property, read/write | `int CkDnsW_getHeartbeatMs(HCkDnsW cHandle); void CkDnsW_putHeartbeatMs(HCkDnsW cHandle, int newVal);` |
| `MaxWaitMs` | property, read/write | `int CkDnsW_getMaxWaitMs(HCkDnsW cHandle); void CkDnsW_putMaxWaitMs(HCkDnsW cHandle, int newVal);` |
| `NumNameservers` | property, read-only | `int CkDnsW_getNumNameservers(HCkDnsW cHandle);` |
| `TlsPref` | property, read/write | `int CkDnsW_getTlsPref(HCkDnsW cHandle); void CkDnsW_putTlsPref(HCkDnsW cHandle, int newVal);` |
| `UncommonOptions` | property, read/write | `void CkDnsW_getUncommonOptions(HCkDnsW cHandle, HCkString retval); void CkDnsW_putUncommonOptions(HCkDnsW cHandle, const wchar_t *newVal); const wchar_t *CkDnsW_uncommonOptions(HCkDnsW cHandle);` |
| `AddDefaultNameservers` | method | `void CkDnsW_AddDefaultNameservers(HCkDnsW cHandle);` |
| `AddNameserver` | method | `void CkDnsW_AddNameserver(HCkDnsW cHandle, const wchar_t *ipAddr, BOOL supportsTls);` |
| `GetNameserver` | method | `BOOL CkDnsW_GetNameserver(HCkDnsW cHandle, int index, const wchar_t *outStr); const wchar_t *CkDnsW_getNameserver(HCkDnsW cHandle, int index);` |
| `Query` | method | `BOOL CkDnsW_Query(HCkDnsW cHandle, const wchar_t *recordType, const wchar_t *domain, HCkJsonObjectW answer);` |
| `RemoveAllNameservers` | method | `void CkDnsW_RemoveAllNameservers(HCkDnsW cHandle);` |
| `RemoveNameserver` | method | `void CkDnsW_RemoveNameserver(HCkDnsW cHandle, const wchar_t *ipAddr);` |

## Properties

### Dns.HeartbeatMs

`Chilkat 11.7.0 · wc · Dns · HeartbeatMs · property · read/write · since 9.5.0.96`

```c
int CkDnsW_getHeartbeatMs(HCkDnsW cHandle);
void CkDnsW_putHeartbeatMs(HCkDnsW 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)

The interval in milliseconds between each `AbortCheck` event callback, which enables an application to abort certain method calls before they complete. **By default, HeartbeatMs is set to** `0`**, meaning no AbortCheck event callbacks will trigger.**

### Dns.MaxWaitMs

`Chilkat 11.7.0 · wc · Dns · MaxWaitMs · property · read/write · since 9.5.0.96`

```c
int CkDnsW_getMaxWaitMs(HCkDnsW cHandle);
void CkDnsW_putMaxWaitMs(HCkDnsW cHandle, int newVal);
```

The maxiumum number of milliseconds to wait for the answer to a DNS query. A value of 0 is to wait indefinitely (no timeout). It's not a good idea to specify 0 (infinite timeout) or a value less than 1000 (1 second). The default value is 10000 milliseconds.

### Dns.NumNameservers

`Chilkat 11.7.0 · wc · Dns · NumNameservers · property · read-only · since 9.5.0.96`

```c
int CkDnsW_getNumNameservers(HCkDnsW cHandle);
```

The number of nameservers currently being used by Chilkat for DNS queries in all objects/classes, such as for HTTP, Email, FTP, SSH, etc.

### Dns.TlsPref

`Chilkat 11.7.0 · wc · Dns · TlsPref · property · read/write · since 9.5.0.96`

```c
int CkDnsW_getTlsPref(HCkDnsW cHandle);
void CkDnsW_putTlsPref(HCkDnsW cHandle, int newVal);
```

Specifies the TLS preference. Possible values are:

- 0 = No TLS
- 1 = Prefer TLS if possible.
- 2 = Require TLS

The default value is 0. If TLS is preferred then DNS nameservers with TLS capability will be tried first. If none succeed, then UDP/TCP will be tried. If TLS is required, then only TLS capable nameservers will be tried and all DNS queries will use TLS.

Note: To use TLS, your application needs to first specify nameservers by calling AddNameserver once per nameserver with the supportsTls argument set to `TRUE`.

### Dns.UncommonOptions

`Chilkat 11.7.0 · wc · Dns · UncommonOptions · property · read/write · since 11.4.0`

```c
void CkDnsW_getUncommonOptions(HCkDnsW cHandle, HCkString retval);
void CkDnsW_putUncommonOptions(HCkDnsW cHandle, const wchar_t *newVal);
const wchar_t *CkDnsW_uncommonOptions(HCkDnsW cHandle);
```

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string and should typically remain empty.

## Methods

### Dns.AddDefaultNameservers

`Chilkat 11.7.0 · wc · Dns · AddDefaultNameservers · method · since 9.5.0.96`

```c
void CkDnsW_AddDefaultNameservers(HCkDnsW cHandle);
```

Adds the default (auto-assigned) nameservers to the collection of nameservers used by Chilkat for DNS queries and domain to IP address lookups.

### Dns.AddNameserver

`Chilkat 11.7.0 · wc · Dns · AddNameserver · method · since 9.5.0.96`

```c
void CkDnsW_AddNameserver(HCkDnsW cHandle, const wchar_t *ipAddr, BOOL supportsTls);
```

Adds a new nameserver to the collection of nameservers used by Chilkat for DNS queries and domain to IP address lookups. The `ipAddr` specifies the IPv4 address of the nameserver. The `supportsTls` indicates if the namserver supports DoT (DNS over TLS. DoT uses port 853 for encrypted DNS communication.) If the TlsPreference property is set to 1 or 2, then Chilkat will use TLS nameservers.

### Dns.GetNameserver

`Chilkat 11.7.0 · wc · Dns · GetNameserver · method · since 9.5.0.96`

```c
BOOL CkDnsW_GetNameserver(HCkDnsW cHandle, int index, const wchar_t *outStr);
const wchar_t *CkDnsW_getNameserver(HCkDnsW cHandle, int index);
```

Returns the IP address of the Nth nameserver currently used by Chilkat for DNS queries and domain to IP address lookups. The `index` specifies the index of the nameserver. The 1st nameserver is at `index` 0.

Returns TRUE for success, FALSE for failure.

### Dns.Query

`Chilkat 11.7.0 · wc · Dns · Query · method · since 9.5.0.96`

```c
BOOL CkDnsW_Query(HCkDnsW cHandle, const wchar_t *recordType, const wchar_t *domain, HCkJsonObjectW answer);
```

Performs an DNS query for `domain` and returns the answer in `answer`. The type of DNS query is specified in `recordType` and can be A, AAAA, ALIAS, CAA, MX, NS, SOA, TXT. Additional record types can be added as needed.

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

### Dns.RemoveAllNameservers

`Chilkat 11.7.0 · wc · Dns · RemoveAllNameservers · method · since 9.5.0.96`

```c
void CkDnsW_RemoveAllNameservers(HCkDnsW cHandle);
```

Removes all nameservers from the collection of nameservers used by Chilkat. An application can call this method to reset to 0 nameservers before adding new nameservers. If a DNS domain to IP address resolution is needed by Chilkat, then the auto-assigned nameserver IP addresses will be automaticaly restored.

### Dns.RemoveNameserver

`Chilkat 11.7.0 · wc · Dns · RemoveNameserver · method · since 9.5.0.96`

```c
void CkDnsW_RemoveNameserver(HCkDnsW cHandle, const wchar_t *ipAddr);
```

Removes a nameserver from the collection of nameservers used by Chilkat. The `ipAddr` is the IPv4 address of the nameserver to be removed.

## 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 CkDnsW_QueryAsync(HCkDnsW cHandle, const wchar_t *recordType, const wchar_t *domain, HCkJsonObjectW answer);
```

## Related classes

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