Control Interface

Functions to start the DNS Client. More...

Typedefs
typedef void(*	netDNSc_cb_t) (netDNSc_Event event, const NET_ADDR *addr)
	DNS Client Event callback function.

Functions
netStatus	netDNSc_GetHostByName (const char *name, int16_t addr_type, netDNSc_cb_t cb_func)
	Resolve IP address of a host from a hostname. [thread-safe].
netStatus	netDNSc_GetHostByNameX (const char *name, int16_t addr_type, NET_ADDR *addr)
	Resolve IP address of a host from a hostname in blocking mode. [thread-safe].
netStatus	netDNSc_ClearCache (void)
	Flush or clear the local DNS cache. [thread-safe].

Description

Functions to start the DNS Client.

Start the DNS Client by calling the function netDNSc_GetHostByName. DNS requests are routed to the DNS Server IP address of an active network interface. If you are using a PPP or SLIP interface and no Ethernet Interface interface, you must enable the "Use default Gateway on remote Network" option in the configuration file (Net_Config_PPP.h or Net_Config_SLIP.h).

You must also specify a callback function, which is called from the DNS Client when a DNS event occurs.

static void dns_cbfunc (netDNSc_Event event, const NET_ADDR *addr) {
  char ip_ascii[40];
 
  switch (event) {
    case netDNSc_EventSuccess:
      // Host Address successfully resolved.
      netIP_ntoa (addr->addr_type, addr->addr, ip_ascii, sizeof (ip_ascii));
      printf ("IP Address: %s\n", ip_ascii)
      break;
    case netDNSc_EventTimeout:
      // All DNS Resolver retries used up and timeouts expired.
      printf ("DNS Resolver Timeout expired, Host Address not resolved.\n");
      break;
    case netDNSc_EventNotResolved:
      // Host Name does not exist in DNS record database.
      printf ("Host name does not exist.\n");
      break;
    case netDNSc_EventError:
      // DNS Protocol Error, invalid or corrupted reply received.
      printf ("DNS Resolver Protocol Error, Host Address not resolved.\n");
      break;
  }
}

When the required host is found in the local DNS Cache, the callback function is called immediately with the result code netDNSc_EventSuccess and provides the IP address of the host to the function. In this case, no actual DNS request packet is sent to the remote DNS Server.

Note

You can also provide the IP address in a string format to specify the host name. The DNS Client decodes it and returns the decoded IP address to the callback function.

Typedef Documentation

netDNSc_cb_t

void(* netDNSc_cb_t)(netDNSc_Event event, const NET_ADDR *addr)

DNS Client Event callback function.

Parameters

[in]	event	DNS client event type as defined in netDNSc_Event.
[in]	addr	Pointer to the structure containing resolved IP address of the host name.

Returns

none.

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 netDNSc_EventSuccess) when calling the function.

Parameter for:

• netDNSc_GetHostByName

Code Example

static void dns_cbfunc (netDNSc_Event event, const NET_ADDR *addr) {
  char ip_ascii[40];
  
  switch (event) {
    case netDNSc_EventSuccess:
      // Host Address successfully resolved
      netIP_ntoa (addr->addr_type, adr->addr, ip_ascii, sizeof(ip_ascii));
      printf("IP Address: %s\n", ip_ascii);
      break;
 
    case netDNSc_EventNotResolved:
      // Error, host name does not exist in DNS record database
      break;
 
    case netDNSc_EventTimeout:
      // Error, DNS resolver timeout expired
      break;
 
    case netDNSc_EventError:
      // Error, DNS protocol error occurred
      break;
  }
}

Function Documentation

netDNSc_ClearCache()

netStatus netDNSc_ClearCache

(

void

)

Flush or clear the local DNS cache. [thread-safe].

Returns

status code that indicates the execution status of the function.

The function netDNSc_ClearCache flushes all resolved IP addresses from the local DNS cache. You can use this function when the cache holds outdated values that are no longer valid.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netBusy: DNS client is busy.

Code Example

if (netDNSc_ClearCache () == netOK) {
  // All entries flushed from DNS cache
}

netDNSc_GetHostByName()

netStatus netDNSc_GetHostByName	(	const char *	name,
		int16_t	addr_type,
		netDNSc_cb_t	cb_func
	)

Resolve IP address of a host from a hostname. [thread-safe].

Parameters

