# DNS-SD Server

# DNS-SD Server

This module includes APIs for DNS-SD server.

## Summary

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga27249f2a7771ee0c010af0537e8f4d1e{ https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gga27249f2a7771ee0c010af0537e8f4d1ea9a28fba3e4fdcef8c6c6fb5773136a17 = 0, https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gga27249f2a7771ee0c010af0537e8f4d1eaca35c79b1e1b0f6a96b0a7e4b4c27494 = 1, https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gga27249f2a7771ee0c010af0537e8f4d1ea89193433985bbd00cefdd6266a63dba1 = 2, https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gga27249f2a7771ee0c010af0537e8f4d1ea5cdf4feb4fbbbb6193538336a79bfec2 = 3 }` | enumSpecifies a DNS-SD query type. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga9c430e887aeac25852301f514197721f` | typedef `struct https://openthread.io/reference/struct/ot-dnssd-counters` Contains the counters of DNS-SD server. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga3b012ee753bae5d87b0ed1799bf5d756` | typedef `struct https://openthread.io/reference/struct/ot-dnssd-host-info` Represents information of a discovered host for a DNS-SD query. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gaf85fe50b588f4ac491da4a264e5bf515` | typedef `void` This opaque type represents a DNS-SD query. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gab399f1e5449e3525d01fc8ebabbdfec6)(void *aContext, const char *aFullName)` | typedef `void(*` Is called when a DNS-SD query subscribes one of: |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga18ef6990cdd72ac58e3eb6ff57027897)(void *aContext, const char *aFullName)` | typedef `void(*` Is called when a DNS-SD query unsubscribes one of: |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga879b8bc7f9d20383a23314e7a1e2688f` | typedef `struct https://openthread.io/reference/struct/ot-dnssd-service-instance-info` Represents information of a discovered service instance for a DNS-SD query. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gabecfc24964972551795ae625e7292d4b` | typedef `struct https://openthread.io/reference/struct/ot-upstream-dns-counters` Represents the count of queries, responses, failures handled by upstream DNS server. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga154cafc3e8e86dd3cd3e9b9287ddb892(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `const https://openthread.io/reference/struct/ot-dnssd-counters *` Returns the counters of the DNS-SD server. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga3cf723e8fb6469d40ce91e820bde26d2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gaf85fe50b588f4ac491da4a264e5bf515 *aQuery)` | `const https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gaf85fe50b588f4ac491da4a264e5bf515 *` Acquires the next query in the DNS-SD server. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gad42b87fb9171b882b7a0b2bcb71e4436(const https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gaf85fe50b588f4ac491da4a264e5bf515 *aQuery, char(*) aNameOutput[OT_DNS_MAX_NAME_SIZE])` | `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga27249f2a7771ee0c010af0537e8f4d1e` Acquires the DNS-SD query type and name for a specific query. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga06d89eca883094055e282e8ccd29a6f0(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aHostFullName, https://openthread.io/reference/struct/ot-dnssd-host-info *aHostInfo)` | `void` Notifies a discovered host. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga464ed59caf149facc56ed2649aca15c6(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aServiceFullName, https://openthread.io/reference/struct/ot-dnssd-service-instance-info *aInstanceInfo)` | `void` Notifies a discovered service instance. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga415476e0d8cfd20d8396becb83721d28(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gab399f1e5449e3525d01fc8ebabbdfec6 aSubscribe, https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga18ef6990cdd72ac58e3eb6ff57027897 aUnsubscribe, void *aContext)` | `void` Sets DNS-SD server query callbacks. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1gaacca195fb044e2443f23229f5d2cbdfe(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Returns whether the DNSSD server will forward DNS queries to the platform DNS upstream API. |
| `https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga5a9d9aeda2b96da7adceb37bdef6b0ab(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `void` Enable or disable forwarding DNS queries to platform DNS upstream API. |

| ### Structs ||
|---|---|
| [otDnssdCounters](https://openthread.io/reference/struct/ot-dnssd-counters) | Contains the counters of DNS-SD server. |
| [otDnssdHostInfo](https://openthread.io/reference/struct/ot-dnssd-host-info) | Represents information of a discovered host for a DNS-SD query. |
| [otDnssdServiceInstanceInfo](https://openthread.io/reference/struct/ot-dnssd-service-instance-info) | Represents information of a discovered service instance for a DNS-SD query. |
| [otUpstreamDnsCounters](https://openthread.io/reference/struct/ot-upstream-dns-counters) | Represents the count of queries, responses, failures handled by upstream DNS server. |

## Enumerations

### otDnssdQueryType

```
 otDnssdQueryType
