# DNS - Platform

# DNS - Platform

This module includes the platform abstraction for sending recursive DNS query to upstream DNS servers.

## Summary

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga424b6f2548bf7c6d377fa7a83c05b800` | typedef `struct https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga424b6f2548bf7c6d377fa7a83c05b800` This opaque type represents an upstream DNS query transaction. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/plat-dns#group__plat-dns_1gae8c7f3b418904b043b4f90fc6e552a96(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga424b6f2548bf7c6d377fa7a83c05b800 *aTxn)` | `void` Cancels a transaction of upstream query. |
| `https://openthread.io/reference/group/plat-dns#group__plat-dns_1gaa180538884e72b34753ec59552fb9ee4(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether upstream DNS query functionality is available on the platform. |
| `https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga160d8a7f5cce6e73eb7b63ce7c0ab218(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga424b6f2548bf7c6d377fa7a83c05b800 *aTxn, const https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aQuery)` | `void` Starts an upstream query transaction. |
| `https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga4e37db1b19421e8793104f0dbaffb119(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga424b6f2548bf7c6d377fa7a83c05b800 *aTxn, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aResponse)` | `void` The platform calls this function to finish DNS query. |

## Typedefs

### otPlatDnsUpstreamQuery

```
struct otPlatDnsUpstreamQuery otPlatDnsUpstreamQuery
```
This opaque type represents an upstream DNS query transaction.

## Functions

### otPlatDnsCancelUpstreamQuery

```
void otPlatDnsCancelUpstreamQuery(
  otInstance *aInstance,
  otPlatDnsUpstreamQuery *aTxn
)
```
Cancels a transaction of upstream query.

The platform MUST call `https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga4e37db1b19421e8793104f0dbaffb119` to release the transaction.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aTxn` | A pointer to the opaque DNS query transaction object. | |

### otPlatDnsIsUpstreamQueryAvailable

```
bool otPlatDnsIsUpstreamQueryAvailable(
  otInstance *aInstance
)
```
Indicates whether upstream DNS query functionality is available on the platform.

This function allows the platform to inform the OpenThread stack if no upstream DNS server is available.

This function is used to optimize query handling. If this function returns `false` (e.g., no upstream DNS server is currently available), one can avoid attempting an upstream resolution (which would likely time out) and instead immediately send an appropriate negative response (e.g., `SERVFAIL`) to the DNS client.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | Upstream DNS query functionality is available. | | `FALSE` | Upstream DNS query functionality is not available. | |

### otPlatDnsStartUpstreamQuery

```
void otPlatDnsStartUpstreamQuery(
  otInstance *aInstance,
  otPlatDnsUpstreamQuery *aTxn,
  const otMessage *aQuery
)
```
Starts an upstream query transaction.


- In success case (and errors represented by DNS protocol messages), the platform is expected to call `otPlatDnsUpstreamQueryDone`.
- The OpenThread core may cancel a query transaction (possibly due to a timeout) by invoking `https://openthread.io/reference/group/plat-dns#group__plat-dns_1gae8c7f3b418904b043b4f90fc6e552a96`. The platform MUST still call `https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga4e37db1b19421e8793104f0dbaffb119` on a cancelled transaction to release the transaction.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aTxn` | A pointer to the opaque DNS query transaction object. | | `[in] aQuery` | A message buffer of the DNS payload that should be sent to upstream DNS server. | |

### otPlatDnsUpstreamQueryDone

```
void otPlatDnsUpstreamQueryDone(
  otInstance *aInstance,
  otPlatDnsUpstreamQuery *aTxn,
  otMessage *aResponse
)
```
The platform calls this function to finish DNS query.

The transaction will be released, so the platform MUST NOT call on the same transaction twice. This function passes the ownership of `aResponse` to OpenThread stack.

Platform can pass NULL to close a transaction without a response.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aTxn` | A pointer to the opaque DNS query transaction object. | | `[in] aResponse` | A message buffer of the DNS response payload or NULL to close a transaction without a response. | |

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