[in]	name	hostname, a null-terminated string.
[in]	addr_type	network address type to resolve: NET_ADDR_IP4 = IPv4 address. NET_ADDR_IP6 = IPv6 address.
[in]	cb_func	callback function to call, when DNS session ends.

Returns

status code that indicates the execution status of the function.

The non-blocking function netDNSc_GetHostByName 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 name can also point to the dotted decimal IPv4 address in string format (for example "192.168.0.100"), or to the hexadecimal IPv6 address in string format (for example "2001:4860:4860::8888"). In this case, the DNS client calls the cb_func function immediately with the IP address. The argument name can also be "localhost", in this case the DNS client calls the cb_func function immediately with the loopback IP address: "127.0.0.1" for IPv4 or "::1" for IPv6.

The argument addr_type specifies the type of address to resolve. It is NET_ADDR_IP4 when you want to resolve an IPv4 address, and NET_ADDR_IP6 when you want to resolve an IPv6 address.

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

Possible netStatus return values:

• netOK: DNS client started successfully.
• netInvalidParameter: Invalid parameter provided.
• netBusy: DNS client is busy.
• netServerError: DNS server IP address undefined.

Note

The function netDNSc_GetHostByName is deprecated, use the netDNSc_GetHostByNameX function instead.

Code Example

static void dns_cbfunc (netDNSc_Event event, const NET_ADDR *addr);
 
if (netDNSc_GetHostByName ("www.arm.com", NET_ADDR_IP4, dns_cbfunc) == netOK) {
  // Started, will complete on callback notification
}
 
static void dns_cbfunc (netDNSc_Event event, const NET_ADDR *addr) {
  char ip_ascii[40];
  
  switch (event) {
    case netDNSc_EventSuccess:
      // Host Address successfully resolved
      netIP_ntoa (addr->addr_type, adr->addr, ip_ascii, sizeof(ip_ascii));
      printf("IP Address: %s\n", ip_ascii);
      break;
 
    case netDNSc_EventNotResolved:
      // Error, host name does not exist in DNS record database
      break;
 
    case netDNSc_EventTimeout:
      // Error, DNS resolver timeout expired
      break;
 
    case netDNSc_EventError:
      // Error, DNS protocol error occurred
      break;
  }
}

netDNSc_GetHostByNameX()

netStatus netDNSc_GetHostByNameX	(	const char *	name,
		int16_t	addr_type,
		NET_ADDR *	addr
	)

Resolve IP address of a host from a hostname in blocking mode. [thread-safe].

Parameters

[in]	name	hostname, a null-terminated string.
[in]	addr_type	network address type to resolve: NET_ADDR_IP4 = IPv4 address. NET_ADDR_IP6 = IPv6 address.
[out]	addr	structure that will receive resolved IP address of the hostname.

Returns

status code that indicates the execution status of the function.

The blocking function netDNSc_GetHostByNameX resolves the IP address of a host from a host name. It starts the DNS client, sends a request to the DNS server and returns the resolved IP address.

The argument name is a pointer to a null-terminated string that specifies the host name. The argument name can also point to the dotted decimal IPv4 address in string format (for example "192.168.0.100"), or to the hexadecimal IPv6 address in string format (for example "2001:4860:4860::8888"). In this case, the DNS client calls the cb_func function immediately with the IP address. The argument name can also be "localhost", in this case the DNS client calls the cb_func function immediately with the loopback IP address: "127.0.0.1" for IPv4 or "::1" for IPv6.

The argument addr_type specifies the type of address to resolve. It is NET_ADDR_IP4 when you want to resolve an IPv4 address, and NET_ADDR_IP6 when you want to resolve an IPv6 address.

The argument addr specifies a user-provided NET_ADDR address structure that will receive the resolved IP address.

Possible netStatus return values:

• netOK: Host name successfully resolved.
• netInvalidParameter: Invalid parameter provided.
• netDnsResolverError: Host name not existing.
• netTimeout: DNS server not responding.
• netServerError: DNS server IP address undefined.
• netError: DNS protocol error occurred.

Code Example

NET_ADDR addr;
char ip_ascii[40];
 
if (netDNSc_GetHostByNameX ("www.arm.com", NET_ADDR_IP4, &addr) == netOK) {
  // Success, 'addr' holds resolved IP address
  netIP_ntoa (addr->addr_type, adr->addr, ip_ascii, sizeof(ip_ascii));
  printf("IP Address: %s\n", ip_ascii);
}