This module includes functions that control DNS communication.

Classes
struct	otDnsTxtEntry
	This structure represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3).

struct	otDnsTxtEntryIterator
	This structure represents an iterator for TXT record entires (key/value pairs).

struct	otDnsQueryConfig
	This structure represents a DNS query configuration.

struct	otDnsServiceInfo
	This structure provides info for a DNS service instance.

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

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

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

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

Typedefs
typedef struct otDnsTxtEntry	otDnsTxtEntry
	This structure represents a TXT record entry representing a key/value pair (RFC 6763 - section 6.3).

typedef struct otDnsTxtEntryIterator	otDnsTxtEntryIterator
	This structure represents an iterator for TXT record entires (key/value pairs).

typedef struct otDnsQueryConfig	otDnsQueryConfig
	This structure represents a DNS query configuration.

typedef struct otDnsAddressResponse	otDnsAddressResponse
	This type is an opaque representation of a response to an address resolution DNS query.

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

typedef struct otDnsBrowseResponse	otDnsBrowseResponse
	This type is an opaque representation of a response to a browse (service instance enumeration) DNS query.

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

typedef struct otDnsServiceInfo	otDnsServiceInfo
	This structure provides info for a DNS service instance.

typedef struct otDnsServiceResponse	otDnsServiceResponse
	This type is an opaque representation of a response to a service instance resolution DNS query.

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

Enumerations
enum	otDnsRecursionFlag { OT_DNS_FLAG_UNSPECIFIED = 0, OT_DNS_FLAG_RECURSION_DESIRED = 1, OT_DNS_FLAG_NO_RECURSION = 2 }
	This enumeration type represents the "Recursion Desired" (RD) flag in an `otDnsQueryConfig` .

enum	otDnsNat64Mode { OT_DNS_NAT64_UNSPECIFIED = 0, OT_DNS_NAT64_ALLOW = 1, OT_DNS_NAT64_DISALLOW = 2 }
	This enumeration type represents the NAT64 mode in an `otDnsQueryConfig` .

Functions
void	otDnsInitTxtEntryIterator ( otDnsTxtEntryIterator aIterator, const uint8_t aTxtData, uint16_t aTxtDataLength)
	This function initializes a TXT record iterator.

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

void	otDnsSetNameCompressionEnabled (bool aEnabled)
	This function enables/disables the "DNS name compression" mode.

bool	otDnsIsNameCompressionEnabled (void)
	This function indicates whether the "DNS name compression" mode is enabled or not.

const otDnsQueryConfig *	otDnsClientGetDefaultConfig ( otInstance *aInstance)
	This function gets the current default query config used by DNS client.

void	otDnsClientSetDefaultConfig ( otInstance aInstance, const otDnsQueryConfig aConfig)
	This function sets the default query config on DNS client.

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

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

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

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

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

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

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

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

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

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

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

otError	otDnsServiceResponseGetServiceInfo (const otDnsServiceResponse aResponse, otDnsServiceInfo aServiceInfo)
	This function gets info for a service instance from a DNS service instance resolution response.

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

Detailed Description

This module includes functions that control DNS communication.

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

Typedef Documentation

◆ otDnsAddressCallback

typedef void(* otDnsAddressCallback) ( otError aError, const otDnsAddressResponse *aResponse, void *aContext)

This function 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.

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.

The aError can have the following:

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.

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

◆ otDnsAddressResponse

typedef struct otDnsAddressResponse otDnsAddressResponse

This type is an opaque representation of a response to an address resolution DNS query.

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

◆ otDnsBrowseCallback

typedef void(* otDnsBrowseCallback) ( otError aError, const otDnsBrowseResponse *aResponse, void *aContext)

This function 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.

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.

For the full list of possible values for aError , please see otDnsAddressCallback() .

◆ otDnsBrowseResponse

typedef struct otDnsBrowseResponse otDnsBrowseResponse

This type is 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

typedef struct otDnsQueryConfig otDnsQueryConfig

