Arduino Ethernet DNS

Arduino Ethernet Libs

Download Version History

DNS with Arduino

A small library capable of sending and parsing DNS traffic (Wikipedia) to discover the IP address of a host name. This way, you do not need to go into the error-prone process of hardcoding host IP addresses into your Arduino Ethernet sketch, but rather have them resolved on the fly at runtime.

This is incredibly useful for all sorts of sketches that interact with the web, such as those that post certain data to a server or download data from a web site.

Documentation

The library ships with 2 extensively commented examples, but here's an additional run-down of the public methods. Nevertheless, I suggest to have a look at the examples for a short introduction to the library.

void setDNSServer(const byte dnsServerIpAddr[4]);

Use setDNSServer() to specify the IP address of the DNS server you want to use. If you want to use your own DNS server, you should call this before making your first actual request. The default setting is 8.8.8.8, which is one of Google's public DNS servers.

Especially if you are behind a NAT router, you will want to use your own setting here (usually your router's IP address). If you use this library in conjunction with my Ethernet DHCP library, you should set the IP address of the DNS server given to you with your DHCP lease.

DNSError resolveHostName(const char* hostName, byte ipAddr[4]);

resolveHostName() looks up the host specified in the first argument and puts its IP address into the the memory pointed to by the second argument (4 bytes). It will block your sketch until the name has been resolved, an error has been reported by the DNS server or a timeout of 5 seconds has elapsed.

The method returns a constant describing the outcome of the request. It is one of the following values: DNSSuccess, DNSInvalidArgument, DNSOutOfMemory, DNSSocketError, DNSAlreadyProcessingQuery, DNSNotFound, DNSServerError, DNSTimedOut, denoting either success or the cause of the error. Note that DNSServerError is returned whenever the DNS server did not respond with an IP address, not only on "real" DNS server errors.

DNSError sendDNSQuery(const char* hostName);
DNSError pollDNSReply(byte ipAddr[4]);

sendDNSQuery() and pollDNSReply() can be used to resolve a host name without blocking your sketch: The idea is that you first call sendDNSQuery() to send off your DNS request, then keep calling pollDNSReply() once per loop-iteration until either an error or success is returned.

The potential return values of sendDNSQuery() are the same as for resolveHostName(). pollDNSReply() has two additional possible return values: DNSNothingToDo, which is returned when you poll the DNS module for a reply without having sent a query first, and DNSTryLater, which means that a response from the server has not yet been received, so you should call pollDNSReply() again at a later time. If a response has not been received after 5 seconds, pollDNSReply() will return DNSTimedOut, rather than waiting indefinitely. You could then try to resend your request.

To sum it up, the process of using polling to resolve a host name is to first call sendDNSQuery(), check that it returned DNSSuccess, then keep calling pollDNSReply() until it does not return DNSTryLater anymore. If the return value was DNSSuccess, the IP address is stored in the memory region provided by you, otherwise an error has occurred.

Notes a.k.a. "Things you should know"