DNS

DNS

lwIP DNS Overview

The lwIP stack provides a basic DNS client (introduced in 1.3.0) to allow other applications to resolve host names to addresses using the DNS (Domain Name System) protocol. LWIP_DNS must be #defined in lwipopts.h to a nonzero value to enable DNS support in your lwIP platform.

if DHCP is used in conjunction with the lwIP DNS client, DNS will automatically be configured to use the offered DNS server (if the DHCP server offers one).

Application DNS requests with Raw/Native API

Raw API applications can use the dns_gethostbyname() function to request a lookup, and specify a callback function to notify the application when the lookup is complete. As you can see from its header bellow, this function will return immediately. If the requested address is already known, it will be returned via the passed argument pointer. If a request to a DNS server needs to be made, your callback function will be called when it has finshed.

---

* err_t
* dns_gethostbyname(const char *hostname, struct ip_addr *addr, dns_found_callback found,
*                  void *callback_arg)
*
* Resolve a hostname (string) into an IP address.
* NON-BLOCKING callback version for use with raw API!!!
*
* Returns immediately with one of err_t return codes:
* - ERR_OK if hostname is a valid IP address string or the host
*   name is already in the local names table.
* - ERR_INPROGRESS enqueue a request to be sent to the DNS server
*   for resolution if no errors are present.
*
* @param hostname the hostname that is to be queried
* @param addr pointer to a struct ip_addr where to store the address if it is already
*             cached in the dns_table (only valid if ERR_OK is returned!)
* @param found a callback function to be called on success, failure or timeout (only if
*              ERR_INPROGRESS is returned!)
* @param callback_arg argument to pass to the callback function
*    callback function and argument defined as follows:
*     A function of this type must be implemented by the application using the DNS resolver.
*      @param name pointer to the name that was looked up.
*      @param ipaddr pointer to a struct ip_addr containing the IP address of the hostname,
*        or NULL if the name could not be found (or on any other error).
*      @param callback_arg a user-specified callback argument passed to dns_gethostbyname: 
*
* typedef void (*dns_found_callback)(const char *name, struct ip_addr *ipaddr, void *callback_arg);

A sample call:

  struct ip_addr resolved;

  switch(dns_gethostbyname("www.lwIP.com", &resolved, smtp_serverFound, NULL)){
  case ERR_OK:
    // numeric or cached, returned in resolved
    smtp.serverIP.addr = resolved->addr;
    smtp.state = SMTP_NAME_RESOLVED;
    break;
  case ERR_INPROGRESS:
    // need to ask, will return data via callback
    smtp.state = SMTP_NAME_RESOLVING;
    break;
  default:
    // bad arguments in function call
    break;
  }

A sample DNS callback function:

void smtp_serverFound(const char *name, struct ip_addr *ipaddr, void *arg)
{
  if ((ipaddr) && (ipaddr->addr))
  {
    smtp.serverIP.addr = ipaddr->addr;
    smtp.state = SMTP_NAME_RESOLVED;
    if (smtp_connect() == ERR_OK)
      return;
    smtp.lastError = SMTP_CONNECT_FAILED;
  }
  else
    smtp.lastError = SMTP_UNKNOWN_HOST;
  smtp.state = SMTP_IDLE;
}

Application DNS requests with Netconn API

err_t netconn_gethostbyname(const char *name, ip_addr_t *addr)

See also netconn_gethostbyname().

Application DNS requests with Sockets API

For socket based apps, a gethostbyname() wrapper function is provided that blocks during the lookup if necessary. Use the following functions:

• gethostbyname() - standard implementation, blocks if necessary until lookup complete or fails
• gethostbyname_r() - thread-safe version of gethostbyname (separate buffer for each invocation)

External References

DNS-related RFCs

Revisions

• Local static host lookup table support (added in 1.3.1)
• Return multiple IP addresses (future)
• Return other RR (record) types e.g. MX, SRV... (future)
• implement a "Dynamic DNS update" message (future)