DNS#

otDnsRecursionFlag#

otDnsRecursionFlag

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

otDnsNat64Mode#

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.

otDnsServiceMode#

otDnsServiceMode

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

otDnsTransportProto#

otDnsTransportProto

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

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.

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.

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.

otDnsAddressCallback#

typedef void(* otDnsAddressCallback) (otError aError, const otDnsAddressResponse *aResponse, void *aContext) )(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.

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

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.

otDnsBrowseCallback#

typedef void(* otDnsBrowseCallback) (otError aError, const otDnsBrowseResponse *aResponse, void *aContext) )(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.

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

otDnsServiceInfo#

typedef struct otDnsServiceInfo otDnsServiceInfo

This structure provides info for a DNS service instance.

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.

otDnsServiceCallback#

typedef void(* otDnsServiceCallback) (otError aError, const otDnsServiceResponse *aResponse, void *aContext) )(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.

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

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.

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.

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

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.

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

Returns

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

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.

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.

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.

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.

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 t