Network Component  Version 7.10.0
MDK Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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. More...
 

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]. More...
 
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]. More...
 
netStatus netDNSc_ClearCache (void)
 Flush or clear the local DNS cache. [thread-safe]. More...
 

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) {
// Host Address successfully resolved.
netIP_ntoa (addr->addr_type, addr->addr, ip_ascii, sizeof (ip_ascii));
printf ("IP Address: %s\n", ip_ascii)
break;
// All DNS Resolver retries used up and timeouts expired.
printf ("DNS Resolver Timeout expired, Host Address not resolved.\n");
break;
// Host Name does not exist in DNS record database.
printf ("Host name does not exist.\n");
break;
// 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

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

DNS Client Event callback function.

Parameters
[in]eventDNS client event type as defined in netDNSc_Event.
[in]addrPointer 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:

Code Example

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

Function Documentation

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

// All entries flushed from DNS cache
}
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]namehostname, a null-terminated string.
[in]addr_typenetwork address type to resolve:
  • NET_ADDR_IP4 = IPv4 address.
  • NET_ADDR_IP6 = IPv6 address.
[in]cb_funccallback 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) {
// Host Address successfully resolved
netIP_ntoa (addr->addr_type, adr->addr, ip_ascii, sizeof(ip_ascii));
printf("IP Address: %s\n", ip_ascii);
break;
// Error, host name does not exist in DNS record database
break;
// Error, DNS resolver timeout expired
break;
// Error, DNS protocol error occurred
break;
}
}
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]namehostname, a null-terminated string.
[in]addr_typenetwork address type to resolve:
  • NET_ADDR_IP4 = IPv4 address.
  • NET_ADDR_IP6 = IPv6 address.
[out]addrstructure 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.

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);
}