DNS#

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.

Modules#

otDnsTxtEntry

otDnsTxtEntryIterator

otDnsQueryConfig

otDnsServiceInfo

Enumerations#

enum
OT_DNS_FLAG_UNSPECIFIED = 0
OT_DNS_FLAG_RECURSION_DESIRED = 1
OT_DNS_FLAG_NO_RECURSION = 2
}

Type represents the "Recursion Desired" (RD) flag in an otDnsQueryConfig.

enum
OT_DNS_NAT64_UNSPECIFIED = 0
OT_DNS_NAT64_ALLOW = 1
OT_DNS_NAT64_DISALLOW = 2
}

Type represents the NAT64 mode in an otDnsQueryConfig.

enum
OT_DNS_SERVICE_MODE_UNSPECIFIED = 0
OT_DNS_SERVICE_MODE_SRV = 1
OT_DNS_SERVICE_MODE_TXT = 2
OT_DNS_SERVICE_MODE_SRV_TXT = 3
OT_DNS_SERVICE_MODE_SRV_TXT_SEPARATE = 4
OT_DNS_SERVICE_MODE_SRV_TXT_OPTIMIZE = 5
}

Type represents the service resolution mode in an otDnsQueryConfig.

enum
OT_DNS_TRANSPORT_UNSPECIFIED = 0
OT_DNS_TRANSPORT_UDP = 1
OT_DNS_TRANSPORT_TCP = 2
}

Type represents the DNS transport protocol in an otDnsQueryConfig.

Typedefs#

typedef struct otDnsTxtEntry

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

typedef struct otDnsTxtEntryIterator

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

typedef struct otDnsQueryConfig

Represents a DNS query configuration.

typedef struct otDnsAddressResponse

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

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

Pointer is called when a DNS response is received for an address resolution query.

typedef struct otDnsBrowseResponse

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

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

typedef struct otDnsServiceInfo

Provides info for a DNS service instance.

typedef struct otDnsServiceResponse

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

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

Pointer is called when a DNS response is received for a service instance resolution query.

Functions#

void
otDnsInitTxtEntryIterator(otDnsTxtEntryIterator *aIterator, const uint8_t *aTxtData, uint16_t aTxtDataLength)

Initializes a TXT record iterator.

otDnsGetNextTxtEntry(otDnsTxtEntryIterator *aIterator, otDnsTxtEntry *aEntry)

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

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

void

Enables/disables the "DNS name compression" mode.

bool

Indicates whether the "DNS name compression" mode is enabled or not.

otDnsClientGetDefaultConfig(otInstance *aInstance)

Gets the current default query config used by DNS client.

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

Sets the default query config on DNS client.

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.

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.

otDnsAddressResponseGetHostName(const otDnsAddressResponse *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)

Gets the full host name associated with an address resolution DNS response.

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

Gets an IPv6 address associated with an address resolution DNS response.

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.

otDnsBrowseResponseGetServiceName(const otDnsBrowseResponse *aResponse, char *aNameBuffer, uint16_t aNameBufferSize)

Gets the service name associated with a DNS browse (service instance enumeration) response.

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.

otDnsBrowseResponseGetServiceInfo(const otDnsBrowseResponse *aResponse, const char *aInstanceLabel, otDnsServiceInfo *aServiceInfo)

Gets info for a service instance from a DNS browse (service instance enumeration) response.

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.

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.

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.

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.

otDnsServiceResponseGetServiceInfo(const otDnsServiceResponse *aResponse, otDnsServiceInfo *aServiceInfo)

Gets info for a service instance from a DNS service instance resolution response.

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.

Macros#

#define

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

#define

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

#define

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

#define

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

#define

Maximum length of TXT key string supported by otDnsTxtEntryIterator.

Enumeration Documentation#

otDnsRecursionFlag#

otDnsRecursionFlag

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.


Definition at line 62 of file include/openthread/dns_client.h

otDnsNat64Mode#

otDnsNat64Mode

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.


Definition at line 76 of file include/openthread/dns_client.h

otDnsServiceMode#

otDnsServiceMode

Type represents the service resolution mode in an otDnsQueryConfig.

This is only used during DNS client service resolution otDnsClientResolveService(). It determines which record types to query.

Enumerator
OT_DNS_SERVICE_MODE_UNSPECIFIED

Mode is not specified. Use default service mode.

