stm32plus::net DNS client module
The Domain Name System (DNS) is the part of the internet responsible for mapping friendly names such as ‘www.google.com’ to IP addresses such as ‘173.194.113.177’. The internet’s transport and network layers do not understand names and so the DNS is required whenever an application wants to communicate with a named host.
All of the stm32plus::net transport APIs such as UDP and TCP require you to know the IP address of the host that you want to communicate with. On a fixed network you may already know those addresses, but if you want to communicate with the internet then this DNS ‘resolver’ module is what you need to use to map a friendly name to an address that you can use with a transport.
DNS implementation
The stm32plus::net DNS implementation presents a straightforward, synchronous API that you can call to get an IP address corresponding to a name.
The module depends on you having assigned at least one DNS server. This will happen automatically if you have included either the Dhcp or the StaticIpClient module into your application layer.
Here’s an example application layer configuration including just the DNS module:
typedef ApplicationLayer<Dns> MyApplicationLayer;
Note that this code fragment only shows DNS in the application layer. As discussed above, you must have also included Dhcp or StaticIpClient
Configuration Parameters
The following parameters are made available in the stack’s configuration object for customisation:
// 10000ms is the default. don't go less than 5000 according to RFC 1123 uint32_t dns_timeout; // DNS cache size (default is 20) uint32_t dns_cacheSize; // number of times to retry all servers (default is 5) uint8_t dns_retries;
dns_timeout is the number of milliseconds to wait for a response from your DNS server. A DNS query can result in a chain of requests across the internet so it is wise to give this a generous timeout.
Entries successfully resolved by the DNS are cached for a period of timed defined by the server that resolved the request. The maximum number of entries in the cache is defined by the dns_cacheSize parameter. When the cache is full, the entry nearest its expiry time is evicted to make room for the new entry.
If dns_timeout expires then the next entry in your list of DNS servers is tried, and so on until the last server is tried. dns_retries is the number of times that the module will loop back around all your DNS servers before giving up and failing the call.
Methods exposed by the DNS service
The DNS module exposes a single method that you can use:
bool dnsHostnameQuery(const char *hostname,IpAddress& ipAddress);
This straightforward method expects a host name the first parameter, for example www.google.co.uk and, in the event of success will return the corresponding IP address in the ipAddress output parameter.
Related examples
The net_dns example shows how to use this module to lookup the IP address for an internet host name.
