DNS

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

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