OT_DNS_SERVICE_MODE_SRV

Query for SRV record only.

OT_DNS_SERVICE_MODE_TXT

Query for TXT record only.

OT_DNS_SERVICE_MODE_SRV_TXT

Query for both SRV and TXT records in same message.

OT_DNS_SERVICE_MODE_SRV_TXT_SEPARATE

Query in parallel for SRV and TXT using separate messages.

OT_DNS_SERVICE_MODE_SRV_TXT_OPTIMIZE

Query for TXT/SRV together first, if fails then query separately.


Definition at line 90 of file include/openthread/dns_client.h

otDnsTransportProto#

otDnsTransportProto

Type represents the DNS transport protocol in an otDnsQueryConfig.

This OT_DNS_TRANSPORT_TCP is only supported when OPENTHREAD_CONFIG_DNS_CLIENT_OVER_TCP_ENABLE is enabled.

Enumerator
OT_DNS_TRANSPORT_UNSPECIFIED
OT_DNS_TRANSPORT_UDP

DNS transport is unspecified.

OT_DNS_TRANSPORT_TCP

DNS query should be sent via UDP.


Definition at line 106 of file include/openthread/dns_client.h

Typedef Documentation#

otDnsTxtEntry#

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

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


Definition at line 97 of file include/openthread/dns.h

otDnsTxtEntryIterator#

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


Definition at line 110 of file include/openthread/dns.h

otDnsQueryConfig#

typedef 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 otDnsQueryConfig.


Definition at line 129 of file include/openthread/dns_client.h

otDnsAddressResponse#

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


Definition at line 177 of file include/openthread/dns_client.h

otDnsAddressCallback#

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

Pointer is called when a DNS response is received for an address resolution query.

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.

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:

  • 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


Definition at line 217 of file include/openthread/dns_client.h

otDnsBrowseResponse#

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


Definition at line 323 of file include/openthread/dns_client.h

otDnsBrowseCallback#

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

Pointer is called when a DNS response is received for a browse (service instance enumeration) query.

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.

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


Definition at line 341 of file include/openthread/dns_client.h

otDnsServiceInfo#

typedef struct otDnsServiceInfo otDnsServiceInfo

Provides info for a DNS service instance.


Definition at line 361 of file include/openthread/dns_client.h

otDnsServiceResponse#

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


Definition at line 497 of file include/openthread/dns_client.h

otDnsServiceCallback#

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

Pointer is called when a DNS response is received for a service instance resolution query.

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.

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


Definition at line 515 of file include/openthread/dns_client.h

Function Documentation#

otDnsInitTxtEntryIterator#

void otDnsInitTxtEntryIterator (otDnsTxtEntryIterator * aIterator, const uint8_t * aTxtData, uint16_t aTxtDataLength)

Initializes a TXT record iterator.

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.

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


Definition at line 123 of file include/openthread/dns.h

otDnsGetNextTxtEntry#

otError otDnsGetNextTxtEntry (otDnsTxtEntryIterator * aIterator, otDnsTxtEntry * aEntry)

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

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

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


Definition at line 144 of file include/openthread/dns.h

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

Parameters
[in]aTxtEntries

Pointer to an array of otDnsTxtEntry.

[in]aNumTxtEntries

Number of entries in aTxtEntries array.

[out]aTxtData

A pointer to a buffer to output the encoded TXT data.

[inout]aTxtDataLength

On input, size of buffer aTxtData. On output, length of the encoded TXT data.


Definition at line 159 of file include/openthread/dns.h

otDnsSetNameCompressionEnabled#

void otDnsSetNameCompressionEnabled (bool aEnabled)

Enables/disables the "DNS name compression" mode.

Parameters
[in]aEnabled

TRUE to enable the "DNS name compression" mode, FALSE to disable.

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


Definition at line 178 of file include/openthread/dns.h

otDnsIsNameCompressionEnabled#

bool otDnsIsNameCompressionEnabled (void )

Indicates whether the "DNS name compression" mode is enabled or not.

Parameters
N/A

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.


Definition at line 188 of file include/openthread/dns.h

otDnsClientGetDefaultConfig#

const otDnsQueryConfig * otDnsClientGetDefaultConfig (otInstance * aInstance)

Gets the current default query config used by DNS client.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

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

Returns

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


Definition at line 143 of file include/openthread/dns_client.h