```
Specifies a DNS-SD query type.

| Properties ||
|---|---|
| `OT_DNSSD_QUERY_TYPE_BROWSE` | Service type browse service. |
| `OT_DNSSD_QUERY_TYPE_NONE` | Service type unspecified. |
| `OT_DNSSD_QUERY_TYPE_RESOLVE` | Service type resolve service instance. |
| `OT_DNSSD_QUERY_TYPE_RESOLVE_HOST` | Service type resolve hostname. |

## Typedefs

### otDnssdCounters

```
struct otDnssdCounters otDnssdCounters
```
Contains the counters of DNS-SD server.

### otDnssdHostInfo

```
struct otDnssdHostInfo otDnssdHostInfo
```
Represents information of a discovered host for a DNS-SD query.

### otDnssdQuery

```
void otDnssdQuery
```
This opaque type represents a DNS-SD query.

### otDnssdQuerySubscribeCallback

```
void(* otDnssdQuerySubscribeCallback)(void *aContext, const char *aFullName)
```
Is called when a DNS-SD query subscribes one of:


1. a service name.
2. a service instance name.
3. a host name.

<br />

The DNS-SD query implementation is responsible for identifying what `aFullName` is. If `aFullName` is a service name or service instance name, the DNS-SD query implementation should discover corresponding service instance information and notify the DNS-SD server using `otDnssdQueryHandleDiscoveredServiceInstance`. If `aFullName` is a host name, the DNS-SD query implementation should discover the host information and notify the DNS-SD server using `otDnssdQueryHandleDiscoveredHost`.


> [!NOTE]
> **Note:** There can be multiple subscription to the same name. DNS-SD query implementation should record the number of active subscriptions and stop notifying when there is no active subscription for `aFullName`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to the application-specific context. | | `[in] aFullName` | The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."), or full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."), or full host name (e.g. "ot-host.default.service.arpa."). | |

**See also:**   
[otDnssdQueryHandleDiscoveredServiceInstance](https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga464ed59caf149facc56ed2649aca15c6)   
[otDnssdQueryHandleDiscoveredHost](https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga06d89eca883094055e282e8ccd29a6f0)   

### otDnssdQueryUnsubscribeCallback

```
void(* otDnssdQueryUnsubscribeCallback)(void *aContext, const char *aFullName)
```
Is called when a DNS-SD query unsubscribes one of:


1. a service name.
2. a service instance name.
3. a host name.

<br />

The DNS-SD query implementation is responsible for identifying what `aFullName` is.


> [!NOTE]
> **Note:** There can be multiple subscription to the same name. DNS-SD query implementation should record the number of active subscriptions and stop notifying when there is no active subscription for `aFullName`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to the application-specific context. | | `[in] aFullName` | The null-terminated full service name (e.g. "_ipps._tcp.default.service.arpa."), or full service instance name (e.g. "OpenThread._ipps._tcp.default.service.arpa."). | |

### otDnssdServiceInstanceInfo

```
struct otDnssdServiceInstanceInfo otDnssdServiceInstanceInfo
```
Represents information of a discovered service instance for a DNS-SD query.

### otUpstreamDnsCounters

```
struct otUpstreamDnsCounters otUpstreamDnsCounters
```
Represents the count of queries, responses, failures handled by upstream DNS server.

Requires `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE`.

## Functions

### otDnssdGetCounters

```
const otDnssdCounters * otDnssdGetCounters(
  otInstance *aInstance
)
```
Returns the counters of the DNS-SD server.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | |
| **Returns** | A pointer to the counters of the DNS-SD server. |

### otDnssdGetNextQuery

```
const otDnssdQuery * otDnssdGetNextQuery(
  otInstance *aInstance,
  const otDnssdQuery *aQuery
)
```
Acquires the next query in the DNS-SD server.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aQuery` | The query pointer. Pass NULL to get the first query. | |
| **Returns** | A pointer to the query or NULL if no more queries. |

