DNS
APIs » "raw" APIs

## Functions

void | dns_setserver (u8_t numdns, const ip_addr_t *dnsserver)
const ip_addr_t * | dns_getserver (u8_t numdns)
err_t | dns_gethostbyname (const char *hostname, ip_addr_t *addr, dns_found_callback found, void *callback_arg)
err_t | dns_gethostbyname_addrtype (const char *hostname, ip_addr_t *addr, dns_found_callback found, void *callback_arg, u8_t dns_addrtype)

## Detailed Description

Implements a DNS host name to IP address resolver.

The lwIP DNS resolver functions are used to lookup a host name and map it to a numerical IP address. It maintains a list of resolved hostnames that can be queried with the dns_lookup() function. New hostnames can be resolved using the dns_query() function.

The lwIP version of the resolver also adds a non-blocking version of gethostbyname() that will work with a raw API application. This function checks for an IP address string first and converts it if it is valid. gethostbyname() then does a dns_lookup() to see if the name is already in the table. If so, the IP is returned. If not, a query is issued and the function returns with a ERR_INPROGRESS status. The app using the dns client must then go into a waiting state.

Once a hostname has been resolved (or found to be non-existent), the resolver code calls a specified callback function (which must be implemented by the module that uses the resolver).

Multicast DNS queries are supported for names ending on ".local". However, only "One-Shot Multicast DNS Queries" are supported (RFC 6762 chapter 5.1), this is not a fully compliant implementation of continuous mDNS querying!

All functions must be called from TCPIP thread.

See also
  DNS_MAX_SERVERS
  LWIP_DHCP_MAX_DNS_SERVERS
  Common functions for thread-safe access.

## Function Documentation

## dns_gethostbyname()

err_t dns_gethostbyname | ( | const char * | hostname,
|  | ip_addr_t * | 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.
- ERR_ARG: dns client not initialized or invalid hostname

Parameters

  hostname | the hostname that is to be queried
  addr | pointer to a ip_addr_t where to store the address if it is already cached in the dns_table (only valid if ERR_OK is returned!)
  found | a callback function to be called on success, failure or timeout (only if ERR_INPROGRESS is returned!)
  callback_arg | argument to pass to the callback function

Returns
  a err_t return code.

## dns_gethostbyname_addrtype()

err_t dns_gethostbyname_addrtype | ( | const char * | hostname,
|  | ip_addr_t * | addr,
|  | dns_found_callback | found,
|  | void * | callback_arg,
|  | u8_t | dns_addrtype
| ) |  |

Like dns_gethostbyname, but returned address type can be controlled:

Parameters

  hostname | the hostname that is to be queried
  addr | pointer to a ip_addr_t where to store the address if it is already cached in the dns_table (only valid if ERR_OK is returned!)
  found | a callback function to be called on success, failure or timeout (only if ERR_INPROGRESS is returned!)
  callback_arg | argument to pass to the callback function

  dns_addrtype

  - LWIP_DNS_ADDRTYPE_IPV4_IPV6: try to resolve IPv4 first, try IPv6 if IPv4 fails only
  - LWIP_DNS_ADDRTYPE_IPV6_IPV4: try to resolve IPv6 first, try IPv4 if IPv6 fails only
  - LWIP_DNS_ADDRTYPE_IPV4: try to resolve IPv4 only
  - LWIP_DNS_ADDRTYPE_IPV6: try to resolve IPv6 only

## dns_getserver()

const ip_addr_t* dns_getserver | ( | u8_t | numdns | ) |

Obtain one of the currently configured DNS server.

Parameters

  numdns | the index of the DNS server

Returns
  IP address of the indexed DNS server or "ip_addr_any" if the DNS server has not been configured.

## dns_setserver()

void dns_setserver | ( | u8_t | numdns,
|  | const ip_addr_t * | dnsserver
| ) |  |

Initialize one of the DNS servers.

Parameters

  numdns | the index of the DNS server to set must be < DNS_MAX_SERVERS
  dnsserver | IP address of the DNS server to set