nRF5 IoT SDK  v0.9.0
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Domain Name System Client (DNS)

The DNS client module provides the functionality for obtaining DNS AAAA (IPv6) records from the authoritative DNS server. The module performs queries for the IPv6 addresses of the given hostname (e.g. example.com).

Each query can be assigned with a separate application callback that informs about the IPv6 addresses found, DNS frame error or DNS Server problem.

The module realizes a retry mechanism to improve chances of resolving the DNS Query. The number of retries is configurable using the DNS6_MAX_RETRANSMISSION_COUNT. The interval between retries is determined by the configurable parameter DNS6_RETRANSMISSION_INTERVAL. Therefore, an application can expect to wait for ((DNS6_MAX_RETRANSMISSION_COUNT + 1) * DNS6_RETRANSMISSION_INTERVAL) before the query is resolved. If no response is received after the maximum number of retries, the application is notified of process result DNS6_SERVER_UNREACHABLE in the event notification callback.

Note
The DNS module is implemented on top of the UDP module. Therefore, an additional UDP socket has to be allocated for the DNS module to work.
The retry mechanism requires the IoT Timer module to be present.

Asynchronous Event Notification Callback on query

The user DNS callback informs about the internal process result, which can be either NRF_SUCCESS or one of the following errors:

Process result Description
DNS6_SERVER_UNREACHABLE No response from the DNS Server has been received.
DNS6_FORMAT_ERROR The DNS Server was unable to interpret the query.
DNS6_SERVER_FAILURE The DNS Server was unable to process the query.
DNS6_HOSTNAME_NOT_FOUND No IPv6 addresses have been found.
DNS6_NOT_IMPLEMENTED The DNS Server does not support the requested kind of query.
DNS6_REFUSED_ERROR The DNS Server refuses to perform the query.
DNS6_RESPONSE_TRUNCATED Response from the DNS Server is truncated.
Other In case the DNS module is not the source of an error.

Code examples

Initialization of the DNS Module

This code example shows how to set up the DNS Client in order to send a DNS Query and receive responses. In the example below, Google's DNS Server is used.

void app_dns_client_init(void)
{
uint32_t err_code;
// Configure DNS Client and Server parameters.
dns6_init_t dns_init_param =
{
.local_src_port = 0x8888,
.dns_server =
{
.port = 53,
.addr = {{0x20, 0x01, 0x48, 0x60, 0x48, 0x60, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x88, 0x88}}
}
};
// Init DNS client.
err_code = dns6_init(&dns_init_param);
}

DNS Query to obtain the IPv6 address of example.com domain.

This code example shows how to send a DNS Query for resolving the given hostname. The application is informed about the status of the DNS process in a user-defined function.

void app_dns_handler(uint32_t process_result,
const char * p_hostname,
ipv6_addr_t * p_addr,
uint16_t addr_count)
{
uint32_t index;
APPL_LOG("\r\nDNS Response for hostname: %s, with %d IPv6 addresses and status 0x%08lX\r\n",
p_hostname, addr_count, process_result);
if(process_result == NRF_SUCCESS)
{
for (index = 0; index < addr_count; index++)
{
APPL_LOG("[%d] IPv6 Address: ", index);
APPL_ADDR(p_addr[index]);
}
}
}
void app_resolve(void)
{
// Find all IPv6 addresses correspond to example.com domain.
err_code = dns6_query("example.com", app_dns_handler);
}

Configuration parameters

The following configuration parameters should be defined in sdk_config.h.

DNS6_DISABLE_LOGS

Disables debug tracing in the module. To enable tracing, this flag must be set to 0 and ENABLE_DEBUG_LOG_SUPPORT must be set to 1.

Description Value
Enable debug trace 0
Disable debug trace 1
Dependencies ENABLE_DEBUG_LOG_SUPPORT

DNS6_DISABLE_API_PARAM_CHECK

Disables API parameter checks in the module. Set this define to 1 to disable checks on API parameters in the module.

API parameter checks are added to ensure that the correct parameters are passed to the module. These checks are useful during development phase, but they might be redundant when the application is finalized. Disabling these checks might improve performance.

Description Value
Enable API parameters check 0
Disable API parameters check 1
Dependencies None

DNS6_MAX_PENDING_QUERIES

Maximum number of pending queries in a queue.

Description Value
Minimum value 1
Maximum value 65534
Dependencies None

DNS6_MAX_RETRANSMISSION_COUNT

Maximum number of retransmissions on a single query. Set this define to 0 to disable retransmission attempts.

Description Value
Minimum value 0
Maximum value 255
Dependencies None

DNS6_RETRANSMISSION_INTERVAL

Interval between retransmissions in seconds.

Description Value
Minimum value 2
Maximum value None
Dependencies None