### otDnssdGetQueryTypeAndName

```
otDnssdQueryType otDnssdGetQueryTypeAndName(
  const otDnssdQuery *aQuery,
  char(*) aNameOutput[OT_DNS_MAX_NAME_SIZE]
)
```
Acquires the DNS-SD query type and name for a specific query.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aQuery` | The query pointer acquired from `otDnssdGetNextQuery`. | | `[out] aNameOutput` | The name output buffer, which should be `OT_DNS_MAX_NAME_SIZE` bytes long. | |
| **Returns** | The DNS-SD query type. |

### otDnssdQueryHandleDiscoveredHost

```
void otDnssdQueryHandleDiscoveredHost(
  otInstance *aInstance,
  const char *aHostFullName,
  otDnssdHostInfo *aHostInfo
)
```
Notifies a discovered host.

The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the subscribed hosts.


> [!NOTE]
> **Note:** `aHostInfo` must not contain unspecified or link-local or loop-back or multicast IP addresses.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aHostFullName` | The null-terminated full host name. | | `[in] aHostInfo` | A pointer to the discovered service instance information. | |

### otDnssdQueryHandleDiscoveredServiceInstance

```
void otDnssdQueryHandleDiscoveredServiceInstance(
  otInstance *aInstance,
  const char *aServiceFullName,
  otDnssdServiceInstanceInfo *aInstanceInfo
)
```
Notifies a discovered service instance.

The external query resolver (e.g. Discovery Proxy) should call this function to notify OpenThread core of the subscribed services or service instances.


> [!NOTE]
> **Note:** `aInstanceInfo` must not contain unspecified or link-local or loop-back or multicast IP addresses.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aServiceFullName` | The null-terminated full service name. | | `[in] aInstanceInfo` | A pointer to the discovered service instance information. | |

### otDnssdQuerySetCallbacks

```
void otDnssdQuerySetCallbacks(
  otInstance *aInstance,
  otDnssdQuerySubscribeCallback aSubscribe,
  otDnssdQueryUnsubscribeCallback aUnsubscribe,
  void *aContext
)
```
Sets DNS-SD server query callbacks.

The DNS-SD server calls `aSubscribe` to subscribe to a service or service instance to resolve a DNS-SD query and `aUnsubscribe` to unsubscribe when the query is resolved or timeout.


> [!NOTE]
> **Note:** `aSubscribe` and `aUnsubscribe` must be both set or unset.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aSubscribe` | A pointer to the callback function to subscribe a service or service instance. | | `[in] aUnsubscribe` | A pointer to the callback function to unsubscribe a service or service instance. | | `[in] aContext` | A pointer to the application-specific context. | |

### otDnssdUpstreamQueryIsEnabled

```
bool otDnssdUpstreamQueryIsEnabled(
  otInstance *aInstance
)
```
Returns whether the DNSSD server will forward DNS queries to the platform DNS upstream API.

Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | If the DNSSD server will forward DNS queries. | | `FALSE` | If the DNSSD server will not forward DNS queries. | |

**See also:**   
[otDnssdUpstreamQuerySetEnabled](https://openthread.io/reference/group/api-dnssd-server#group__api-dnssd-server_1ga5a9d9aeda2b96da7adceb37bdef6b0ab)   

### otDnssdUpstreamQuerySetEnabled

```
void otDnssdUpstreamQuerySetEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enable or disable forwarding DNS queries to platform DNS upstream API.

Available when `OPENTHREAD_CONFIG_DNS_UPSTREAM_QUERY_ENABLE` is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aEnabled` | A boolean to enable/disable forwarding DNS queries to upstream. | |

**See also:**   
[otPlatDnsStartUpstreamQuery](https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga160d8a7f5cce6e73eb7b63ce7c0ab218)   
[otPlatDnsCancelUpstreamQuery](https://openthread.io/reference/group/plat-dns#group__plat-dns_1gae8c7f3b418904b043b4f90fc6e552a96)   
[otPlatDnsUpstreamQueryDone](https://openthread.io/reference/group/plat-dns#group__plat-dns_1ga4e37db1b19421e8793104f0dbaffb119)   

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