This structure 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 otDnsQueryConfig .

◆ otDnsServiceCallback

typedef void(* otDnsServiceCallback) ( otError aError, const otDnsServiceResponse *aResponse, void *aContext)

This function 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.

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.

For the full list of possible values for aError , please see otDnsAddressCallback() .

◆ otDnsServiceResponse

typedef struct otDnsServiceResponse otDnsServiceResponse

This type is 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

typedef struct otDnsTxtEntry otDnsTxtEntry

This structure 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 otSrpClientService instance).

An array of otDnsTxtEntry entries are used in otSrpClientService to specify the full TXT record (a list of entries).

◆ otDnsTxtEntryIterator

typedef struct otDnsTxtEntryIterator otDnsTxtEntryIterator

This structure represents an iterator for TXT record entires (key/value pairs).

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

Enumeration Type Documentation

◆ otDnsNat64Mode

enum otDnsNat64Mode

This enumeration type represents the NAT64 mode in an otDnsQueryConfig .

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.

Enumerator
OT_DNS_NAT64_UNSPECIFIED	NAT64 mode is not specified. Use default NAT64 mode.
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.

◆ otDnsRecursionFlag

enum otDnsRecursionFlag

This enumeration type represents the "Recursion Desired" (RD) flag in an otDnsQueryConfig .

Enumerator
OT_DNS_FLAG_UNSPECIFIED	Indicates the flag is not specified.
OT_DNS_FLAG_RECURSION_DESIRED	Indicates DNS name server can resolve the query recursively.
OT_DNS_FLAG_NO_RECURSION	Indicates DNS name server can not resolve the query recursively.

Function Documentation

◆ otDnsAddressResponseGetAddress()

otError otDnsAddressResponseGetAddress	(	const otDnsAddressResponse *	`aResponse,`
		uint16_t	`aIndex,`
		otIp6Address *	`aAddress,`
		uint32_t *	`aTtl`
	)

This function gets an IPv6 address associated with an address resolution DNS response.

This function 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.

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`
	)

This function gets the full host name associated with an address resolution DNS response.

This function MUST only be used from otDnsAddressCallback .

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`
	)

This function gets the host IPv6 address from a DNS browse (service instance enumeration) response.

This function 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.

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`
	)

This function gets info for a service instance from a DNS browse (service instance enumeration) response.

This function MUST only be used from otDnsBrowseCallback .

A browse DNS response should include the SRV, TXT, and AAAA records for the service instances that are enumerated (note that it is a SHOULD and not a MUST requirement). This function tries 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.
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 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() `.

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`
	)

This function gets a service instance associated with a DNS browse (service instance enumeration) response.

This function 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 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 <Instance>.<Service>.<Domain> .

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`
	)

This function gets the service name associated with a DNS browse (service instance enumeration) response.

This function MUST only be used from otDnsBrowseCallback .

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`
	)

This function sends a DNS browse (service instance enumeration) query for a given service name.

This function is available when OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE is enabled.

The aConfig can be NULL. In this case the default config (from otDnsClientGetDefaultConfig() ) 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.

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 )

This function 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).

Parameters

[in] aInstance A pointer to an OpenThread instance.

Returns: A pointer to the current default config being used by DNS client.

◆ otDnsClientResolveAddress()

otError otDnsClientResolveAddress	(	otInstance *	`aInstance,`
		const char *	`aHostName,`
		otDnsAddressCallback	`aCallback,`
		void *	`aContext,`
		const otDnsQueryConfig *	`aConfig`
	)

This function 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 otDnsClientGetDefaultConfig() ) 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.

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`
	)

This function sends an address resolution DNS query for A (IPv4) record(s) for a given host name.

