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

Table of Contents