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

> Chilkat 11.7.0 · language=c · 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/c/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
HCkDns instance = CkDns_Create();
// ...
CkDns_Dispose(instance);
```

`HCkDns CkDns_Create(void);`

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

`void CkDns_Dispose(HCkDns handle);`

Objects created by calling CkDns_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 CkDns_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 CkDns_getDebugLogFilePath(HCkDns cHandle, HCkString retval); void CkDns_putDebugLogFilePath(HCkDns cHandle, const char *newVal); const char *CkDns_debugLogFilePath(HCkDns 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 CkDns_getLastErrorHtml(HCkDns cHandle, HCkString retval); const char *CkDns_lastErrorHtml(HCkDns cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkDns_getLastErrorText(HCkDns cHandle, HCkString retval); const char *CkDns_lastErrorText(HCkDns cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkDns_getLastErrorXml(HCkDns cHandle, HCkString retval); const char *CkDns_lastErrorXml(HCkDns cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkDns_getLastMethodSuccess(HCkDns cHandle); void CkDns_putLastMethodSuccess(HCkDns cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `Utf8` | `BOOL CkDns_getUtf8(HCkDns cHandle); void CkDns_putUtf8(HCkDns cHandle, BOOL newVal);` | read/write | When set to `TRUE`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `BOOL CkDns_getVerboseLogging(HCkDns cHandle); void CkDns_putVerboseLogging(HCkDns 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 CkDns_getVersion(HCkDns cHandle, HCkString retval); const char *CkDns_version(HCkDns cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `HeartbeatMs` | property, read/write | `int CkDns_getHeartbeatMs(HCkDns cHandle); void CkDns_putHeartbeatMs(HCkDns cHandle, int newVal);` |
| `MaxWaitMs` | property, read/write | `int CkDns_getMaxWaitMs(HCkDns cHandle); void CkDns_putMaxWaitMs(HCkDns cHandle, int newVal);` |
| `NumNameservers` | property, read-only | `int CkDns_getNumNameservers(HCkDns cHandle);` |
| `TlsPref` | property, read/write | `int CkDns_getTlsPref(HCkDns cHandle); void CkDns_putTlsPref(HCkDns cHandle, int newVal);` |
| `UncommonOptions` | property, read/write | `void CkDns_getUncommonOptions(HCkDns cHandle, HCkString retval); void CkDns_putUncommonOptions(HCkDns cHandle, const char *newVal); const char *CkDns_uncommonOptions(HCkDns cHandle);` |
| `AddDefaultNameservers` | method | `void CkDns_AddDefaultNameservers(HCkDns cHandle);` |
| `AddNameserver` | method | `void CkDns_AddNameserver(HCkDns cHandle, const char *ipAddr, BOOL supportsTls);` |
| `GetNameserver` | method | `BOOL CkDns_GetNameserver(HCkDns cHandle, int index, HCkString outStr); const char *CkDns_getNameserver(HCkDns cHandle, int index);` |
| `Query` | method | `BOOL CkDns_Query(HCkDns cHandle, const char *recordType, const char *domain, HCkJsonObject answer);` |
| `RemoveAllNameservers` | method | `void CkDns_RemoveAllNameservers(HCkDns cHandle);` |
| `RemoveNameserver` | method | `void CkDns_RemoveNameserver(HCkDns cHandle, const char *ipAddr);` |

## Properties

### Dns.HeartbeatMs

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

```c
int CkDns_getHeartbeatMs(HCkDns cHandle);
void CkDns_putHeartbeatMs(HCkDns 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 · c · Dns · MaxWaitMs · property · read/write · since 9.5.0.96`

```c
int CkDns_getMaxWaitMs(HCkDns cHandle);
void CkDns_putMaxWaitMs(HCkDns 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 · c · Dns · NumNameservers · property · read-only · since 9.5.0.96`

```c
int CkDns_getNumNameservers(HCkDns 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 · c · Dns · TlsPref · property · read/write · since 9.5.0.96`

```c
int CkDns_getTlsPref(HCkDns cHandle);
void CkDns_putTlsPref(HCkDns 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 · c · Dns · UncommonOptions · property · read/write · since 11.4.0`

```c
void CkDns_getUncommonOptions(HCkDns cHandle, HCkString retval);
void CkDns_putUncommonOptions(HCkDns cHandle, const char *newVal);
const char *CkDns_uncommonOptions(HCkDns 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 · c · Dns · AddDefaultNameservers · method · since 9.5.0.96`

```c
void CkDns_AddDefaultNameservers(HCkDns 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 · c · Dns · AddNameserver · method · since 9.5.0.96`

```c
void CkDns_AddNameserver(HCkDns cHandle, const char *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 · c · Dns · GetNameserver · method · since 9.5.0.96`

```c
BOOL CkDns_GetNameserver(HCkDns cHandle, int index, HCkString outStr);
const char *CkDns_getNameserver(HCkDns 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 · c · Dns · Query · method · since 9.5.0.96`

```c
BOOL CkDns_Query(HCkDns cHandle, const char *recordType, const char *domain, HCkJsonObject 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 · c · Dns · RemoveAllNameservers · method · since 9.5.0.96`

```c
void CkDns_RemoveAllNameservers(HCkDns 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 · c · Dns · RemoveNameserver · method · since 9.5.0.96`

```c
void CkDns_RemoveNameserver(HCkDns cHandle, const char *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 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 CkDns_QueryAsync(HCkDns cHandle, const char *recordType, const char *domain, HCkJsonObject answer);
```

## Related classes

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