# DNS

# DNS

This module includes functions that control DNS communication.

## Summary

The functions in this module are available only if feature `OPENTHREAD_CONFIG_DNS_CLIENT_ENABLE` is enabled.

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gab0b5f6e49609e780d0cb7c9a87f6377a{ https://openthread.io/reference/group/api-dns#group__api-dns_1ggab0b5f6e49609e780d0cb7c9a87f6377aa34da721a212326b455397542da22489c = 0, https://openthread.io/reference/group/api-dns#group__api-dns_1ggab0b5f6e49609e780d0cb7c9a87f6377aa2a6eb05c98a08cbaadeb2e860a73dd3b = 1, https://openthread.io/reference/group/api-dns#group__api-dns_1ggab0b5f6e49609e780d0cb7c9a87f6377aa9d60ae5fbbfe745641ac053a0b47e7a3 = 2 }` | enumType represents the NAT64 mode in an `https://openthread.io/reference/struct/ot-dns-query-config`. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga8412585153e15488e7ea798aab839a7c{ https://openthread.io/reference/group/api-dns#group__api-dns_1gga8412585153e15488e7ea798aab839a7cac2f4cd444e9f85ff5524875897f032eb, https://openthread.io/reference/group/api-dns#group__api-dns_1gga8412585153e15488e7ea798aab839a7ca8534efb5b76ac87f29bc95d6bb536f4f, https://openthread.io/reference/group/api-dns#group__api-dns_1gga8412585153e15488e7ea798aab839a7cabe5d037cfced6064155b611dc058b064 }` | enumRepresents a section in a DNS query/response message. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga6754474ea5deb76d9a035903a88b4314{ https://openthread.io/reference/group/api-dns#group__api-dns_1gga6754474ea5deb76d9a035903a88b4314a83a9e014d06ac680857e55c916a6c8e1 = 0, https://openthread.io/reference/group/api-dns#group__api-dns_1gga6754474ea5deb76d9a035903a88b4314a53d2765b56a793589317264d2219c135 = 1, https://openthread.io/reference/group/api-dns#group__api-dns_1gga6754474ea5deb76d9a035903a88b4314a08fbd13abee61f01c9bd6d0013dda449 = 2 }` | enumType represents the "Recursion Desired" (RD) flag in an `https://openthread.io/reference/struct/ot-dns-query-config`. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gaf4fe63bece26b49d6425501b4ce327db{ https://openthread.io/reference/group/api-dns#group__api-dns_1ggaf4fe63bece26b49d6425501b4ce327dba439ea0eea39c9d42d4d96541b73d3754 = 0, https://openthread.io/reference/group/api-dns#group__api-dns_1ggaf4fe63bece26b49d6425501b4ce327dbaca4dee71def32d0addd0b153c777697f = 1, https://openthread.io/reference/group/api-dns#group__api-dns_1ggaf4fe63bece26b49d6425501b4ce327dbae27146b14b81b7f10fe8472374479e7c = 2, https://openthread.io/reference/group/api-dns#group__api-dns_1ggaf4fe63bece26b49d6425501b4ce327dba3384d0741e38dc5076dda8cd7278df3d = 3, https://openthread.io/reference/group/api-dns#group__api-dns_1ggaf4fe63bece26b49d6425501b4ce327dbaaacc95da5ade66bf0c77848beaea6a39 = 4, https://openthread.io/reference/group/api-dns#group__api-dns_1ggaf4fe63bece26b49d6425501b4ce327dba92405c29e4ed785e104a10ef55881363 = 5 }` | enumType represents the service resolution mode in an `https://openthread.io/reference/struct/ot-dns-query-config`. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gaba76aae698b8670b56fb59a6a2e5b4ce{ https://openthread.io/reference/group/api-dns#group__api-dns_1ggaba76aae698b8670b56fb59a6a2e5b4cea366ba4d98331f6ad8a059f32b3a1c56b = 1, https://openthread.io/reference/group/api-dns#group__api-dns_1ggaba76aae698b8670b56fb59a6a2e5b4cea4f4db4a7a8ae6aba8117f884c2000cb9 = 2 }` | enumType represents the DNS transport protocol in an `https://openthread.io/reference/struct/ot-dns-query-config`. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga802c11b73b3e1808efd15c0ce97586ba)(otError aError, const otDnsAddressResponse *aResponse, void *aContext)` | typedef `void(*` Pointer is called when a DNS response is received for an address resolution query. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga6f0e17a3652fcb57d46f5d9f51d86472` | typedef `struct https://openthread.io/reference/group/api-dns#group__api-dns_1ga6f0e17a3652fcb57d46f5d9f51d86472` An opaque representation of a response to an address resolution DNS query. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gafca47262d9d4d1573d5bd4cb81d320af)(otError aError, const otDnsBrowseResponse *aResponse, void *aContext)` | typedef `void(*` Pointer is called when a DNS response is received for a browse (service instance enumeration) query. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga1e93f77951c22980aab6118e4230bf79` | typedef `struct https://openthread.io/reference/group/api-dns#group__api-dns_1ga1e93f77951c22980aab6118e4230bf79` An opaque representation of a response to a browse (service instance enumeration) DNS query. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gaab351820431f9ab04d942a329a221ec9` | typedef `struct https://openthread.io/reference/struct/ot-dns-query-config` Represents a DNS query configuration. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga36d1a957dc7bf32ef42e1b71f9657e60)(otError aError, const otDnsRecordResponse *aResponse, void *aContext)` | typedef `void(*` Pointer is called when a DNS response is received for a DNS query to an arbitrary record type. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga7cd648c866a4c5032dc500526c87bc01` | typedef `struct https://openthread.io/reference/struct/ot-dns-record-info` Represents info for a record in an `otDnsRecordResponse`. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga05513053acc52257534b0192ff70219d` | typedef `struct https://openthread.io/reference/group/api-dns#group__api-dns_1ga05513053acc52257534b0192ff70219d` An opaque representation of a response to a query for an arbitrary record type. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga85bdd6591ee6b10b2265afa4b5d8c136)(otError aError, const otDnsServiceResponse *aResponse, void *aContext)` | typedef `void(*` Pointer is called when a DNS response is received for a service instance resolution query. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga72d13e7e5c80e5936b9cc55005a4bf12` | typedef `struct https://openthread.io/reference/struct/ot-dns-service-info` Provides info for a DNS service instance. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga3e6ea15c8b02b4a2aebd8721c0c0b6a0` | typedef `struct https://openthread.io/reference/group/api-dns#group__api-dns_1ga3e6ea15c8b02b4a2aebd8721c0c0b6a0` An opaque representation of a response to a service instance resolution DNS query. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gae499b289abde67b720d8f905348cd837` | typedef `struct https://openthread.io/reference/struct/ot-dns-txt-entry` Represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3). |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga1741fde3e5343fbc694c5af9d21b3fc2` | typedef `struct https://openthread.io/reference/struct/ot-dns-txt-entry-iterator` Represents an iterator for TXT record entries (key/value pairs). |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga938cd34aabd37e847b1a02c50daafd3a(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga6f0e17a3652fcb57d46f5d9f51d86472 *aResponse, uint16_t aIndex, https://openthread.io/reference/struct/ot-ip6-address *aAddress, uint32_t *aTtl)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets an IPv6 address associated with an address resolution DNS response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga01f3e29bbe6ed63e58eb0d73eea2dd90(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga6f0e17a3652fcb57d46f5d9f51d86472 *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the full host name associated with an address resolution DNS response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga050d381393fb4ea21227ec080d6537f5(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga1e93f77951c22980aab6118e4230bf79 *aResponse, const char *aHostName, uint16_t aIndex, https://openthread.io/reference/struct/ot-ip6-address *aAddress, uint32_t *aTtl)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the host IPv6 address from a DNS browse (service instance enumeration) response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga683d7fa652369429e87abbafba2f4665(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga1e93f77951c22980aab6118e4230bf79 *aResponse, const char *aInstanceLabel, https://openthread.io/reference/struct/ot-dns-service-info *aServiceInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets info for a service instance from a DNS browse (service instance enumeration) response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga7406224ea7fd02c144dded672031380c(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga1e93f77951c22980aab6118e4230bf79 *aResponse, uint16_t aIndex, char *aLabelBuffer, uint8_t aLabelBufferSize)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets a service instance associated with a DNS browse (service instance enumeration) response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gaf2b9294e745d3eca4608e0b4b3b61ffe(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga1e93f77951c22980aab6118e4230bf79 *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the service name associated with a DNS browse (service instance enumeration) response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga51ac6bec622be91262b2e3a2f570b484(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aServiceName, https://openthread.io/reference/group/api-dns#group__api-dns_1gafca47262d9d4d1573d5bd4cb81d320af aCallback, void *aContext, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a DNS browse (service instance enumeration) query for a given service name. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `const https://openthread.io/reference/struct/ot-dns-query-config *` Gets the current default query config used by DNS client. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga84cb690c71b68a4b0fec5912f724faf1(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aRecordType, const char *aFirstLabel, const char *aNextLabels, https://openthread.io/reference/group/api-dns#group__api-dns_1ga36d1a957dc7bf32ef42e1b71f9657e60 aCallback, void *aContext, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a DNS query for a given record type and name. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga4b736138305f5c034fb62c1d14c8b78d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aHostName, https://openthread.io/reference/group/api-dns#group__api-dns_1ga802c11b73b3e1808efd15c0ce97586ba aCallback, void *aContext, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends an address resolution DNS query for AAAA (IPv6) record(s) for a given host name. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga02a50f28f8628278e3661b5b36da4eeb(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aHostName, https://openthread.io/reference/group/api-dns#group__api-dns_1ga802c11b73b3e1808efd15c0ce97586ba aCallback, void *aContext, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends an address resolution DNS query for A (IPv4) record(s) for a given host name. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga37875e2aa21b199dc0206099d60540eb(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aInstanceLabel, const char *aServiceName, https://openthread.io/reference/group/api-dns#group__api-dns_1ga85bdd6591ee6b10b2265afa4b5d8c136 aCallback, void *aContext, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts a DNS service instance resolution for a given service instance. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga698f8f3418d81760bbcbd39f29773cd9(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aInstanceLabel, const char *aServiceName, https://openthread.io/reference/group/api-dns#group__api-dns_1ga85bdd6591ee6b10b2265afa4b5d8c136 aCallback, void *aContext, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts a DNS service instance resolution for a given service instance, with a potential follow-up address resolution for the host name discovered for the service instance. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gae6a6a5393d135f0f8104dfc515f7b136(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-dns-query-config *aConfig)` | `void` Sets the default query config on DNS client. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga27aa2a66d776522e071699534b1fa96e(const https://openthread.io/reference/struct/ot-dns-txt-entry *aTxtEntries, uint16_t aNumTxtEntries, uint8_t *aTxtData, uint16_t *aTxtDataLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Encodes a given list of TXT record entries (key/value pairs) into TXT data (following format specified by RFC 6763). |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gaa23314c7905781dcc6b938bc620a9614(https://openthread.io/reference/struct/ot-dns-txt-entry-iterator *aIterator, https://openthread.io/reference/struct/ot-dns-txt-entry *aEntry)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Parses the TXT data from an iterator and gets the next TXT record entry (key/value pair). |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga024f05cb3a25a9c07a595077cbe038f0(https://openthread.io/reference/struct/ot-dns-txt-entry-iterator *aIterator, const uint8_t *aTxtData, uint16_t aTxtDataLength)` | `void` Initializes a TXT record iterator. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga3cd21a39ce4e2ebb478e594b5731bc64(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the "DNS name compression" mode is enabled or not. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga1dc45ab721d165145935321d0d278e1f(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga05513053acc52257534b0192ff70219d *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the query name associated with a record query DNS response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga53862620158f479faf3b16037d68abc9(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga05513053acc52257534b0192ff70219d *aResponse, uint16_t aIndex, https://openthread.io/reference/struct/ot-dns-record-info *aRecordInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Reads the records from a DNS query response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga2cdf6f609592da6908188f3f3d6ff198(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga3e6ea15c8b02b4a2aebd8721c0c0b6a0 *aResponse, const char *aHostName, uint16_t aIndex, https://openthread.io/reference/struct/ot-ip6-address *aAddress, uint32_t *aTtl)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the host IPv6 address from a DNS service instance resolution response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga105c49e04bdccda32821676b68220583(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga3e6ea15c8b02b4a2aebd8721c0c0b6a0 *aResponse, https://openthread.io/reference/struct/ot-dns-service-info *aServiceInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets info for a service instance from a DNS service instance resolution response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga0844e6d5c1953d9c161ef3e4146bfb7e(const https://openthread.io/reference/group/api-dns#group__api-dns_1ga3e6ea15c8b02b4a2aebd8721c0c0b6a0 *aResponse, char *aLabelBuffer, uint8_t aLabelBufferSize, char *aNameBuffer, uint16_t aNameBufferSize)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the service instance name associated with a DNS service instance resolution response. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gab593cb1c1eacca646bae01baf3936f1c(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Enables/disables the "DNS name compression" mode. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga639ccb1c2287318243df88fe53781b59 64` | Maximum label string size (include null char at the end of string). |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga27c2ecd894e02aefaf71861d930240a4 255` | Maximum name string size (includes null char at the end of string). |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gabcc48d62d82d1123ae9765693aa3724b 64` | Maximum length of TXT key string supported by `https://openthread.io/reference/struct/ot-dns-txt-entry-iterator`. |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1gab705f56255f28b4399b3f0f2caef080f 9` | Recommended maximum length of TXT record key string (RFC 6763 - section 6.4). |
| `https://openthread.io/reference/group/api-dns#group__api-dns_1ga81e763bbb494b61053b1946163a657d7 1` | Minimum length of TXT record key string (RFC 6763 - section 6.4). |

| ### Structs ||
|---|---|
| [otDnsQueryConfig](https://openthread.io/reference/struct/ot-dns-query-config) | Represents a DNS query configuration. |
| [otDnsRecordInfo](https://openthread.io/reference/struct/ot-dns-record-info) | Represents info for a record in an `otDnsRecordResponse`. |
| [otDnsServiceInfo](https://openthread.io/reference/struct/ot-dns-service-info) | Provides info for a DNS service instance. |
| [otDnsTxtEntry](https://openthread.io/reference/struct/ot-dns-txt-entry) | Represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3). |
| [otDnsTxtEntryIterator](https://openthread.io/reference/struct/ot-dns-txt-entry-iterator) | Represents an iterator for TXT record entries (key/value pairs). |

## Enumerations

### otDnsNat64Mode

```
 otDnsNat64Mode
```
Type represents the NAT64 mode in an `https://openthread.io/reference/struct/ot-dns-query-config`.

The NAT64 mode indicates whether to allow or disallow NAT64 address translation during DNS client address resolution. This mode is only used when `OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE` is enabled.

| Properties ||
|---|---|
| `OT_DNS_NAT64_ALLOW` | Allow NAT64 address translation during DNS client address resolution. |
| `OT_DNS_NAT64_DISALLOW` | Do not allow NAT64 address translation during DNS client address resolution. |
| `OT_DNS_NAT64_UNSPECIFIED` | NAT64 mode is not specified. Use default NAT64 mode. |

### otDnsRecordSection

```
 otDnsRecordSection
```
Represents a section in a DNS query/response message.

| Properties ||
|---|---|
| `OT_DNS_SECTION_ADDITIONAL` | Additional section. |
| `OT_DNS_SECTION_ANSWER` | Answer section. |
| `OT_DNS_SECTION_AUTHORITY` | Authority section. |

### otDnsRecursionFlag

```
 otDnsRecursionFlag
```
Type represents the "Recursion Desired" (RD) flag in an `https://openthread.io/reference/struct/ot-dns-query-config`.

| Properties ||
|---|---|
| `OT_DNS_FLAG_NO_RECURSION` | Indicates DNS name server can not resolve the query recursively. |
| `OT_DNS_FLAG_RECURSION_DESIRED` | Indicates DNS name server can resolve the query recursively. |
| `OT_DNS_FLAG_UNSPECIFIED` | Indicates the flag is not specified. |

### otDnsServiceMode

```
 otDnsServiceMode
```
Type represents the service resolution mode in an `https://openthread.io/reference/struct/ot-dns-query-config`.

This is only used during DNS client service resolution `https://openthread.io/reference/group/api-dns#group__api-dns_1ga37875e2aa21b199dc0206099d60540eb`. It determines which record types to query.

| Properties ||
|---|---|
| `OT_DNS_SERVICE_MODE_SRV` | Query for SRV record only. |
| `OT_DNS_SERVICE_MODE_SRV_TXT` | Query for both SRV and TXT records in same message. |
| `OT_DNS_SERVICE_MODE_SRV_TXT_OPTIMIZE` | Query for TXT/SRV together first, if fails then query separately. |
| `OT_DNS_SERVICE_MODE_SRV_TXT_SEPARATE` | Query in parallel for SRV and TXT using separate messages. |
| `OT_DNS_SERVICE_MODE_TXT` | Query for TXT record only. |
| `OT_DNS_SERVICE_MODE_UNSPECIFIED` | Mode is not specified. Use default service mode. |

### otDnsTransportProto

```
 otDnsTransportProto
```
Type represents the DNS transport protocol in an `https://openthread.io/reference/struct/ot-dns-query-config`.

This `OT_DNS_TRANSPORT_TCP` is only supported when `OPENTHREAD_CONFIG_DNS_CLIENT_OVER_TCP_ENABLE` is enabled.

| Properties ||
|---|---|
| `OT_DNS_TRANSPORT_TCP` | DNS query should be sent via UDP. |
| `OT_DNS_TRANSPORT_UDP` | DNS transport is unspecified. |

## Typedefs

### otDnsAddressCallback

```
void(* otDnsAddressCallback)(otError aError, const otDnsAddressResponse *aResponse, void *aContext)
```
Pointer is called when a DNS response is received for an address resolution query.

Within this callback the user can use `otDnsAddressResponseGet{Item}()` functions along with the `aResponse` pointer to get more info about the response.

The `aResponse` pointer can only be used within this callback and after returning from this function it will not stay valid, so the user MUST NOT retain the `aResponse` pointer for later use.


The `aError` can have the following:

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | The result of the DNS transaction. | | `[in] aResponse` | A pointer to the response (it is always non-NULL). | | `[in] aContext` | A pointer to application-specific context. | |


- OT_ERROR_NONE A response was received successfully.
- OT_ERROR_ABORT A DNS transaction was aborted by stack.
- OT_ERROR_RESPONSE_TIMEOUT No DNS response has been received within timeout.

<br />

If the server rejects the address resolution request the error code from server is mapped as follow:


- (0) NOERROR Success (no error condition) -\> OT_ERROR_NONE
- (1) FORMERR Server unable to interpret due to format error -\> OT_ERROR_PARSE
- (2) SERVFAIL Server encountered an internal failure -\> OT_ERROR_FAILED
- (3) NXDOMAIN Name that ought to exist, does not exist -\> OT_ERROR_NOT_FOUND
- (4) NOTIMP Server does not support the query type (OpCode) -\> OT_ERROR_NOT_IMPLEMENTED
- (5) REFUSED Server refused for policy/security reasons -\> OT_ERROR_SECURITY
- (6) YXDOMAIN Some name that ought not to exist, does exist -\> OT_ERROR_DUPLICATED
- (7) YXRRSET Some RRset that ought not to exist, does exist -\> OT_ERROR_DUPLICATED
- (8) NXRRSET Some RRset that ought to exist, does not exist -\> OT_ERROR_NOT_FOUND
- (9) NOTAUTH Service is not authoritative for zone -\> OT_ERROR_SECURITY
- (10) NOTZONE A name is not in the zone -\> OT_ERROR_PARSE
- (20) BADNAME Bad name -\> OT_ERROR_PARSE
- (21) BADALG Bad algorithm -\> OT_ERROR_SECURITY
- (22) BADTRUN Bad truncation -\> OT_ERROR_PARSE
- Other response codes -\> OT_ERROR_FAILED

<br />

### otDnsAddressResponse

```
struct otDnsAddressResponse otDnsAddressResponse
```
An opaque representation of a response to an address resolution DNS query.

Pointers to instance of this type are provided from callback `otDnsAddressCallback`.

### otDnsBrowseCallback

```
void(* otDnsBrowseCallback)(otError aError, const otDnsBrowseResponse *aResponse, void *aContext)
```
Pointer is called when a DNS response is received for a browse (service instance enumeration) query.

Within this callback the user can use `otDnsBrowseResponseGet{Item}()` functions along with the `aResponse` pointer to get more info about the response.

The `aResponse` pointer can only be used within this callback and after returning from this function it will not stay valid, so the user MUST NOT retain the `aResponse` pointer for later use.


For the full list of possible values for `aError`, please see `https://openthread.io/reference/group/api-dns#group__api-dns_1ga802c11b73b3e1808efd15c0ce97586ba`.

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | The result of the DNS transaction. | | `[in] aResponse` | A pointer to the response (it is always non-NULL). | | `[in] aContext` | A pointer to application-specific context. | |

### otDnsBrowseResponse

```
struct otDnsBrowseResponse otDnsBrowseResponse
```
An opaque representation of a response to a browse (service instance enumeration) DNS query.

Pointers to instance of this type are provided from callback `otDnsBrowseCallback`.

### otDnsQueryConfig

```
struct otDnsQueryConfig otDnsQueryConfig
```
Represents a DNS query configuration.

Any of the fields in this structure can be set to zero to indicate that it is not specified. How the unspecified fields are treated is determined by the function which uses the instance of `https://openthread.io/reference/struct/ot-dns-query-config`.

### otDnsRecordCallback

```
void(* otDnsRecordCallback)(otError aError, const otDnsRecordResponse *aResponse, void *aContext)
```
Pointer is called when a DNS response is received for a DNS query to an arbitrary record type.

Within this callback the user can use `otDnsRecordResponseGet{Item}()` functions along with the `aResponse` pointer to get more info about the response.

The `aResponse` pointer can only be used within this callback and after returning from this function it will not stay valid, so the user MUST NOT retain the `aResponse` pointer for later use.


The `aError` can have the following:

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | The result of the DNS transaction. | | `[in] aResponse` | A pointer to the response (it is always non-NULL). | | `[in] aContext` | A pointer to application-specific context. | |


- OT_ERROR_NONE A response was received successfully.
- OT_ERROR_ABORT A DNS transaction was aborted by the stack.
- OT_ERROR_RESPONSE_TIMEOUT No DNS response has been received within timeout.

<br />

### otDnsRecordInfo

```
struct otDnsRecordInfo otDnsRecordInfo
```
Represents info for a record in an `otDnsRecordResponse`.

This struct is used as input to `https://openthread.io/reference/group/api-dns#group__api-dns_1ga53862620158f479faf3b16037d68abc9`.

### otDnsRecordResponse

```
struct otDnsRecordResponse otDnsRecordResponse
```
An opaque representation of a response to a query for an arbitrary record type.

Pointers to instance of this type are provided from callback `otDnsRecordCallback`.

### otDnsServiceCallback

```
void(* otDnsServiceCallback)(otError aError, const otDnsServiceResponse *aResponse, void *aContext)
```
Pointer is called when a DNS response is received for a service instance resolution query.

Within this callback the user can use `otDnsServiceResponseGet{Item}()` functions along with the `aResponse` pointer to get more info about the response.

The `aResponse` pointer can only be used within this callback and after returning from this function it will not stay valid, so the user MUST NOT retain the `aResponse` pointer for later use.


For the full list of possible values for `aError`, please see `https://openthread.io/reference/group/api-dns#group__api-dns_1ga802c11b73b3e1808efd15c0ce97586ba`.

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aError` | The result of the DNS transaction. | | `[in] aResponse` | A pointer to the response (it is always non-NULL). | | `[in] aContext` | A pointer to application-specific context. | |

### otDnsServiceInfo

```
struct otDnsServiceInfo otDnsServiceInfo
```
Provides info for a DNS service instance.

### otDnsServiceResponse

```
struct otDnsServiceResponse otDnsServiceResponse
```
An opaque representation of a response to a service instance resolution DNS query.

Pointers to instance of this type are provided from callback `otDnsAddressCallback`.

### otDnsTxtEntry

```
struct otDnsTxtEntry otDnsTxtEntry
```
Represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3).

The string buffers pointed to by `mKey` and `mValue` MUST persist and remain unchanged after an instance of such structure is passed to OpenThread (as part of `https://openthread.io/reference/struct/ot-srp-client-service` instance).

An array of `https://openthread.io/reference/struct/ot-dns-txt-entry` entries are used in `https://openthread.io/reference/struct/ot-srp-client-service` to specify the full TXT record (a list of entries).

### otDnsTxtEntryIterator

```
struct otDnsTxtEntryIterator otDnsTxtEntryIterator
```
Represents an iterator for TXT record entries (key/value pairs).

The data fields in this structure are intended for use by OpenThread core and caller should not read or change them.

## Functions

### otDnsAddressResponseGetAddress

```
otError otDnsAddressResponseGetAddress(
  const otDnsAddressResponse *aResponse,
  uint16_t aIndex,
  otIp6Address *aAddress,
  uint32_t *aTtl
)
```
Gets an IPv6 address associated with an address resolution DNS response.

MUST only be used from `otDnsAddressCallback`.

The response may include multiple IPv6 address records. `aIndex` can be used to iterate through the list of addresses. Index zero gets the first address and so on. When we reach end of the list, `OT_ERROR_NOT_FOUND` is returned.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[in] aIndex` | The address record index to retrieve. | | `[out] aAddress` | A pointer to a IPv6 address to output the address (MUST NOT be NULL). | | `[out] aTtl` | A pointer to an `uint32_t` to output TTL for the address. It can be NULL if caller does not want to get the TTL. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The address was read successfully. | | `OT_ERROR_NOT_FOUND` | No address record in `aResponse` at `aIndex`. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | | `OT_ERROR_INVALID_STATE` | No NAT64 prefix (applicable only when NAT64 is allowed). | |

### otDnsAddressResponseGetHostName

```
otError otDnsAddressResponseGetHostName(
  const otDnsAddressResponse *aResponse,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)
```
Gets the full host name associated with an address resolution DNS response.

MUST only be used from `otDnsAddressCallback`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[out] aNameBuffer` | A buffer to char array to output the full host name (MUST NOT be NULL). | | `[in] aNameBufferSize` | The size of `aNameBuffer`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The full host name was read successfully. | | `OT_ERROR_NO_BUFS` | The name does not fit in `aNameBuffer`. | |

### otDnsBrowseResponseGetHostAddress

```
otError otDnsBrowseResponseGetHostAddress(
  const otDnsBrowseResponse *aResponse,
  const char *aHostName,
  uint16_t aIndex,
  otIp6Address *aAddress,
  uint32_t *aTtl
)
```
Gets the host IPv6 address from a DNS browse (service instance enumeration) response.

MUST only be used from `otDnsBrowseCallback`.

The response can include zero or more IPv6 address records. `aIndex` can be used to iterate through the list of addresses. Index zero gets the first address and so on. When we reach end of the list, `OT_ERROR_NOT_FOUND` is returned.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[in] aHostName` | The host name to get the address (MUST NOT be NULL). | | `[in] aIndex` | The address record index to retrieve. | | `[out] aAddress` | A pointer to a IPv6 address to output the address (MUST NOT be NULL). | | `[out] aTtl` | A pointer to an `uint32_t` to output TTL for the address. It can be NULL if caller does not want to get the TTL. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The address was read successfully. | | `OT_ERROR_NOT_FOUND` | No address record for `aHostname` in `aResponse` at `aIndex`. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | |

### otDnsBrowseResponseGetServiceInfo

```
otError otDnsBrowseResponseGetServiceInfo(
  const otDnsBrowseResponse *aResponse,
  const char *aInstanceLabel,
  otDnsServiceInfo *aServiceInfo
)
```
Gets info for a service instance from a DNS browse (service instance enumeration) response.

MUST only be used from `otDnsBrowseCallback`.

A browse DNS response can include SRV, TXT, and AAAA records for the service instances that are enumerated. This is a SHOULD and not a MUST requirement, and servers/resolvers are not required to provide this. This function attempts to retrieve this info for a given service instance when available.


- If no matching SRV record is found in `aResponse`, `OT_ERROR_NOT_FOUND` is returned. In this case, no additional records (no TXT and/or AAAA) are read.
- If a matching SRV record is found in `aResponse`, `aServiceInfo` is updated and `OT_ERROR_NONE` is returned.
- If no matching TXT record is found in `aResponse`, `mTxtDataSize` in `aServiceInfo` is set to zero.
- If TXT data length is greater than `mTxtDataSize`, it is read partially and `mTxtDataTruncated` is set to true.
- If no matching AAAA record is found in `aResponse`, `mHostAddress is set to all zero or unspecified address.`
- `If there are multiple AAAA records for the host name in @p aResponse,`mHostAddress`is set to the first one. The other addresses can be retrieved using`[otDnsBrowseResponseGetHostAddress()](https://openthread.io/reference/group/api-dns#group__api-dns_1ga050d381393fb4ea21227ec080d6537f5)\`.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[in] aInstanceLabel` | The service instance label (MUST NOT be NULL). | | `[out] aServiceInfo` | A `ServiceInfo` to output the service instance information (MUST NOT be NULL). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The service instance info was read. `aServiceInfo` is updated. | | `OT_ERROR_NOT_FOUND` | Could not find a matching SRV record for `aInstanceLabel`. | | `OT_ERROR_NO_BUFS` | The host name and/or TXT data could not fit in the given buffers. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | |

### otDnsBrowseResponseGetServiceInstance

```
otError otDnsBrowseResponseGetServiceInstance(
  const otDnsBrowseResponse *aResponse,
  uint16_t aIndex,
  char *aLabelBuffer,
  uint8_t aLabelBufferSize
)
```
Gets a service instance associated with a DNS browse (service instance enumeration) response.

MUST only be used from `otDnsBrowseCallback`.

The response may include multiple service instance records. `aIndex` can be used to iterate through the list. Index zero gives the first record. When we reach end of the list, `OT_ERROR_NOT_FOUND` is returned.

Note that this function gets the service instance label and not the full service instance name which is of the form `..`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[in] aIndex` | The service instance record index to retrieve. | | `[out] aLabelBuffer` | A buffer to char array to output the service instance label (MUST NOT be NULL). | | `[in] aLabelBufferSize` | The size of `aLabelBuffer`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The service instance was read successfully. | | `OT_ERROR_NO_BUFS` | The name does not fit in `aNameBuffer`. | | `OT_ERROR_NOT_FOUND` | No service instance record in `aResponse` at `aIndex`. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | |

### otDnsBrowseResponseGetServiceName

```
otError otDnsBrowseResponseGetServiceName(
  const otDnsBrowseResponse *aResponse,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)
```
Gets the service name associated with a DNS browse (service instance enumeration) response.

MUST only be used from `otDnsBrowseCallback`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[out] aNameBuffer` | A buffer to char array to output the service name (MUST NOT be NULL). | | `[in] aNameBufferSize` | The size of `aNameBuffer`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The service name was read successfully. | | `OT_ERROR_NO_BUFS` | The name does not fit in `aNameBuffer`. | |

### otDnsClientBrowse

```
otError otDnsClientBrowse(
  otInstance *aInstance,
  const char *aServiceName,
  otDnsBrowseCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)
```
Sends a DNS browse (service instance enumeration) query for a given service name.

Is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled.

The `aConfig` can be NULL. In this case the default config (from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc`) will be used as the config for this query. In a non-NULL `aConfig`, some of the fields can be left unspecified (value zero). The unspecified fields are then replaced by the values from the default config.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aServiceName` | The service name to query for (MUST NOT be NULL). | | `[in] aCallback` | A function pointer that shall be called on response reception or time-out. | | `[in] aContext` | A pointer to arbitrary context information. | | `[in] aConfig` | A pointer to the config to use for this query. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Query sent successfully. `aCallback` will be invoked to report the status. | | `OT_ERROR_NO_BUFS` | Insufficient buffer to prepare and send query. | |

### otDnsClientGetDefaultConfig

```
const otDnsQueryConfig * otDnsClientGetDefaultConfig(
  otInstance *aInstance
)
```
Gets the current default query config used by DNS client.

When OpenThread stack starts, the default DNS query config is determined from a set of OT config options such as `OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_SERVER_IP6_ADDRESS`, `_DEFAULT_SERVER_PORT`, `_DEFAULT_RESPONSE_TIMEOUT`, etc. (see `config/dns_client.h` for all related config options).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | A pointer to the current default config being used by DNS client. |

### otDnsClientQueryRecord

```
otError otDnsClientQueryRecord(
  otInstance *aInstance,
  uint16_t aRecordType,
  const char *aFirstLabel,
  const char *aNextLabels,
  otDnsRecordCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)
```
Sends a DNS query for a given record type and name.

Requires `OPENTHREAD_CONFIG_DNS_CLIENT_ARBITRARY_RECORD_QUERY_ENABLE`.

The `aConfig` can be NULL. In this case the default config (from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc`) will be used as the config for this query. In a non-NULL `aConfig`, some of the fields can be left unspecified (value zero). The unspecified fields are then replaced by the values from the default config.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aRecordType` | The resource record type to query. | | `[in] aFirstLabel` | The first label of the name to be queried (can be NULL if not needed). | | `[in] aNextLabels` | The next labels of the name to be queried (MUST NOT be NULL). | | `[in] aCallback` | A function pointer that shall be called on response reception or time-out. | | `[in] aContext` | A pointer to arbitrary context information used when `aCallback` is invoked. | | `[in] aConfig` | A pointer to the config to use for this query. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Query sent successfully. `aCallback` will be invoked to report the outcome. | | `OT_ERROR_NO_BUFS` | Insufficient buffer to prepare and send query. | | `OT_ERROR_INVALID_STATE` | Cannot send query since Thread interface is not up. | |

### otDnsClientResolveAddress

```
otError otDnsClientResolveAddress(
  otInstance *aInstance,
  const char *aHostName,
  otDnsAddressCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)
```
Sends an address resolution DNS query for AAAA (IPv6) record(s) for a given host name.

The `aConfig` can be NULL. In this case the default config (from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc`) will be used as the config for this query. In a non-NULL `aConfig`, some of the fields can be left unspecified (value zero). The unspecified fields are then replaced by the values from the default config.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aHostName` | The host name for which to query the address (MUST NOT be NULL). | | `[in] aCallback` | A function pointer that shall be called on response reception or time-out. | | `[in] aContext` | A pointer to arbitrary context information. | | `[in] aConfig` | A pointer to the config to use for this query. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Query sent successfully. `aCallback` will be invoked to report the status. | | `OT_ERROR_NO_BUFS` | Insufficient buffer to prepare and send query. | | `OT_ERROR_INVALID_ARGS` | The host name is not valid format. | | `OT_ERROR_INVALID_STATE` | Cannot send query since Thread interface is not up. | |

### otDnsClientResolveIp4Address

```
otError otDnsClientResolveIp4Address(
  otInstance *aInstance,
  const char *aHostName,
  otDnsAddressCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)
```
Sends an address resolution DNS query for A (IPv4) record(s) for a given host name.

Requires and is available when `OPENTHREAD_CONFIG_DNS_CLIENT_NAT64_ENABLE` is enabled.

When a successful response is received, the addresses are returned from `aCallback` as NAT64 IPv6 translated versions of the IPv4 addresses from the query response.

The `aConfig` can be NULL. In this case the default config (from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc`) will be used as the config for this query. In a non-NULL `aConfig`, some of the fields can be left unspecified (value zero). The unspecified fields are then replaced by the values from the default config.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aHostName` | The host name for which to query the address (MUST NOT be NULL). | | `[in] aCallback` | A function pointer that shall be called on response reception or time-out. | | `[in] aContext` | A pointer to arbitrary context information. | | `[in] aConfig` | A pointer to the config to use for this query. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Query sent successfully. `aCallback` will be invoked to report the status. | | `OT_ERROR_NO_BUFS` | Insufficient buffer to prepare and send query. | | `OT_ERROR_INVALID_ARGS` | The host name is not valid format or NAT64 is not enabled in config. | | `OT_ERROR_INVALID_STATE` | Cannot send query since Thread interface is not up. | |

### otDnsClientResolveService

```
otError otDnsClientResolveService(
  otInstance *aInstance,
  const char *aInstanceLabel,
  const char *aServiceName,
  otDnsServiceCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)
```
Starts a DNS service instance resolution for a given service instance.

Is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled.

The `aConfig` can be NULL. In this case the default config (from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc`) will be used as the config for this query. In a non-NULL `aConfig`, some of the fields can be left unspecified (value zero). The unspecified fields are then replaced by the values from the default config.

The function sends queries for SRV and/or TXT records for the given service instance. The `mServiceMode` field in `https://openthread.io/reference/struct/ot-dns-query-config` determines which records to query (SRV only, TXT only, or both SRV and TXT) and how to perform the query (together in the same message, separately in parallel, or in optimized mode where client will try in the same message first and then separately if it fails to get a response).

The SRV record provides information about service port, priority, and weight along with the host name associated with the service instance. This function DOES NOT perform address resolution for the host name discovered from SRV record. The server/resolver may provide AAAA/A record(s) for the host name in the Additional Data section of the response to SRV/TXT query and this information can be retrieved using `https://openthread.io/reference/group/api-dns#group__api-dns_1ga105c49e04bdccda32821676b68220583` in `otDnsServiceCallback`. Users of this API MUST NOT assume that host address will always be available from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga105c49e04bdccda32821676b68220583`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aInstanceLabel` | The service instance label. | | `[in] aServiceName` | The service name (together with `aInstanceLabel` form full instance name). | | `[in] aCallback` | A function pointer that shall be called on response reception or time-out. | | `[in] aContext` | A pointer to arbitrary context information. | | `[in] aConfig` | A pointer to the config to use for this query. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Query sent successfully. `aCallback` will be invoked to report the status. | | `OT_ERROR_NO_BUFS` | Insufficient buffer to prepare and send query. | | `OT_ERROR_INVALID_ARGS` | `aInstanceLabel` is NULL. | |

### otDnsClientResolveServiceAndHostAddress

```
otError otDnsClientResolveServiceAndHostAddress(
  otInstance *aInstance,
  const char *aInstanceLabel,
  const char *aServiceName,
  otDnsServiceCallback aCallback,
  void *aContext,
  const otDnsQueryConfig *aConfig
)
```
Starts a DNS service instance resolution for a given service instance, with a potential follow-up address resolution for the host name discovered for the service instance.

Is available when `OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE` is enabled.

The `aConfig` can be NULL. In this case the default config (from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga506d2d7531ae0fe7785f0f575812c4fc`) will be used as the config for this query. In a non-NULL `aConfig`, some of the fields can be left unspecified (value zero). The unspecified fields are then replaced by the values from the default config. This function cannot be used with `mServiceMode` in DNS config set to `OT_DNS_SERVICE_MODE_TXT` (i.e., querying for TXT record only) and will return `OT_ERROR_INVALID_ARGS`.

Behaves similarly to `https://openthread.io/reference/group/api-dns#group__api-dns_1ga37875e2aa21b199dc0206099d60540eb` sending queries for SRV and TXT records. However, if the server/resolver does not provide AAAA/A records for the host name in the response to SRV query (in the Additional Data section), it will perform host name resolution (sending an AAAA query) for the discovered host name from the SRV record. The callback `aCallback` is invoked when responses for all queries are received (i.e., both service and host address resolutions are finished).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aInstanceLabel` | The service instance label. | | `[in] aServiceName` | The service name (together with `aInstanceLabel` form full instance name). | | `[in] aCallback` | A function pointer that shall be called on response reception or time-out. | | `[in] aContext` | A pointer to arbitrary context information. | | `[in] aConfig` | A pointer to the config to use for this query. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Query sent successfully. `aCallback` will be invoked to report the status. | | `OT_ERROR_NO_BUFS` | Insufficient buffer to prepare and send query. | | `OT_ERROR_INVALID_ARGS` | `aInstanceLabel` is NULL, or `aConfig` is invalid. | |

### otDnsClientSetDefaultConfig

```
void otDnsClientSetDefaultConfig(
  otInstance *aInstance,
  const otDnsQueryConfig *aConfig
)
```
Sets the default query config on DNS client.

<br />

> [!NOTE]
> **Note:** Any ongoing query will continue to use the config from when it was started. The new default config will be used for any future DNS queries.

The `aConfig` can be NULL. In this case the default config will be set to the defaults from OT config options `OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_{}`. This resets the default query config back to to the config when the OpenThread stack starts.

<br />

In a non-NULL `aConfig`, caller can choose to leave some of the fields in `https://openthread.io/reference/struct/ot-dns-query-config` instance unspecified (value zero). The unspecified fields are replaced by the corresponding OT config option definitions `OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_{}` to form the default query config.

When `OPENTHREAD_CONFIG_DNS_CLIENT_DEFAULT_SERVER_ADDRESS_AUTO_SET_ENABLE` is enabled, the server's IPv6 address in the default config is automatically set and updated by DNS client. This is done only when user does not explicitly set or specify it. This behavior requires SRP client and its auto-start feature to be enabled. SRP client will then monitor the Thread Network Data for DNS/SRP Service entries to select an SRP server. The selected SRP server address is also set as the DNS server address in the default config.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aConfig` | A pointer to the new query config to use as default. | |

### otDnsEncodeTxtData

```
otError otDnsEncodeTxtData(
  const otDnsTxtEntry *aTxtEntries,
  uint16_t aNumTxtEntries,
  uint8_t *aTxtData,
  uint16_t *aTxtDataLength
)
```
Encodes a given list of TXT record entries (key/value pairs) into TXT data (following format specified by RFC 6763).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aTxtEntries` | Pointer to an array of `https://openthread.io/reference/struct/ot-dns-txt-entry`. | | `[in] aNumTxtEntries` | Number of entries in `aTxtEntries` array. | | `[out] aTxtData` | A pointer to a buffer to output the encoded TXT data. | | `[in,out] aTxtDataLength` | On input, size of buffer `aTxtData`. On output, length of the encoded TXT data. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Encoded TXT data successfully, `aTxtData` and `aTxtDataLength` are updated. | | `OT_ERROR_INVALID_ARGS` | The `aTxtEntries` is not valid. | | `OT_ERROR_NO_BUS` | Could not fit the encoded data in `aTxtData` buffer with its `aTxtDataLength`. | |

### otDnsGetNextTxtEntry

```
otError otDnsGetNextTxtEntry(
  otDnsTxtEntryIterator *aIterator,
  otDnsTxtEntry *aEntry
)
```
Parses the TXT data from an iterator and gets the next TXT record entry (key/value pair).

The `aIterator` MUST be initialized using `https://openthread.io/reference/group/api-dns#group__api-dns_1ga024f05cb3a25a9c07a595077cbe038f0` before calling this function and the TXT data buffer used to initialize the iterator MUST persist and remain unchanged. Otherwise the behavior of this function is undefined.

If the parsed key string length is smaller than or equal to `OT_DNS_TXT_KEY_ITER_MAX_LENGTH` the key string is returned in `mKey` in `aEntry`. But if the key is longer, then `mKey` is set to NULL and the entire encoded TXT entry string is returned in `mValue` and `mValueLength`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aIterator` | A pointer to the iterator (MUST NOT be NULL). | | `[out] aEntry` | A pointer to a `https://openthread.io/reference/struct/ot-dns-txt-entry` structure to output the parsed/read entry (MUST NOT be NULL). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The next entry was parsed successfully. `aEntry` is updated. | | `OT_ERROR_NOT_FOUND` | No more entries in the TXT data. | | `OT_ERROR_PARSE` | The TXT data from `aIterator` is not well-formed. | |

### otDnsInitTxtEntryIterator

```
void otDnsInitTxtEntryIterator(
  otDnsTxtEntryIterator *aIterator,
  const uint8_t *aTxtData,
  uint16_t aTxtDataLength
)
```
Initializes a TXT record iterator.

The buffer pointer `aTxtData` and its content MUST persist and remain unchanged while `aIterator` object is being used.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aIterator` | A pointer to the iterator to initialize (MUST NOT be NULL). | | `[in] aTxtData` | A pointer to buffer containing the encoded TXT data. | | `[in] aTxtDataLength` | The length (number of bytes) of `aTxtData`. | |

### otDnsIsNameCompressionEnabled

```
bool otDnsIsNameCompressionEnabled(
  otInstance *aInstance
)
```
Indicates whether the "DNS name compression" mode is enabled or not.

This is intended for testing only and available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` config is enabled.

<br />

| Details ||
|---|---|
| **Returns** | TRUE if the "DNS name compression" mode is enabled, FALSE otherwise. |

### otDnsRecordResponseGetQueryName

```
otError otDnsRecordResponseGetQueryName(
  const otDnsRecordResponse *aResponse,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)
```
Gets the query name associated with a record query DNS response.

MUST only be used from `otDnsRecordCallback`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[out] aNameBuffer` | A buffer to char array to output the full query name (MUST NOT be NULL). | | `[in] aNameBufferSize` | The size of `aNameBuffer`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The full query name was read successfully. | | `OT_ERROR_NO_BUFS` | The name does not fit in `aNameBuffer`. | |

### otDnsRecordResponseGetRecordInfo

```
otError otDnsRecordResponseGetRecordInfo(
  const otDnsRecordResponse *aResponse,
  uint16_t aIndex,
  otDnsRecordInfo *aRecordInfo
)
```
Reads the records from a DNS query response.

MUST only be used from `otDnsRecordCallback`.

The response may include multiple records. `aIndex` can be used to iterate through the list. Index zero gets the first record and so on. When we reach the end of the list, `OT_ERROR_NOT_FOUND` is returned.

Upon successful retrieval (`OT_ERROR_NONE`):

- `mRecordLength` is set to the actual length of the record's data.
- The data is copied into `mDataBuffer` (if not `NULL`) up to its capacity specified by `mDataBufferSize`.
- `mDataBufferSize` is then updated to reflect the number of bytes actually written into `mDataBuffer`.

<br />

If the retrieved record type is NS, CNAME, SOA, PTR, MX, RP, AFSDB, RT, PX, SRV, KX, DNAME, or NSEC, the record data in the received response contains a DNS name which may use DNS name compression. For these specific record types, the record data is first decompressed such that it contains the full uncompressed DNS name. This decompressed data is then provided in `mDataBuffer`, and `mRecordDataLength` will indicate the length of this decompressed data. For all other record types, the record data is read and provided as it appears in the received response message.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[in] aIndex` | The record index to retrieve. | | `[out] aRecordInfo` | A pointer to a `https://openthread.io/reference/struct/ot-dns-record-info` to populate with read record info. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The record was read successfully. | | `OT_ERROR_NOT_FOUND` | No record in `aResponse` at `aIndex`. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | | `OT_ERROR_NO_BUFS` | The record name does not fit in the provided `mNameBufferSize` in `aRecordInfo`, or failed to allocate buffer to decompress a compressed DNS name. | |

### otDnsServiceResponseGetHostAddress

```
otError otDnsServiceResponseGetHostAddress(
  const otDnsServiceResponse *aResponse,
  const char *aHostName,
  uint16_t aIndex,
  otIp6Address *aAddress,
  uint32_t *aTtl
)
```
Gets the host IPv6 address from a DNS service instance resolution response.

MUST only be used from `otDnsServiceCallback`.

The response can include zero or more IPv6 address records. `aIndex` can be used to iterate through the list of addresses. Index zero gets the first address and so on. When we reach end of the list, `OT_ERROR_NOT_FOUND` is returned.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[in] aHostName` | The host name to get the address (MUST NOT be NULL). | | `[in] aIndex` | The address record index to retrieve. | | `[out] aAddress` | A pointer to a IPv6 address to output the address (MUST NOT be NULL). | | `[out] aTtl` | A pointer to an `uint32_t` to output TTL for the address. It can be NULL if caller does not want to get the TTL. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The address was read successfully. | | `OT_ERROR_NOT_FOUND` | No address record for `aHostname` in `aResponse` at `aIndex`. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | |

### otDnsServiceResponseGetServiceInfo

```
otError otDnsServiceResponseGetServiceInfo(
  const otDnsServiceResponse *aResponse,
  otDnsServiceInfo *aServiceInfo
)
```
Gets info for a service instance from a DNS service instance resolution response.

MUST only be used from a `otDnsServiceCallback` triggered from `https://openthread.io/reference/group/api-dns#group__api-dns_1ga37875e2aa21b199dc0206099d60540eb` or `https://openthread.io/reference/group/api-dns#group__api-dns_1ga698f8f3418d81760bbcbd39f29773cd9`.

When this is is used from a `https://openthread.io/reference/group/api-dns#group__api-dns_1ga37875e2aa21b199dc0206099d60540eb` callback, the DNS response from server/resolver may include AAAA records in its Additional Data section for the host name associated with the service instance that is resolved. This is a SHOULD and not a MUST requirement so servers/resolvers are not required to provide this. This function attempts to parse AAAA record(s) if included in the response. If it is not included `mHostAddress` is set to all zeros (unspecified address). To also resolve the host address, user can use the DNS client API function `https://openthread.io/reference/group/api-dns#group__api-dns_1ga698f8f3418d81760bbcbd39f29773cd9` which will perform service resolution followed up by a host name address resolution query (when AAAA records are not provided by server/resolver in the SRV query response).


- If a matching SRV record is found in `aResponse`, `aServiceInfo` is updated.
- If no matching SRV record is found, `OT_ERROR_NOT_FOUND` is returned unless the query config for this query used `OT_DNS_SERVICE_MODE_TXT` for `mServiceMode` (meaning the request was only for TXT record). In this case, we still try to parse the SRV record from Additional Data Section of response (in case server provided the info).
- If no matching TXT record is found in `aResponse`, `mTxtDataSize` in `aServiceInfo` is set to zero.
- If TXT data length is greater than `mTxtDataSize`, it is read partially and `mTxtDataTruncated` is set to true.
- If no matching AAAA record is found in `aResponse`, `mHostAddress is set to all zero or unspecified address.`
- `If there are multiple AAAA records for the host name in @p aResponse,`mHostAddress`is set to the first one. The other addresses can be retrieved using`[otDnsServiceResponseGetHostAddress()](https://openthread.io/reference/group/api-dns#group__api-dns_1ga2cdf6f609592da6908188f3f3d6ff198)\`.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[out] aServiceInfo` | A `ServiceInfo` to output the service instance information (MUST NOT be NULL). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The service instance info was read. `aServiceInfo` is updated. | | `OT_ERROR_NOT_FOUND` | Could not find a required record in `aResponse`. | | `OT_ERROR_NO_BUFS` | The host name and/or TXT data could not fit in the given buffers. | | `OT_ERROR_PARSE` | Could not parse the records in the `aResponse`. | |

### otDnsServiceResponseGetServiceName

```
otError otDnsServiceResponseGetServiceName(
  const otDnsServiceResponse *aResponse,
  char *aLabelBuffer,
  uint8_t aLabelBufferSize,
  char *aNameBuffer,
  uint16_t aNameBufferSize
)
```
Gets the service instance name associated with a DNS service instance resolution response.

MUST only be used from `otDnsServiceCallback`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aResponse` | A pointer to the response. | | `[out] aLabelBuffer` | A buffer to char array to output the service instance label (MUST NOT be NULL). | | `[in] aLabelBufferSize` | The size of `aLabelBuffer`. | | `[out] aNameBuffer` | A buffer to char array to output the rest of service name (can be NULL if user is not interested in getting the name. | | `[in] aNameBufferSize` | The size of `aNameBuffer`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The service name was read successfully. | | `OT_ERROR_NO_BUFS` | Either the label or name does not fit in the given buffers. | |

### otDnsSetNameCompressionEnabled

```
otError otDnsSetNameCompressionEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enables/disables the "DNS name compression" mode.

By default, DNS name compression is enabled. When disabled, DNS names are appended in full and are never compressed. This applies to OpenThread's DNS and SRP client/server modules.

DNS name compression cannot be disabled if the OpenThread mDNS module is enabled. Enabling the mDNS module will automatically enable name compression if it was previously disabled. Attempting to disable compression while the mDNS module is active will return `OT_ERROR_NOT_CAPABLE`.

This is intended for testing only and available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` config is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnabled` | TRUE to enable the "DNS name compression" mode, FALSE to disable. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The "DNS name compression" mode is updated. | | `OT_ERROR_NOT_CAPABLE` | The "DNS name compression" mode cannot be disabled since OpenThread mDNS module is enabled. | |

## Macros

### OT_DNS_MAX_LABEL_SIZE

```
 OT_DNS_MAX_LABEL_SIZE 64
```
Maximum label string size (include null char at the end of string).

### OT_DNS_MAX_NAME_SIZE

```
 OT_DNS_MAX_NAME_SIZE 255
```
Maximum name string size (includes null char at the end of string).

### OT_DNS_TXT_KEY_ITER_MAX_LENGTH

```
 OT_DNS_TXT_KEY_ITER_MAX_LENGTH 64
```
Maximum length of TXT key string supported by `https://openthread.io/reference/struct/ot-dns-txt-entry-iterator`.

### OT_DNS_TXT_KEY_MAX_LENGTH

```
 OT_DNS_TXT_KEY_MAX_LENGTH 9
```
Recommended maximum length of TXT record key string (RFC 6763 - section 6.4).

### OT_DNS_TXT_KEY_MIN_LENGTH

```
 OT_DNS_TXT_KEY_MIN_LENGTH 1
```
Minimum length of TXT record key string (RFC 6763 - section 6.4).

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).