---
product: Chilkat
product_version: 11.7.0
language: xbase
language_label: Xbase++
class: Dns
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/xbase_DnsRef.html
---
# Chilkat Dns — Xbase++ — v11.7.0

> Chilkat 11.7.0 · language=xbase · 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/xbase/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

**Object Creation**

```xbase
LOCAL oDns
oDns := CreateObject("Chilkat.Dns")

// ... use oDns ...

oDns:destroy()
```

Xbase++ uses the Chilkat ActiveX through the automation object returned by `CreateObject()`; properties and methods are accessed with the send operator (`oHttp:ConnectTimeout := 30`, `oHttp:Download(cUrl, cPath)`), and `:destroy()` releases the object. Register the Chilkat ActiveX matching the bitness of your Xbase++ application. To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as `CreateObject("Chilkat.Dns.11")` for Chilkat v11.\*.\*.

Boolean properties, arguments and return values are integers in the ActiveX: pass `1` or `0`, and test a method's success with `== 1`. A method that fails to return an object returns `NIL`. Objects returned by methods (such as an `HttpResponse` or `JsonObject`) are automation objects too and should likewise be released with `:destroy()`. Methods and properties that pass or return raw byte arrays are not shown on this page; use the `BinData`-based alternatives (methods ending in *Bd*) or the base64 / hex string-encoded variants instead.

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

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` | `oDns:DebugLogFilePath // Character` | 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` | `oDns:LastErrorHtml // Character (read-only)` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `oDns:LastErrorText // Character (read-only)` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `oDns:LastErrorXml // Character (read-only)` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `oDns:LastMethodSuccess // Numeric` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `oDns:LastStringResult // Character (read-only)` | read-only | In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. |
| `LastStringResultLen` | `oDns:LastStringResultLen // Numeric (read-only)` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `oDns:VerboseLogging // Numeric` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `oDns:Version // Character (read-only)` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MaxWaitMs` | property, read/write | `oDns:MaxWaitMs // Numeric` |
| `NumNameservers` | property, read-only | `oDns:NumNameservers // Numeric (read-only)` |
| `TlsPref` | property, read/write | `oDns:TlsPref // Numeric` |
| `UncommonOptions` | property, read/write | `oDns:UncommonOptions // Character` |
| `AddDefaultNameservers` | method | `oDns:AddDefaultNameservers()` |
| `AddNameserver` | method | `oDns:AddNameserver(cIpAddr, lSupportsTls)` |
| `GetNameserver` | method | `cResult := oDns:GetNameserver(nIndex) // returns Character` |
| `Query` | method | `nSuccess := oDns:Query(cRecordType, cDomain, oAnswer) // returns Numeric (1/0)` |
| `RemoveAllNameservers` | method | `oDns:RemoveAllNameservers()` |
| `RemoveNameserver` | method | `oDns:RemoveNameserver(cIpAddr)` |

## Properties

### Dns.MaxWaitMs

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

```xbase
oDns:MaxWaitMs  // Numeric
```

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 · xbase · Dns · NumNameservers · property · read-only · since 9.5.0.96`

```xbase
oDns:NumNameservers  // Numeric (read-only)
```

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 · xbase · Dns · TlsPref · property · read/write · since 9.5.0.96`

```xbase
oDns:TlsPref  // Numeric
```

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 `1`.

### Dns.UncommonOptions

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

```xbase
oDns:UncommonOptions  // Character
```

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 · xbase · Dns · AddDefaultNameservers · method · since 9.5.0.96`

```xbase
oDns:AddDefaultNameservers()
```

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 · xbase · Dns · AddNameserver · method · since 9.5.0.96`

```xbase
oDns:AddNameserver(cIpAddr, lSupportsTls)
```

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 · xbase · Dns · GetNameserver · method · since 9.5.0.96`

```xbase
cResult := oDns:GetNameserver(nIndex)  // returns Character
```

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 `NIL` on failure

### Dns.Query

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

```xbase
nSuccess := oDns:Query(cRecordType, cDomain, oAnswer)  // returns Numeric (1/0)
```

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 · xbase · Dns · RemoveAllNameservers · method · since 9.5.0.96`

```xbase
oDns:RemoveAllNameservers()
```

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 · xbase · Dns · RemoveNameserver · method · since 9.5.0.96`

```xbase
oDns:RemoveNameserver(cIpAddr)
```

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 has no event callbacks. For progress, percent-done or cancellation use the `*Async` variant of a method and poll the returned `Task` (`PercentDone`, `Finished`, `Cancel`).

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

```xbase
oTask := oDns:QueryAsync(cRecordType, cDomain, oAnswer)  // returns ChilkatTask
```

## Related classes

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

