lwIP  2.1.0
Lightweight IP stack

Functions

void dns_setserver (u8_t numdns, const ip_addr_t *dnsserver)
 
const ip_addr_tdns_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
hostnamethe hostname that is to be queried
addrpointer 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!)
founda callback function to be called on success, failure or timeout (only if ERR_INPROGRESS is returned!)
callback_argargument 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
hostnamethe hostname that is to be queried
addrpointer 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!)
founda callback function to be called on success, failure or timeout (only if ERR_INPROGRESS is returned!)
callback_argargument 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
numdnsthe 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
numdnsthe index of the DNS server to set must be < DNS_MAX_SERVERS
dnsserverIP address of the DNS server to set