otDnsClientSetDefaultConfig#

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

Sets the default query config on DNS client.

Parameters
[in]aInstance

A pointer to an OpenThread instance.

[in]aConfig

A pointer to the new query config to use as default.

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.


Definition at line 169 of file include/openthread/dns_client.h

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.

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.

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.


Definition at line 238 of file include/openthread/dns_client.h

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.

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.

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.


Definition at line 268 of file include/openthread/dns_client.h

otDnsAddressResponseGetHostName#

otError otDnsAddressResponseGetHostName (const otDnsAddressResponse * aResponse, char * aNameBuffer, uint16_t aNameBufferSize)

Gets the full host name associated with an address resolution DNS response.

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.

MUST only be used from otDnsAddressCallback.


Definition at line 287 of file include/openthread/dns_client.h

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.

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.

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.


Definition at line 312 of file include/openthread/dns_client.h

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.

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.

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.


Definition at line 382 of file include/openthread/dns_client.h

otDnsBrowseResponseGetServiceName#

otError otDnsBrowseResponseGetServiceName (const otDnsBrowseResponse * aResponse, char * aNameBuffer, uint16_t aNameBufferSize)

Gets the service name associated with a DNS browse (service instance enumeration) response.

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.

MUST only be used from otDnsBrowseCallback.


Definition at line 401 of file include/openthread/dns_client.h

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.

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.

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


Definition at line 427 of file include/openthread/dns_client.h

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.

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

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,mHostAddressis set to the first one. The other addresses can be retrieved usingotDnsBrowseResponseGetHostAddress()`.


Definition at line 460 of file include/openthread/dns_client.h

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.

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.

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.


Definition at line 485 of file include/openthread/dns_client.h

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.

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.

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.

The function sends queries for SRV and/or TXT records for the given service instance. The mServiceMode field in otDnsQueryConfig 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 otDnsServiceResponseGetServiceInfo() in otDnsServiceCallback. Users of this API MUST NOT assume that host address will always be available from otDnsServiceResponseGetServiceInfo().


Definition at line 550 of file include/openthread/dns_client.h

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.

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.

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


Definition at line 587 of file include/openthread/dns_client.h

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.

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.

MUST only be used from otDnsServiceCallback.


Definition at line 610 of file include/openthread/dns_client.h

otDnsServiceResponseGetServiceInfo#

otError otDnsServiceResponseGetServiceInfo (const otDnsServiceResponse * aResponse, otDnsServiceInfo * aServiceInfo)

Gets info for a service instance from a DNS service instance resolution response.

Parameters
[in]aResponse

A pointer to the response.

[out]aServiceInfo

A ServiceInfo to output the service instance information (MUST NOT be NULL).

MUST only be used from a otDnsServiceCallback triggered from otDnsClientResolveService() or otDnsClientResolveServiceAndHostAddress().

When this is is used from a otDnsClientResolveService() 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 otDnsClientResolveServiceAndHostAddress() 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,mHostAddressis set to the first one. The other addresses can be retrieved usingotDnsServiceResponseGetHostAddress()`.


Definition at line 649 of file include/openthread/dns_client.h

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.

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.

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.


Definition at line 672 of file include/openthread/dns_client.h

Macro Definition Documentation#

OT_DNS_MAX_NAME_SIZE#

#define OT_DNS_MAX_NAME_SIZE
Value:
255

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


Definition at line 57 of file include/openthread/dns.h

OT_DNS_MAX_LABEL_SIZE#

#define OT_DNS_MAX_LABEL_SIZE
Value:
64

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


Definition at line 59 of file include/openthread/dns.h

OT_DNS_TXT_KEY_MIN_LENGTH#

#define OT_DNS_TXT_KEY_MIN_LENGTH
Value:
1

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


Definition at line 61 of file include/openthread/dns.h

OT_DNS_TXT_KEY_MAX_LENGTH#

#define OT_DNS_TXT_KEY_MAX_LENGTH
Value:
9

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


Definition at line 63 of file include/openthread/dns.h

OT_DNS_TXT_KEY_ITER_MAX_LENGTH#

#define OT_DNS_TXT_KEY_ITER_MAX_LENGTH
Value:
64

Maximum length of TXT key string supported by otDnsTxtEntryIterator.


Definition at line 65 of file include/openthread/dns.h