This function 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 otDnsClientGetDefaultConfig() ) 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.

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`
	)

This function sends a DNS service instance resolution query for a given service instance.

This function is available when OPENTHREAD_CONFIG_DNS_CLIENT_SERVICE_DISCOVERY_ENABLE is enabled.

The aConfig can be NULL. In this case the default config (from otDnsClientGetDefaultConfig() ) 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.

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.

◆ otDnsClientSetDefaultConfig()

void otDnsClientSetDefaultConfig	(	otInstance *	`aInstance,`
		const otDnsQueryConfig *	`aConfig`
	)

This function sets the default query config on DNS client.

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.

In a non-NULL aConfig , caller can choose to leave some of the fields in otDnsQueryConfig 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.

Parameters

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

◆ otDnsGetNextTxtEntry()

otError otDnsGetNextTxtEntry	(	otDnsTxtEntryIterator *	`aIterator,`
		otDnsTxtEntry *	`aEntry`
	)

This function parses the TXT data from an iterator and gets the next TXT record entry (key/value pair).

The aIterator MUST be initialized using otDnsInitTxtEntryIterator() 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_MAX_LENGTH (recommended max key 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 .

Parameters

[in]	`aIterator`	A pointer to the iterator (MUST NOT be NULL).
[out]	`aEntry`	A pointer to a `otDnsTxtEntry` 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`
	)

This function initializes a TXT record iterator.

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

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 ( void )

This function 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.

Returns: TRUE if the "DNS name compression" mode is enabled, FALSE otherwise.

◆ otDnsServiceResponseGetHostAddress()

otError otDnsServiceResponseGetHostAddress	(	const otDnsServiceResponse *	`aResponse,`
		const char *	`aHostName,`
		uint16_t	`aIndex,`
		otIp6Address *	`aAddress,`
		uint32_t *	`aTtl`
	)

This function gets the host IPv6 address from a DNS service instance resolution response.

This function 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.

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`
	)

This function gets info for a service instance from a DNS service instance resolution response.

This function MUST only be used from otDnsServiceCallback .

If no matching SRV record is found in aResponse , OT_ERROR_NOT_FOUND is returned.
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 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() `.

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 matching SRV 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`
	)

This function gets the service instance name associated with a DNS service instance resolution response.

This function MUST only be used from otDnsServiceCallback .

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()

void otDnsSetNameCompressionEnabled ( bool aEnabled )

This function enables/disables the "DNS name compression" mode.

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

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

Note that in the case OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE is used, this mode applies to all OpenThread instances (i.e., calling this function enables/disables the compression mode on all OpenThread instances).

Parameters

[in] aEnabled TRUE to enable the "DNS name compression" mode, FALSE to disable.

DNSv6 API > IPv6 Networking

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ otDnsAddressCallback

◆ otDnsAddressResponse

◆ otDnsBrowseCallback

◆ otDnsBrowseResponse

◆ otDnsQueryConfig

◆ otDnsServiceCallback

◆ otDnsServiceResponse

◆ otDnsTxtEntry

◆ otDnsTxtEntryIterator

Enumeration Type Documentation

◆ otDnsNat64Mode

◆ otDnsRecursionFlag

Function Documentation

◆ otDnsAddressResponseGetAddress()

◆ otDnsAddressResponseGetHostName()

◆ otDnsBrowseResponseGetHostAddress()

◆ otDnsBrowseResponseGetServiceInfo()

◆ otDnsBrowseResponseGetServiceInstance()

◆ otDnsBrowseResponseGetServiceName()

◆ otDnsClientBrowse()

◆ otDnsClientGetDefaultConfig()

◆ otDnsClientResolveAddress()

◆ otDnsClientResolveIp4Address()

◆ otDnsClientResolveService()

◆ otDnsClientSetDefaultConfig()

◆ otDnsGetNextTxtEntry()

◆ otDnsInitTxtEntryIterator()

◆ otDnsIsNameCompressionEnabled()

◆ otDnsServiceResponseGetHostAddress()

◆ otDnsServiceResponseGetServiceInfo()

◆ otDnsServiceResponseGetServiceName()

◆ otDnsSetNameCompressionEnabled()

DNSv6
API > IPv6 Networking