Mistake on this page?
Report an issue in GitHub or email us

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.


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

To make a DNS host name resolution:

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

To make an asynchronous DNS host name resolution:

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

To cancel an asynchronous host name resolution:

  1. Store the unique ID that the gethostbyname_async() call returns.
  2. 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

Public Types
typedef mbed::Callback< void(nsapi_value_or_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 getaddrinfo (const char *hostname, SocketAddress *hints, SocketAddress **res, const char *interface_name=NULL)=0
 Translate a hostname to the multiple IP addresses 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_value_or_error_t getaddrinfo_async (const char *hostname, SocketAddress *hints, hostbyname_cb_t callback, const char *interface_name=NULL)=0
 Translate a hostname to the multiple IP addresses (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.

 * Copyright (c) 2006-2020 Arm Limited and affiliates.
 * SPDX-License-Identifier: Apache-2.0
#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;

int main()
    // Initialise network interface
    EthernetInterface eth;

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

    // Wait for callback semaphore

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

    // Disconnect network interface

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.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.