DNS Client routines help to resolve DNS requests using an external DNS server. More...

Functions
netStatus	get_host_by_name (const char *name, net_dns_client_cb_t cb_func)
	Resolve IP address of a host from a hostname.

enum	dnsClientEvent { dnsClientSuccess = 0, dnsClientTimeout, dnsClientNotResolved, dnsClientError }
	DNS Client Callback Events. More...

typedef void(*	net_dns_client_cb_t )(dnsClientEvent event, const uint8_t *ip_addr)
	DNS Client Event callback function.

Description

DNS Client routines help to resolve DNS requests using an external DNS server.

Domain Name System (DNS) servers store and manage information about domains and respond to resolution requests for clients (in some cases millions of times each day). The DNS database is a distributed name database stored on many DNS servers. DNS uses a hierarchical tree structure for its name space and a hierarchical tree for name authorities and registration.

The DNS Client is capable of resolving the IP address of a host from the host's name. It does this by sending DNS requests to a DNS Server. The IP address of a DNS Server is specified in the network interface configuration file or can be obtained from the DHCP Server for the Local Area Network.

Note: The page DNS Client gives you more information on the actual usage of the functions and how to work with them in a project.

Code Examples

DNS Resolution Example

#include <stdio.h>
#include "cmsis_os.h"       // CMSIS RTOS definitions
#include "rl_net.h"         // Network definitions
 
const char *hosts[] = {
  "www.google.com",
  "www.keil.com",
  "www.microsoft.com",
  "www.yahoo.com",
  "192.168.0.253"
};
 
unsigned int idx;
 
// Select next host from the table. 
static void next_host () {
  if (++idx == sizeof(hosts)/sizeof(hosts[0])) {
    idx = 0;
  }
}
 
// This function is called by the DNS client when dns event occurs.
static void dns_cbfunc (dnsClientEvent event, const uint8_t *ip_addr) {
  switch (event) {
    case dnsClientSuccess:
      // Host Address successfully resolved.
      printf("IP Address : %d.%d.%d.%d\n", ip_addr[0], ip_addr[1], ip_addr[2], ip_addr[3]);
      next_host();
      break;
    case dnsClientNotResolved:
      // Host Name does not exist in DNS record database.
      printf("Host name does not exist.\n");
      next_host();
      break;
    case dnsClientTimeout:
      // All DNS Resolver retries used up and timeouts expired.
      printf("DNS Resolver Timeout expired, Host Address not resolved.\n");
      break;
    case dnsClientError:
      // DNS Protocol Error, invalid or corrupted reply received.
      printf("DNS Resolver Protocol Error, Host Address not resolved.\n");
      break;
  }
}
 
int main (void) {
  netStatus res;
  idx = 0;
 
  while (1) {
    ...
    res = get_host_by_name (hosts[idx], dns_cbfunc);
    switch (res) {
      case netOK:
        // Resolver started, wait for callback event.
        break;
      case netBusy:
        // Busy, retry on next tick.
        break;
      case netInvalidParameter:
        printf ("Invalid parameters!\n");
        next_host();
        break;
      case netServerError:
        printf ("DNS Server unknown!\n");
        break;
      default:
        // catch other enumeration values
        break;
    }
  }
}

Typedef Documentation

void(* net_dns_client_cb_t)(dnsClientEvent event, const uint8_t *ip_addr)

DNS Client Event callback function.

Parameters

[in]	event	DNS client event type as defined in dnsClientEvent.
[in]	ip_addr	IP address of the host server.

Is the type definition for the DNS callback function. The function is invoked by the DNS client when an event ends the DNS session. The DNS client specifies the event and the host IP address (in case of dnsClientSuccess) when calling the function.

Parameter for:

get_host_by_name

Enumeration Type Documentation

enum dnsClientEvent

DNS Client Callback Events.

Parameter for:

net_dns_client_cb_t

Enumerator:

dnsClientSuccess	Host name successfully resolved.
dnsClientTimeout	Timeout resolving host.
dnsClientNotResolved	DNS Error, no such name.
dnsClientError	Erroneous response packet.

Function Documentation

netStatus get_host_by_name	(	const char *	name,
		net_dns_client_cb_t	cb_func
	)

Resolve IP address of a host from a hostname.

Parameters

[in]	name	hostname, a null-terminated string.
[in]	cb_func	callback function to call, when DNS session ends.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function get_host_by_name resolves the IP address of a host from a host name. It starts the DNS client and sends a request to the DNS server.

The argument name is a pointer to a NULL terminated string that specifies the host name.

The argument cb_func specifies a user-provided callback function. Refer to net_dns_client_cb_t.

Note: The argument name can also point to the dotted decimal IP address in string format (for example "192.168.0.100"). In this case, the DNS client calls the cb_func function immediately with the IP address.

Code Example