Docs › APIs › Network Socket › DNS Resolver

DNS Resolver

DNS class hierarchy

The DNS resolver provides an interface to do DNS host name resolutions. You can use DNS host name resolution to convert resource names to IP addresses. You can make DNS host name resolution after connecting the interface. You can use the returned IP address to make the socket connection.

Usage

The DNS resolver supports both blocking and asynchronous DNS host name resolutions.

To make a DNS host name resolution:

Instantiate and connect a network interface.
Call the gethostbyname() function to resolve address.

To make an asynchronous DNS host name resolution:

Create a callback function for asynchronous host name resolution.
Instantiate and connect network interface.
Call the gethostbyname_async() with callback function to resolve address.

To cancel an asynchronous host name resolution:

Store the unique ID that the gethostbyname_async() call returns.
Call the gethostbyname_async_cancel() with a unique ID to cancel the asynchronous address resolution.

Asynchronous operation

The DNS resolver has a cache for the host names and IP addresses. If the host name is found from the cache, the gethostbyname_async() function returns a success right away. The callback is called before the function returns.

If the address is not in the cache, gethostbyname_async() returns an unique ID for the operation. The callback is called after a response arrives from the DNS server on the network or a timeout occurs. You can use the unique ID to cancel the DNS host name resolution if needed.

If gethostbyname_async() returns a failure, the callback is not called.

When designing the callback function, take following considerations into account:

Callback is called from thread context. If the callback takes more than 10ms to execute, it might prevent underlying thread processing. Do not make calls to network operations due to stack size limitations; the callback should not perform expensive operations, such as socket recv/send calls or blocking operations.

DNS resolver class reference

DNS Class Reference

Public Types
typedef mbed::Callback< void(nsapi_error_t result, SocketAddress *address)>	hostbyname_cb_t
	Hostname translation callback for gethostbyname_async. More...

Public Member Functions
virtual nsapi_error_t	gethostbyname (const char host, SocketAddress address, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)=0
	Translate a hostname to an IP address with specific version using network interface name. More...
virtual nsapi_value_or_error_t	gethostbyname_async (const char host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC, const char interface_name=NULL)=0
	Translate a hostname to an IP address (asynchronous) More...
virtual nsapi_error_t	gethostbyname_async_cancel (int id)=0
	Cancel asynchronous hostname translation. More...
virtual nsapi_error_t	add_dns_server (const SocketAddress &address, const char *interface_name=NULL)=0
	Add a domain name server to list of servers to query. More...

DNS resolver example

This DNS resolver example makes asynchronous DNS host name resolution.

main.cppImport into Mbed IDE

#include "mbed.h"
#include "nsapi_types.h"
#include "EthernetInterface.h"
#include "SocketAddress.h"
#include "Semaphore.h"

rtos::Semaphore callback_semaphore;
SocketAddress address;
nsapi_error_t result;

// Callback for asynchronous host name resolution
void hostbyname_callback(nsapi_error_t res, SocketAddress *addr)
{
    // Store result and release semaphore
    result = res;
    address = *addr;
    callback_semaphore.release();
}

int main()
{
    // Initialise network interface
    EthernetInterface eth;
    eth.connect();

    // Initiate asynchronous DNS host name resolution
    eth.gethostbyname_async("www.mbed.com", hostbyname_callback);

    // Wait for callback semaphore
    callback_semaphore.wait();

    // Print result
    printf("Result %s, Address %s\r\n", result == NSAPI_ERROR_OK ? "OK" : "FAIL",
        result == NSAPI_ERROR_OK ? address.get_ip_address() : "NONE");

    // Disconnect network interface
    eth.disconnect();
}

Troubleshooting information

Network interface gethostbyname() and gethostbyname_async() failure causes:

NSAPI_ERROR_DNS_FAILURE indicates that DNS failed to complete successfully. Check the host name and network connection.
NSAPI_ERROR_NO_MEMORY indicates that there was not enough memory on heap to make an address resolution.

Network socket API overview.